• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Copyright 2020 The gRPC authors.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#     http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15import sys
16
17_REQUIRED_SYMBOLS = ("_protos", "_services", "_protos_and_services")
18_MINIMUM_VERSION = (3, 5, 0)
19
20_UNINSTALLED_TEMPLATE = "Install the grpcio-tools package (1.32.0+) to use the {} function."
21_VERSION_ERROR_TEMPLATE = "The {} function is only on available on Python 3.X interpreters."
22
23
24def _has_runtime_proto_symbols(mod):
25    return all(hasattr(mod, sym) for sym in _REQUIRED_SYMBOLS)
26
27
28def _is_grpc_tools_importable():
29    try:
30        import grpc_tools  # pylint: disable=unused-import
31        return True
32    except ImportError as e:
33        # NOTE: It's possible that we're encountering a transitive ImportError, so
34        # we check for that and re-raise if so.
35        if "grpc_tools" not in e.args[0]:
36            raise
37        return False
38
39
40def _call_with_lazy_import(fn_name, protobuf_path):
41    """Calls one of the three functions, lazily importing grpc_tools.
42
43    Args:
44      fn_name: The name of the function to import from grpc_tools.protoc.
45      protobuf_path: The path to import.
46
47    Returns:
48      The appropriate module object.
49    """
50    if sys.version_info < _MINIMUM_VERSION:
51        raise NotImplementedError(_VERSION_ERROR_TEMPLATE.format(fn_name))
52    else:
53        if not _is_grpc_tools_importable():
54            raise NotImplementedError(_UNINSTALLED_TEMPLATE.format(fn_name))
55        import grpc_tools.protoc
56        if _has_runtime_proto_symbols(grpc_tools.protoc):
57            fn = getattr(grpc_tools.protoc, '_' + fn_name)
58            return fn(protobuf_path)
59        else:
60            raise NotImplementedError(_UNINSTALLED_TEMPLATE.format(fn_name))
61
62
63def protos(protobuf_path):  # pylint: disable=unused-argument
64    """Returns a module generated by the indicated .proto file.
65
66    THIS IS AN EXPERIMENTAL API.
67
68    Use this function to retrieve classes corresponding to message
69    definitions in the .proto file.
70
71    To inspect the contents of the returned module, use the dir function.
72    For example:
73
74    ```
75    protos = grpc.protos("foo.proto")
76    print(dir(protos))
77    ```
78
79    The returned module object corresponds to the _pb2.py file generated
80    by protoc. The path is expected to be relative to an entry on sys.path
81    and all transitive dependencies of the file should also be resolveable
82    from an entry on sys.path.
83
84    To completely disable the machinery behind this function, set the
85    GRPC_PYTHON_DISABLE_DYNAMIC_STUBS environment variable to "true".
86
87    Args:
88      protobuf_path: The path to the .proto file on the filesystem. This path
89        must be resolveable from an entry on sys.path and so must all of its
90        transitive dependencies.
91
92    Returns:
93      A module object corresponding to the message code for the indicated
94      .proto file. Equivalent to a generated _pb2.py file.
95    """
96    return _call_with_lazy_import("protos", protobuf_path)
97
98
99def services(protobuf_path):  # pylint: disable=unused-argument
100    """Returns a module generated by the indicated .proto file.
101
102    THIS IS AN EXPERIMENTAL API.
103
104    Use this function to retrieve classes and functions corresponding to
105    service definitions in the .proto file, including both stub and servicer
106    definitions.
107
108    To inspect the contents of the returned module, use the dir function.
109    For example:
110
111    ```
112    services = grpc.services("foo.proto")
113    print(dir(services))
114    ```
115
116    The returned module object corresponds to the _pb2_grpc.py file generated
117    by protoc. The path is expected to be relative to an entry on sys.path
118    and all transitive dependencies of the file should also be resolveable
119    from an entry on sys.path.
120
121    To completely disable the machinery behind this function, set the
122    GRPC_PYTHON_DISABLE_DYNAMIC_STUBS environment variable to "true".
123
124    Args:
125      protobuf_path: The path to the .proto file on the filesystem. This path
126        must be resolveable from an entry on sys.path and so must all of its
127        transitive dependencies.
128
129    Returns:
130      A module object corresponding to the stub/service code for the indicated
131      .proto file. Equivalent to a generated _pb2_grpc.py file.
132    """
133    return _call_with_lazy_import("services", protobuf_path)
134
135
136def protos_and_services(protobuf_path):  # pylint: disable=unused-argument
137    """Returns a 2-tuple of modules corresponding to protos and services.
138
139    THIS IS AN EXPERIMENTAL API.
140
141    The return value of this function is equivalent to a call to protos and a
142    call to services.
143
144    To completely disable the machinery behind this function, set the
145    GRPC_PYTHON_DISABLE_DYNAMIC_STUBS environment variable to "true".
146
147    Args:
148      protobuf_path: The path to the .proto file on the filesystem. This path
149        must be resolveable from an entry on sys.path and so must all of its
150        transitive dependencies.
151
152    Returns:
153      A 2-tuple of module objects corresponding to (protos(path), services(path)).
154    """
155    return _call_with_lazy_import("protos_and_services", protobuf_path)
156