schema
The schema
module provides a normalized API representation.
In general, this module can be considered in three parts: wrappers, metadata, and a roll-up view of an API as a whole.
These three parts are divided into the three component modules.
api
This module contains the “roll-up” class, API
.
Everything else in the schema
module is usually accessed
through an API
object.
- class gapic.schema.api.API(naming: gapic.schema.naming.Naming, all_protos: Mapping[str, gapic.schema.api.Proto], service_yaml_config: google.api.service_pb2.Service, subpackage_view: Tuple[str, ...] = <factory>)[source]
A representation of a full API.
This represents a top-down view of a complete API, as loaded from a set of protocol buffer files. Once the descriptors are loaded (see
load()
), this object contains every message, method, service, and everything else needed to write a client library.An instance of this object is made available to every template (as
api
).- classmethod build(file_descriptors: Sequence[google.protobuf.descriptor_pb2.FileDescriptorProto], package: str = '', opts: gapic.utils.options.Options = Options(name='', namespace=(), warehouse_package_name='', retry=None, sample_configs=(), autogen_snippets=True, templates=('DEFAULT'), lazy_import=False, old_naming=False, add_iam_methods=False, metadata=False, transport=[], service_yaml_config={}, PYTHON_GAPIC_PREFIX='python-gapic-', OPT_FLAGS=frozenset({'retry-config', 'old-naming', 'autogen-snippets', 'warehouse-package-name', 'service-yaml', 'add-iam-methods', 'lazy-import', 'samples', 'transport', 'metadata'})), prior_protos: Optional[Mapping[str, gapic.schema.api.Proto]] = None) → gapic.schema.api.API[source]
Build the internal API schema based on the request.
- Parameters
file_descriptors (Sequence[FileDescriptorProto]) – A list of
FileDescriptorProto
objects describing the API.package (str) – A protocol buffer package, as a string, for which code should be explicitly generated (including subpackages). Protos with packages outside this list are considered imports rather than explicit targets.
opts (Options) – CLI options passed to the generator.
prior_protos (Proto) – Previous, already processed protos. These are needed to look up messages in imported protos. Primarily used for testing.
- property enums: Mapping[str, gapic.schema.wrappers.EnumType]
Return a map of all enums available in the API.
- get_custom_operation_service(method: gapic.schema.wrappers.Method) → gapic.schema.wrappers.Service[source]
Return the extended operation service that should be polled for progress from a given initial method.
Precondition: method returns an Extended Operation type message and has an operation_polling_service annotation.
- get_extended_operations_services(service) → Set[gapic.schema.wrappers.Service][source]
Return a set of all the extended operation services used by the input service.
Precondition: service is NOT an extended operation service
- property http_options: Mapping[str, Sequence[gapic.schema.wrappers.HttpRule]]
Return a map of API-wide http rules.
- property messages: Mapping[str, gapic.schema.wrappers.MessageType]
Return a map of all messages available in the API.
- property protos: Mapping[str, gapic.schema.api.Proto]
Return a map of all protos specific to this API.
This property excludes imported protos that are dependencies of this API but not being directly generated.
- property services: Mapping[str, gapic.schema.wrappers.Service]
Return a map of all services available in the API.
- property subpackages: Mapping[str, gapic.schema.api.API]
Return a map of all subpackages, if any.
Each value in the mapping is another API object, but the
protos
property only shows protos belonging to the subpackage.
- property top_level_enums: Mapping[str, gapic.schema.wrappers.EnumType]
Return a map of all messages that are NOT nested.
- property top_level_messages: Mapping[str, gapic.schema.wrappers.MessageType]
Return a map of all messages that are NOT nested.
- class gapic.schema.api.Proto(file_pb2: google.protobuf.descriptor_pb2.FileDescriptorProto, services: Mapping[str, gapic.schema.wrappers.Service], all_messages: Mapping[str, gapic.schema.wrappers.MessageType], all_enums: Mapping[str, gapic.schema.wrappers.EnumType], file_to_generate: bool, meta: gapic.schema.metadata.Metadata = <factory>)[source]
A representation of a particular proto file within an API.
- classmethod build(file_descriptor: google.protobuf.descriptor_pb2.FileDescriptorProto, file_to_generate: bool, naming: gapic.schema.naming.Naming, opts: gapic.utils.options.Options = Options(name='', namespace=(), warehouse_package_name='', retry=None, sample_configs=(), autogen_snippets=True, templates=('DEFAULT'), lazy_import=False, old_naming=False, add_iam_methods=False, metadata=False, transport=[], service_yaml_config={}, PYTHON_GAPIC_PREFIX='python-gapic-', OPT_FLAGS=frozenset({'retry-config', 'old-naming', 'autogen-snippets', 'warehouse-package-name', 'service-yaml', 'add-iam-methods', 'lazy-import', 'samples', 'transport', 'metadata'})), prior_protos: Optional[Mapping[str, gapic.schema.api.Proto]] = None, load_services: bool = True, all_resources: Optional[Mapping[str, gapic.schema.wrappers.MessageType]] = None) → gapic.schema.api.Proto[source]
Build and return a Proto instance.
- Parameters
file_descriptor (FileDescriptorProto) – The protocol buffer object describing the proto file.
file_to_generate (bool) – Whether this is a file which is to be directly generated, or a dependency.
naming (Naming) – The
Naming
instance associated with the API.prior_protos (Proto) – Previous, already processed protos. These are needed to look up messages in imported protos.
load_services (bool) – Toggle whether the proto file should load its services. Not doing so enables a two-pass fix for LRO response and metadata types in certain situations.
- disambiguate(string: str) → str[source]
Return a disambiguated string for the context of this proto.
This is used for avoiding naming collisions. Generally, this method returns the same string, but it returns a modified version if it will cause a naming collision with messages or fields in this proto.
- property enums: Mapping[str, gapic.schema.wrappers.EnumType]
Return top-level enums on the proto.
- property messages: Mapping[str, gapic.schema.wrappers.MessageType]
Return top-level messages on the proto.
- property module_name: str
Return the appropriate module name for this service.
- Returns
- The module name for this service (which is the service
name in snake case).
- Return type
- property names: FrozenSet[str]
Return a set of names used by this proto.
This is used for detecting naming collisions in the module names used for imports.
- property python_modules: Sequence[Tuple[str, str]]
Return a sequence of Python modules, for import.
The results of this method are in alphabetical order (by package, then module), and do not contain duplicates.
- property resource_messages: Mapping[str, gapic.schema.wrappers.MessageType]
Return the file level resources of the proto.
metadata
The metadata
module defines schema for where data was parsed from.
This library places every protocol buffer descriptor in a wrapper class
(see wrappers
) before loading it into the API
object.
As we iterate over descriptors during the loading process, it is important
to know where they came from, because sometimes protocol buffer types are
referenced by fully-qualified string (e.g. method.input_type
), and we
want to resolve those references.
Additionally, protocol buffers stores data from the comments in the .proto
in a separate structure, and this object model re-connects the comments
with the things they describe for easy access in templates.
- class gapic.schema.metadata.Address(name: str = '', module: str = '', module_path: Tuple[int, ...] = <factory>, package: Tuple[str, ...] = <factory>, parent: Tuple[str, ...] = <factory>, api_naming: gapic.schema.naming.Naming = <factory>, collisions: FrozenSet[str] = <factory>)[source]
- child(child_name: str, path: Tuple[int, ...]) → gapic.schema.metadata.Address[source]
Return a new child of the current Address.
- Parameters
child_name (str) – The name of the child node. This address’ name is appended to
parent
.- Returns
The new address object.
- Return type
Address
- property module_alias: str
Return an appropriate module alias if necessary.
If the module name is not a collision, return empty string.
This method provides a mechanism for resolving naming conflicts, while still providing names that are fundamentally readable to users (albeit looking auto-generated).
- property proto: str
Return the proto selector for this type.
- property proto_package: str
Return the proto package for this type.
- property python_import: gapic.schema.imp.Import
Return the Python import for this type.
- rel(address: gapic.schema.metadata.Address) → str[source]
Return an identifier for this type, relative to the given address.
Similar to
__str__()
, but accepts an address (expected to be the module being written) and truncates the beginning module if the address matches the identifier’s address. Templates can use this in situations where otherwise they would refer to themselves.- Parameters
address (Address) – The address to compare against.
- Returns
The appropriate identifier.
- Return type
- resolve(selector: str) → str[source]
Resolve a potentially-relative protobuf selector.
This takes a protobuf selector which may be fully-qualified (e.g. foo.bar.v1.Baz) or may be relative (Baz) and returns the fully-qualified version.
This method is naive and does not check to see if the message actually exists.
- property sphinx: str
Return the Sphinx identifier for this type.
- property subpackage: Tuple[str, ...]
Return the subpackage below the versioned module name, if any.
- with_context(*, collisions: FrozenSet[str]) → gapic.schema.metadata.Address[source]
Return a derivative of this address with the provided context.
This method is used to address naming collisions. The returned
Address
object aliases module names to avoid naming collisions in the file being written.
- class gapic.schema.metadata.BaseAddress(name: str = '', module: str = '', module_path: Tuple[int, ...] = <factory>, package: Tuple[str, ...] = <factory>, parent: Tuple[str, ...] = <factory>)[source]
- class gapic.schema.metadata.FieldIdentifier(ident: gapic.schema.metadata.Address, repeated: bool, mapping: Optional[tuple] = None)[source]
- class gapic.schema.metadata.Metadata(address: gapic.schema.metadata.Address = <factory>, documentation: google.protobuf.descriptor_pb2.Location = <factory>)[source]
- property doc
Return the best comment.
This property prefers the leading comment if one is available, and falls back to a trailing comment or a detached comment otherwise.
If there are no comments, return empty string. (This means a template is always guaranteed to get a string.)
- with_context(*, collisions: FrozenSet[str]) → gapic.schema.metadata.Metadata[source]
Return a derivative of this metadata with the provided context.
This method is used to address naming collisions. The returned
Address
object aliases module names to avoid naming collisions in the file being written.
naming
- class gapic.schema.naming.Naming(name: str = '', namespace: Tuple[str, ...] = <factory>, version: str = '', product_name: str = '', proto_package: str = '', _warehouse_package_name: str = '')[source]
Naming data for an API.
This class contains the naming nomenclature used for this API within templates.
An concrete child of this object is made available to every template (as
api.naming
).- static build(*file_descriptors: google.protobuf.descriptor_pb2.FileDescriptorProto, opts: gapic.utils.options.Options = Options(name='', namespace=(), warehouse_package_name='', retry=None, sample_configs=(), autogen_snippets=True, templates=('DEFAULT'), lazy_import=False, old_naming=False, add_iam_methods=False, metadata=False, transport=[], service_yaml_config={}, PYTHON_GAPIC_PREFIX='python-gapic-', OPT_FLAGS=frozenset({'retry-config', 'old-naming', 'autogen-snippets', 'warehouse-package-name', 'service-yaml', 'add-iam-methods', 'lazy-import', 'samples', 'transport', 'metadata'}))) → gapic.schema.naming.Naming[source]
Return a full Naming instance based on these file descriptors.
This is pieced together from the proto package names as well as the
google.api.metadata
file annotation. This information may be present in one or many files; this method is tolerant as long as the data does not conflict.- Parameters
file_descriptors (Iterable[FileDescriptorProto]) – A list of file descriptor protos. This list should only include the files actually targeted for output (not their imports).
- Returns
- Return type
Naming
- Raises
ValueError – If the provided file descriptors contain contradictory information.
- property long_name: str
Return an appropriate title-cased long name.
- property module_name: str
Return the appropriate Python module name.
- property module_namespace: Tuple[str, ...]
Return the appropriate Python module namespace as a tuple.
- property namespace_packages: Tuple[str, ...]
Return the appropriate Python namespace packages.
- abstract property versioned_module_name: str
Return the versiond module name (e.g.
apiname_v1
).If there is no version, this is the same as
module_name
.
- property warehouse_package_name: str
Return the appropriate Python package name for Warehouse.
- class gapic.schema.naming.NewNaming(name: str = '', namespace: Tuple[str, ...] = <factory>, version: str = '', product_name: str = '', proto_package: str = '', _warehouse_package_name: str = '')[source]
- property versioned_module_name: str
Return the versiond module name (e.g.
apiname_v1
).If there is no version, this is the same as
module_name
.
- class gapic.schema.naming.OldNaming(name: str = '', namespace: Tuple[str, ...] = <factory>, version: str = '', product_name: str = '', proto_package: str = '', _warehouse_package_name: str = '')[source]
- property versioned_module_name: str
Return the versiond module name (e.g.
apiname_v1
).If there is no version, this is the same as
module_name
.
wrappers
Module containing wrapper classes around meta-descriptors.
This module contains dataclasses which wrap the descriptor protos defined in google/protobuf/descriptor.proto (which are descriptors that describe descriptors).
These wrappers exist in order to provide useful helper methods and generally ease access to things in templates (in particular, documentation, certain aggregate views of things, etc.)
Reading of underlying descriptor properties in templates is okay, a
__getattr__
method which consistently routes in this way is provided.
Documentation is consistently at {thing}.meta.doc
.
- class gapic.schema.wrappers.EnumType(enum_pb: google.protobuf.descriptor_pb2.EnumDescriptorProto, values: List[gapic.schema.wrappers.EnumValueType], meta: gapic.schema.metadata.Metadata = <factory>)[source]
Description of an enum (defined with the
enum
keyword.)- property ident: gapic.schema.metadata.Address
Return the identifier data to be used in templates.
- property options_dict: Dict
Return the EnumOptions (if present) as a dict.
This is a hack to support a pythonic structure representation for the generator templates.
- with_context(*, collisions: FrozenSet[str]) → gapic.schema.wrappers.EnumType[source]
Return a derivative of this enum with the provided context.
This method is used to address naming collisions. The returned
EnumType
object aliases module names to avoid naming collisions in the file being written.
- class gapic.schema.wrappers.EnumValueType(enum_value_pb: google.protobuf.descriptor_pb2.EnumValueDescriptorProto, meta: gapic.schema.metadata.Metadata = <factory>)[source]
Description of an enum value.
- class gapic.schema.wrappers.ExtendedOperationInfo(request_type: gapic.schema.wrappers.MessageType, operation_type: gapic.schema.wrappers.MessageType)[source]
A handle to the request type of the extended operation polling method and the underlying operation type.
- with_context(*, collisions: FrozenSet[str]) → gapic.schema.wrappers.ExtendedOperationInfo[source]
Return a derivative of this OperationInfo with the provided context.
This method is used to address naming collisions. The returned
OperationInfo
object aliases module names to avoid naming collisions in the file being written.
- class gapic.schema.wrappers.Field(field_pb: google.protobuf.descriptor_pb2.FieldDescriptorProto, message: Optional[gapic.schema.wrappers.MessageType] = None, enum: Optional[gapic.schema.wrappers.EnumType] = None, meta: gapic.schema.metadata.Metadata = <factory>, oneof: Optional[str] = None)[source]
Description of a field.
- property ident: gapic.schema.metadata.FieldIdentifier
Return the identifier to be used in templates.
- inner_mock(stack, visited_fields) → str[source]
Return a repr of a valid, usually truthy mock value.
- property is_primitive: bool
Return True if the field is a primitive, False otherwise.
- property map: bool
Return True if this field is a map, False otherwise.
- property name: str
Used to prevent collisions with python keywords
- primitive_mock(suffix: int = 0) → Optional[Union[bool, str, bytes, int, float, List[Any]]][source]
Generate a valid mock for a primitive type. This function returns the original (Python) type.
If a suffix is provided, generate a slightly different mock using the provided integer.
- property proto_type: str
Return the proto type constant to be used in templates.
- property repeated: bool
Return True if this is a repeated field, False otherwise.
- Returns
Whether this field is repeated.
- Return type
- property required: bool
Return True if this is a required field, False otherwise.
- Returns
Whether this field is required.
- Return type
- property resource_reference: Optional[str]
Return a resource reference type if it exists.
This is only applicable for string fields. Example: “translate.googleapis.com/Glossary”
- property type: Union[gapic.schema.wrappers.MessageType, gapic.schema.wrappers.EnumType, gapic.schema.wrappers.PrimitiveType]
Return the type of this field.
- with_context(*, collisions: FrozenSet[str], visited_messages: FrozenSet[gapic.schema.wrappers.MessageType]) → gapic.schema.wrappers.Field[source]
Return a derivative of this field with the provided context.
This method is used to address naming collisions. The returned
Field
object aliases module names to avoid naming collisions in the file being written.
- class gapic.schema.wrappers.HttpRule(method: str, uri: str, body: Optional[str])[source]
Representation of the method’s http bindings.
- path_fields(method: gapic.schema.wrappers.Method) → List[Tuple[gapic.schema.wrappers.Field, str, str]][source]
return list of (name, template) tuples extracted from uri.
- sample_request(method: gapic.schema.wrappers.Method) → Dict[str, Any][source]
return json dict for sample request matching the uri template.
- class gapic.schema.wrappers.MessageType(message_pb: google.protobuf.descriptor_pb2.DescriptorProto, fields: Mapping[str, gapic.schema.wrappers.Field], nested_enums: Mapping[str, gapic.schema.wrappers.EnumType], nested_messages: Mapping[str, gapic.schema.wrappers.MessageType], meta: gapic.schema.metadata.Metadata = <factory>, oneofs: Optional[Mapping[str, gapic.schema.wrappers.Oneof]] = None)[source]
Description of a message (defined with the
message
keyword).- property extended_operation_request_fields: Sequence[gapic.schema.wrappers.Field]
If this message is the request for a method that uses extended operations, return the fields that correspond to operation request fields in the operation message.
- property extended_operation_response_fields: Sequence[gapic.schema.wrappers.Field]
If this message is the request for a method that uses extended operations, return the fields that correspond to operation response fields in the polling message.
- get_field(*field_path: str, collisions: FrozenSet[str] = frozenset({})) → gapic.schema.wrappers.Field[source]
Return a field arbitrarily deep in this message’s structure.
This method recursively traverses the message tree to return the requested inner-field.
Traversing through repeated fields is not supported; a repeated field may be specified if and only if it is the last field in the path.
- property ident: gapic.schema.metadata.Address
Return the identifier data to be used in templates.
- property map: bool
Return True if the given message is a map, False otherwise.
- property recursive_field_types: Sequence[Union[gapic.schema.wrappers.MessageType, gapic.schema.wrappers.EnumType]]
Return all composite fields used in this proto’s messages.
- property resource_path: Optional[str]
If this message describes a resource, return the path to the resource. If there are multiple paths, returns the first one.
- with_context(*, collisions: FrozenSet[str], skip_fields: bool = False, visited_messages: FrozenSet[gapic.schema.wrappers.MessageType] = frozenset({})) → gapic.schema.wrappers.MessageType[source]
Return a derivative of this message with the provided context.
This method is used to address naming collisions. The returned
MessageType
object aliases module names to avoid naming collisions in the file being written.The
skip_fields
argument will omit applying the context to the underlying fields. This provides for an “exit” in the case of circular references.
- class gapic.schema.wrappers.Method(method_pb: google.protobuf.descriptor_pb2.MethodDescriptorProto, input: gapic.schema.wrappers.MessageType, output: gapic.schema.wrappers.MessageType, lro: Optional[gapic.schema.wrappers.OperationInfo] = None, extended_lro: Optional[gapic.schema.wrappers.ExtendedOperationInfo] = None, retry: Optional[gapic.schema.wrappers.RetryInfo] = None, timeout: Optional[float] = None, meta: gapic.schema.metadata.Metadata = <factory>)[source]
Description of a method (defined with the
rpc
keyword).- property field_headers: Sequence[gapic.schema.wrappers.FieldHeader]
Return the field headers defined for this method.
- property grpc_stub_type: str
Return the type of gRPC stub to use.
- property http_opt: Optional[Dict[str, str]]
Return the (main) http option for this method.
- e.g. {‘verb’: ‘post’
‘url’: ‘/some/path’ ‘body’: ‘*’}
- property http_options: List[gapic.schema.wrappers.HttpRule]
Return a list of the http bindings for this method.
- property idempotent: bool
Return True if we know this method is idempotent, False otherwise.
Note: We are intentionally conservative here. It is far less bad to falsely believe an idempotent method is non-idempotent than the converse.
- property ident: gapic.schema.metadata.Address
Return the identifier data to be used in templates.
- property is_deprecated: bool
Returns true if the method is deprecated, false otherwise.
- property legacy_flattened_fields: Mapping[str, gapic.schema.wrappers.Field]
top level fields only, required fields first
- Type
Return the legacy flattening interface
- property paged_result_field: Optional[gapic.schema.wrappers.Field]
Return the response pagination field if the method is paginated.
- property path_params: Sequence[str]
Return the path parameters found in the http annotation path template
- property query_params: Set[str]
Return query parameters for API call as determined by http annotation and grpc transcoding
- property void: bool
Return True if this method has no return value, False otherwise.
- with_context(*, collisions: FrozenSet[str]) → gapic.schema.wrappers.Method[source]
Return a derivative of this method with the provided context.
This method is used to address naming collisions. The returned
Method
object aliases module names to avoid naming collisions in the file being written.
- class gapic.schema.wrappers.Oneof(oneof_pb: google.protobuf.descriptor_pb2.OneofDescriptorProto)[source]
Description of a field.
- class gapic.schema.wrappers.OperationInfo(response_type: gapic.schema.wrappers.MessageType, metadata_type: gapic.schema.wrappers.MessageType)[source]
Representation of long-running operation info.
- with_context(*, collisions: FrozenSet[str]) → gapic.schema.wrappers.OperationInfo[source]
Return a derivative of this OperationInfo with the provided context.
This method is used to address naming collisions. The returned
OperationInfo
object aliases module names to avoid naming collisions in the file being written.
- class gapic.schema.wrappers.PrimitiveType(meta: gapic.schema.metadata.Metadata, python_type: Optional[type])[source]
A representation of a Python primitive type.
- class gapic.schema.wrappers.PythonType(meta: gapic.schema.metadata.Metadata)[source]
Wrapper class for Python types.
This exists for interface consistency, so that methods like
Field.type()
can return an object and the caller can be confident that aname
property will be present.- property ident: gapic.schema.metadata.Address
Return the identifier to be used in templates.
- class gapic.schema.wrappers.RetryInfo(max_attempts: int, initial_backoff: float, max_backoff: float, backoff_multiplier: float, retryable_exceptions: FrozenSet[google.api_core.exceptions.GoogleAPICallError])[source]
Representation of the method’s retry behavior.
- class gapic.schema.wrappers.RoutingParameter(field: str, path_template: str)[source]
- property sample_request: str
return json dict for sample request matching the uri template.
- class gapic.schema.wrappers.RoutingRule(routing_parameters: List[gapic.schema.wrappers.RoutingParameter])[source]
- class gapic.schema.wrappers.Service(service_pb: google.protobuf.descriptor_pb2.ServiceDescriptorProto, methods: Mapping[str, gapic.schema.wrappers.Method], visible_resources: Mapping[str, gapic.schema.wrappers.MessageType], meta: gapic.schema.metadata.Metadata = <factory>)[source]
Description of a service (defined with the
service
keyword).- property async_client_name: str
Returns the name of the generated AsyncIO client class
- property client_name: str
Returns the name of the generated client class
- property has_lro: bool
Return whether the service has a long-running method.
- property has_pagers: bool
Return whether the service has paged methods.
- property host: str
Return the hostname for this service, if specified.
- Returns
The hostname, with no protocol and no trailing
/
.- Return type
- property module_name: str
Return the appropriate module name for this service.
- Returns
The service name, in snake case.
- Return type
- property names: FrozenSet[str]
Return a set of names used in this service.
This is used for detecting naming collisions in the module names used for imports.
- property oauth_scopes: Sequence[str]
Return a sequence of oauth scopes, if applicable.
- Returns
A sequence of OAuth scopes.
- Return type
Sequence[str]
- property resource_messages: FrozenSet[gapic.schema.wrappers.MessageType]
Returns all the resource message types used in all request and response fields in the service.
- property resource_messages_dict: Dict[str, gapic.schema.wrappers.MessageType]
Returns a dict from resource reference to the message type. This includes the common resource messages.
- Returns
- A mapping from resource path
string to the corresponding MessageType. {“locations.googleapis.com/Location”: MessageType(…)}
- Return type
Dict[str, MessageType]
- property shortname: str
Return the API short name. DRIFT uses this to identify APIs.
- Returns
The api shortname.
- Return type
- with_context(*, collisions: FrozenSet[str]) → gapic.schema.wrappers.Service[source]
Return a derivative of this service with the provided context.
This method is used to address naming collisions. The returned
Service
object aliases module names to avoid naming collisions in the file being written.