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, protos: Mapping[str, gapic.schema.api.Proto])[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 = '') → 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.

enums¶: Return a map of all enums available in the API.

messages¶: Return a map of all messages available in the API.

services¶: Return a map of all services available in the API.

class gapic.schema.api.Proto(file_pb2: google.protobuf.descriptor_pb2.FileDescriptorProto, services: Mapping[str, gapic.schema.wrappers.Service], messages: Mapping[str, gapic.schema.wrappers.MessageType], 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, prior_protos: Mapping[str, Proto] = 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.

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.

module_name¶

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

names¶

Return a set of names used by this proto.

This is used for detecting naming collisions in the module names used for imports.

python_modules¶

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.

Returns:	The package and module pair, intended for use in a `from package import module` type of statement.
Return type:	Sequence[Tuple[str, str]]

top¶

Return a proto shim which is only aware of top-level objects.

This is useful in a situation where a template wishes to iterate over only those messages and enums that are at the top level of the file.

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:Set[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

module_alias¶

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).

proto¶: Return the proto selector for this type.

proto_package¶: Return the proto package for this type.

python_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:	str

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.

Parameters:	selector (str) – A protobuf selector, either fully-qualified or relative.
Returns:	An absolute selector.
Return type:	str

sphinx¶: Return the Sphinx identifier for this type.

subpackage¶: Return the subpackage below the versioned module name, if any.

with_context(*, collisions: Set[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.FieldIdentifier(ident:gapic.schema.metadata.Address, repeated:bool)[source]¶

class gapic.schema.metadata.Metadata(address:gapic.schema.metadata.Address=<factory>, documentation:google.protobuf.descriptor_pb2.Location=<factory>)[source]¶

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: Set[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 = '', product_url: str = '', proto_package: str = '')[source]¶

Naming data for an API.

This class contains the naming nomenclature used for this API within templates.

An instance of this object is made available to every template (as api.naming).

classmethod build(*file_descriptors) → 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:	A `Naming` instance which is provided to templates as part of the `API`.
Return type:	Naming
Raises:	`ValueError` – If the provided file descriptors contain contradictory information.

long_name¶: Return an appropriate title-cased long name.

module_name¶: Return the appropriate Python module name.

module_namespace¶: Return the appropriate Python module namespace as a tuple.

namespace_packages¶: Return the appropriate Python namespace packages.

versioned_module_name¶

Return the versiond module name (e.g. apiname_v1).

If there is no version, this is the same as module_name.

warehouse_package_name¶: Return the appropriate Python package name for Warehouse.

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.)

ident¶: Return the identifier data to be used in templates.

with_context(*, collisions: Set[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.Field(field_pb: google.protobuf.descriptor_pb2.FieldDescriptorProto, message: MessageType = None, enum: EnumType = None, meta: gapic.schema.metadata.Metadata = <factory>)[source]¶

Description of a field.

ident¶: Return the identifier to be used in templates.

is_primitive¶: Return True if the field is a primitive, False otherwise.

proto_type¶: Return the proto type constant to be used in templates.

repeated¶

Return True if this is a repeated field, False otherwise.

Returns:	Whether this field is repeated.
Return type:	bool

required¶

Return True if this is a required field, False otherwise.

Returns:	Whether this field is required.
Return type:	bool

type¶: Return the type of this field.

with_context(*, collisions: Set[str]) → 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.MessageType(message_pb: google.protobuf.descriptor_pb2.DescriptorProto, fields: Mapping[str, gapic.schema.wrappers.Field], nested_enums: Mapping[str, EnumType], nested_messages: Mapping[str, MessageType], meta: gapic.schema.metadata.Metadata = <factory>)[source]¶

Description of a message (defined with the message keyword).

field_types¶: Return all composite fields used in this proto’s messages.

get_field(*field_path, collisions: Set[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.

Parameters:	field_path (Sequence[str]) – The field path.
Returns:	A field object.
Return type:	Field
Raises:	`KeyError` – If a repeated field is used in the non-terminal position in the path.

ident¶: Return the identifier data to be used in templates.

with_context(*, collisions: Set[str], skip_fields: bool = False) → 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, meta: gapic.schema.metadata.Metadata = <factory>)[source]¶

Description of a method (defined with the rpc keyword).

field_headers¶: Return the field headers defined for this method.

grpc_stub_type¶: Return the type of gRPC stub to use.

ref_types¶: Return types referenced by this method.

signatures¶: Return the signature defined for this method.

with_context(*, collisions: Set[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.MethodSignature(name:str, fields:Mapping[str, gapic.schema.wrappers.Field])[source]¶

composite_types¶: Return all composite types used in this signature.

dispatch_field¶

Return the first field.

This is what is used for functools.singledispatch.

class gapic.schema.wrappers.MethodSignatures(all:Tuple[gapic.schema.wrappers.MethodSignature])[source]¶

single_dispatch¶

Return a tuple of signatures, grouped and deduped by dispatch type.

In the Python 3 templates, we only honor at most one method signature per initial argument type, and only for primitives.

This method groups and deduplicates signatures and sends back only the signatures that the template actually wants.

Returns:	Method signatures to be used with ”single dispatch” routing.
Return type:	Tuple[MethodSignature]

class gapic.schema.wrappers.OperationType(lro_response: gapic.schema.wrappers.MessageType, lro_metadata: gapic.schema.wrappers.MessageType = None)[source]¶

Wrapper class for Operation.

This exists for interface consistency, so Operations can be used alongside MessageType instances.

meta¶: Return a Metadata object.

name¶: Return the class name.

with_context(*, collisions: Set[str]) → gapic.schema.wrappers.OperationType[source]¶

Return a derivative of this operation with the provided context.

This method is used to address naming collisions. The returned OperationType object aliases module names to avoid naming collisions in the file being written.

class gapic.schema.wrappers.PythonType(python_type: type)[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 a name property will be present.

ident¶

Return the identifier to be used in templates.

Primitives have no import, and no module to reference, so this is simply the name of the class (e.g. “int”, “str”).

class gapic.schema.wrappers.Service(service_pb: google.protobuf.descriptor_pb2.ServiceDescriptorProto, methods: Mapping[str, gapic.schema.wrappers.Method], meta: gapic.schema.metadata.Metadata = <factory>)[source]¶

Description of a service (defined with the service keyword).

has_lro¶: Return whether the service has a long-running method.

host¶

Return the hostname for this service, if specified.

Returns:	The hostname, with no protocol and no trailing `/`.
Return type:	str

module_name¶

Return the appropriate module name for this service.

Returns:	The service name, in snake case.
Return type:	str

names¶

Return a set of names used in this service.

This is used for detecting naming collisions in the module names used for imports.

oauth_scopes¶

Return a sequence of oauth scopes, if applicable.

Returns:	A sequence of OAuth scopes.
Return type:	Sequence[str]

python_modules¶

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.

Returns:	The package and module, intended for use in templates.
Return type:	Sequence[Import]

with_context(*, collisions: Set[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.