codekingpro/portable-devtools

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
16import types
17from typing import Tuple, Union
18
19_REQUIRED_SYMBOLS = ("_protos", "_services", "_protos_and_services")
20_MINIMUM_VERSION = (3, 5, 0)
21
22_UNINSTALLED_TEMPLATE = (
23    "Install the grpcio-tools package (1.32.0+) to use the {} function."
24)
25_VERSION_ERROR_TEMPLATE = (
26    "The {} function is only on available on Python 3.X interpreters."
27)
28
29
30def _has_runtime_proto_symbols(mod: types.ModuleType) -> bool:
31    return all(hasattr(mod, sym) for sym in _REQUIRED_SYMBOLS)
32
33
34def _is_grpc_tools_importable() -> bool:
35    try:
36        import grpc_tools  # pylint: disable=unused-import # pytype: disable=import-error
37
38        return True
39    except ImportError as e:
40        # NOTE: It's possible that we're encountering a transitive ImportError, so
41        # we check for that and re-raise if so.
42        if "grpc_tools" not in e.args[0]:
43            raise
44        return False
45
46
47def _call_with_lazy_import(
48    fn_name: str, protobuf_path: str
49) -> Union[types.ModuleType, Tuple[types.ModuleType, types.ModuleType]]:
50    """Calls one of the three functions, lazily importing grpc_tools.
51
52    Args:
53      fn_name: The name of the function to import from grpc_tools.protoc.
54      protobuf_path: The path to import.
55
56    Returns:
57      The appropriate module object.
58    """
59    if sys.version_info < _MINIMUM_VERSION:
60        raise NotImplementedError(_VERSION_ERROR_TEMPLATE.format(fn_name))
61    if not _is_grpc_tools_importable():
62        raise NotImplementedError(_UNINSTALLED_TEMPLATE.format(fn_name))
63    import grpc_tools.protoc  # pytype: disable=import-error
64
65    if _has_runtime_proto_symbols(grpc_tools.protoc):
66        fn = getattr(grpc_tools.protoc, "_" + fn_name)
67        return fn(protobuf_path)
68    raise NotImplementedError(_UNINSTALLED_TEMPLATE.format(fn_name))
69
70
71def protos(protobuf_path):  # pylint: disable=unused-argument
72    """Returns a module generated by the indicated .proto file.
73
74    THIS IS AN EXPERIMENTAL API.
75
76    Use this function to retrieve classes corresponding to message
77    definitions in the .proto file.
78
79    To inspect the contents of the returned module, use the dir function.
80    For example:
81
82    ```
83    protos = grpc.protos("foo.proto")
84    print(dir(protos))
85    ```
86
87    The returned module object corresponds to the _pb2.py file generated
88    by protoc. The path is expected to be relative to an entry on sys.path
89    and all transitive dependencies of the file should also be resolvable
90    from an entry on sys.path.
91
92    To completely disable the machinery behind this function, set the
93    GRPC_PYTHON_DISABLE_DYNAMIC_STUBS environment variable to "true".
94
95    Args:
96      protobuf_path: The path to the .proto file on the filesystem. This path
97        must be resolvable from an entry on sys.path and so must all of its
98        transitive dependencies.
99
100    Returns:
101      A module object corresponding to the message code for the indicated
102      .proto file. Equivalent to a generated _pb2.py file.
103    """
104    return _call_with_lazy_import("protos", protobuf_path)
105
106
107def services(protobuf_path):  # pylint: disable=unused-argument
108    """Returns a module generated by the indicated .proto file.
109
110    THIS IS AN EXPERIMENTAL API.
111
112    Use this function to retrieve classes and functions corresponding to
113    service definitions in the .proto file, including both stub and servicer
114    definitions.
115
116    To inspect the contents of the returned module, use the dir function.
117    For example:
118
119    ```
120    services = grpc.services("foo.proto")
121    print(dir(services))
122    ```
123
124    The returned module object corresponds to the _pb2_grpc.py file generated
125    by protoc. The path is expected to be relative to an entry on sys.path
126    and all transitive dependencies of the file should also be resolvable
127    from an entry on sys.path.
128
129    To completely disable the machinery behind this function, set the
130    GRPC_PYTHON_DISABLE_DYNAMIC_STUBS environment variable to "true".
131
132    Args:
133      protobuf_path: The path to the .proto file on the filesystem. This path
134        must be resolvable from an entry on sys.path and so must all of its
135        transitive dependencies.
136
137    Returns:
138      A module object corresponding to the stub/service code for the indicated
139      .proto file. Equivalent to a generated _pb2_grpc.py file.
140    """
141    return _call_with_lazy_import("services", protobuf_path)
142
143
144def protos_and_services(protobuf_path):  # pylint: disable=unused-argument
145    """Returns a 2-tuple of modules corresponding to protos and services.
146
147    THIS IS AN EXPERIMENTAL API.
148
149    The return value of this function is equivalent to a call to protos and a
150    call to services.
151
152    To completely disable the machinery behind this function, set the
153    GRPC_PYTHON_DISABLE_DYNAMIC_STUBS environment variable to "true".
154
155    Args:
156      protobuf_path: The path to the .proto file on the filesystem. This path
157        must be resolvable from an entry on sys.path and so must all of its
158        transitive dependencies.
159
160    Returns:
161      A 2-tuple of module objects corresponding to (protos(path), services(path)).
162    """
163    return _call_with_lazy_import("protos_and_services", protobuf_path)
164