Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/grpc/_runtime_protos.py: 38%

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 else: 

62 if not _is_grpc_tools_importable(): 

63 raise NotImplementedError(_UNINSTALLED_TEMPLATE.format(fn_name)) 

64 import grpc_tools.protoc # pytype: disable=import-error 

65 

66 if _has_runtime_proto_symbols(grpc_tools.protoc): 

67 fn = getattr(grpc_tools.protoc, "_" + fn_name) 

68 return fn(protobuf_path) 

69 raise NotImplementedError(_UNINSTALLED_TEMPLATE.format(fn_name)) 

70 

71 

72def protos(protobuf_path): # pylint: disable=unused-argument 

73 """Returns a module generated by the indicated .proto file. 

74 

75 THIS IS AN EXPERIMENTAL API. 

76 

77 Use this function to retrieve classes corresponding to message 

78 definitions in the .proto file. 

79 

80 To inspect the contents of the returned module, use the dir function. 

81 For example: 

82 

83 ``` 

84 protos = grpc.protos("foo.proto") 

85 print(dir(protos)) 

86 ``` 

87 

88 The returned module object corresponds to the _pb2.py file generated 

89 by protoc. The path is expected to be relative to an entry on sys.path 

90 and all transitive dependencies of the file should also be resolvable 

91 from an entry on sys.path. 

92 

93 To completely disable the machinery behind this function, set the 

94 GRPC_PYTHON_DISABLE_DYNAMIC_STUBS environment variable to "true". 

95 

96 Args: 

97 protobuf_path: The path to the .proto file on the filesystem. This path 

98 must be resolvable from an entry on sys.path and so must all of its 

99 transitive dependencies. 

100 

101 Returns: 

102 A module object corresponding to the message code for the indicated 

103 .proto file. Equivalent to a generated _pb2.py file. 

104 """ 

105 return _call_with_lazy_import("protos", protobuf_path) 

106 

107 

108def services(protobuf_path): # pylint: disable=unused-argument 

109 """Returns a module generated by the indicated .proto file. 

110 

111 THIS IS AN EXPERIMENTAL API. 

112 

113 Use this function to retrieve classes and functions corresponding to 

114 service definitions in the .proto file, including both stub and servicer 

115 definitions. 

116 

117 To inspect the contents of the returned module, use the dir function. 

118 For example: 

119 

120 ``` 

121 services = grpc.services("foo.proto") 

122 print(dir(services)) 

123 ``` 

124 

125 The returned module object corresponds to the _pb2_grpc.py file generated 

126 by protoc. The path is expected to be relative to an entry on sys.path 

127 and all transitive dependencies of the file should also be resolvable 

128 from an entry on sys.path. 

129 

130 To completely disable the machinery behind this function, set the 

131 GRPC_PYTHON_DISABLE_DYNAMIC_STUBS environment variable to "true". 

132 

133 Args: 

134 protobuf_path: The path to the .proto file on the filesystem. This path 

135 must be resolvable from an entry on sys.path and so must all of its 

136 transitive dependencies. 

137 

138 Returns: 

139 A module object corresponding to the stub/service code for the indicated 

140 .proto file. Equivalent to a generated _pb2_grpc.py file. 

141 """ 

142 return _call_with_lazy_import("services", protobuf_path) 

143 

144 

145def protos_and_services(protobuf_path): # pylint: disable=unused-argument 

146 """Returns a 2-tuple of modules corresponding to protos and services. 

147 

148 THIS IS AN EXPERIMENTAL API. 

149 

150 The return value of this function is equivalent to a call to protos and a 

151 call to services. 

152 

153 To completely disable the machinery behind this function, set the 

154 GRPC_PYTHON_DISABLE_DYNAMIC_STUBS environment variable to "true". 

155 

156 Args: 

157 protobuf_path: The path to the .proto file on the filesystem. This path 

158 must be resolvable from an entry on sys.path and so must all of its 

159 transitive dependencies. 

160 

161 Returns: 

162 A 2-tuple of module objects corresponding to (protos(path), services(path)). 

163 """ 

164 return _call_with_lazy_import("protos_and_services", protobuf_path)