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: typing.Mapping[str, gapic.schema.api.Proto], service_yaml_config: google.api.service_pb2.Service, subpackage_view: typing.Tuple[str, ...] = <factory>)

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

property all_library_settings: Mapping[str, Sequence[google.api.client_pb2.ClientLibrarySettings]]

Return a map of all google.api.client.ClientLibrarySettings to be used when generating client libraries. https://github.com/googleapis/googleapis/blob/master/google/api/client.proto#L130

Returns

A mapping of all library

settings read from the service YAML.

Return type

Mapping[str, Sequence[client_pb2.ClientLibrarySettings]]

Raises

• gapic.schema.api.ClientLibrarySettingsError – Raised when google.api.client_pb2.ClientLibrarySettings

• contains an invalid value. –

property all_method_settings: Mapping[str, Sequence[google.api.client_pb2.MethodSettings]]

Return a map of all google.api.client.MethodSettings to be used when generating methods. https://github.com/googleapis/googleapis/blob/7dab3de7ec79098bb367b6b2ac3815512a49dd56/google/api/client.proto#L325

Returns

A mapping of all method

settings read from the service YAML.

Return type

Mapping[str, Sequence[client_pb2.MethodSettings]]

Raises

gapic.schema.api.MethodSettingsError – if the method settings do not meet the requirements of https://google.aip.dev/client-libraries/4235.

property all_methods: Mapping[str, google.protobuf.descriptor_pb2.MethodDescriptorProto]

Return a map of all methods for the API.

Returns

A mapping of MethodDescriptorProto

values for the API.

Return type

Mapping[str, MethodDescriptorProto]

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={}, rest_numeric_enums=False, proto_plus_deps=('',), PYTHON_GAPIC_PREFIX='python-gapic-', OPT_FLAGS=frozenset({'warehouse-package-name', 'rest-numeric-enums', 'lazy-import', 'add-iam-methods', 'service-yaml', 'proto-plus-deps', 'retry-config', 'transport', 'samples', 'metadata', 'autogen-snippets', 'old-naming'})), prior_protos: Optional[Mapping[str, gapic.schema.api.Proto]] = None) → gapic.schema.api.API

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.

enforce_valid_library_settings(client_library_settings: Sequence[google.api.client_pb2.ClientLibrarySettings]) → None

Checks each google.api.client.ClientLibrarySettings provided for validity and raises an exception if invalid values are found.

Parameters

client_library_settings (Sequence[client_pb2.ClientLibrarySettings]) – Client library settings to be used when generating API methods.

Returns

None

Raises

ClientLibrarySettingsError – if fields in client_library_settings.experimental_features are not supported.

enforce_valid_method_settings(service_method_settings: Sequence[google.api.client_pb2.MethodSettings]) → None

Checks each google.api.client.MethodSettings provided for validity and raises an exception if invalid values are found. If google.api.client.MethodSettings.auto_populated_fields is set, verify each field against the criteria of AIP-4235 (https://google.aip.dev/client-libraries/4235). All of the conditions below must be true:

• The field must be of type string

• The field must be at the top-level of the request message

• The RPC must be a unary RPC (i.e. streaming RPCs are not supported)

• The field must not be annotated with google.api.field_behavior = REQUIRED.

• The field must be annotated with google.api.field_info.format = UUID4.

Note that the field presence requirements in AIP-4235 should be checked at run time.

Parameters

service_method_settings (Sequence[client_pb2.MethodSettings]) – Method settings to be used when generating API methods.

Returns

None

Raises

MethodSettingsError – if fields in method_settings.auto_populated_fields cannot be automatically populated.

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

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]

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 mixin_api_signatures

Compile useful info about MixIn API signatures.

Returns

Useful info

about MixIn methods present for the main API.

Return type

Mapping[str, wrappers.MixinMethod]

property mixin_http_options

Gather HTTP options for the MixIn methods.

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.

exception gapic.schema.api.ClientLibrarySettingsError

Raised when google.api.client_pb2.ClientLibrarySettings contains an invalid value.

exception gapic.schema.api.MethodSettingsError

Raised when google.api.client_pb2.MethodSettings contains an invalid value.

class gapic.schema.api.Proto(file_pb2: google.protobuf.descriptor_pb2.FileDescriptorProto, services: typing.Mapping[str, gapic.schema.wrappers.Service], all_messages: typing.Mapping[str, gapic.schema.wrappers.MessageType], all_enums: typing.Mapping[str, gapic.schema.wrappers.EnumType], file_to_generate: bool, meta: gapic.schema.metadata.Metadata = <factory>)

A representation of a particular proto file within an API.

add_to_address_allowlist(*, address_allowlist: Set[gapic.schema.metadata.Address], method_allowlist: Set[str], resource_messages: Dict[str, gapic.schema.wrappers.MessageType]) → None

Adds to the set of Addresses of wrapper objects to be included in selective GAPIC generation.

This method is used to create an allowlist of addresses to be used to filter out unneeded services, methods, messages, and enums at a later step.

Parameters

• address_allowlist (Set[metadata.Address]) – A set of allowlisted metadata.Address objects to add to. Only the addresses of the allowlisted methods, the services containing these methods, and messages/enums those methods use will be part of the final address_allowlist. The set may be modified during this call.

• method_allowlist (Set[str]) – An allowlist of fully-qualified method names.

• resource_messages (Dict[str, wrappers.MessageType]) – A dictionary mapping the unified resource type name of a resource message to the corresponding MessageType object representing that resource message. Only resources with a message representation should be included in the dictionary.

Returns

None

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={}, rest_numeric_enums=False, proto_plus_deps=('',), PYTHON_GAPIC_PREFIX='python-gapic-', OPT_FLAGS=frozenset({'warehouse-package-name', 'rest-numeric-enums', 'lazy-import', 'add-iam-methods', 'service-yaml', 'proto-plus-deps', 'retry-config', 'transport', 'samples', 'metadata', 'autogen-snippets', 'old-naming'})), 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

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

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

str

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.

prune_messages_for_selective_generation(*, address_allowlist: Set[gapic.schema.metadata.Address]) → Optional[gapic.schema.api.Proto]

Returns a truncated version of this Proto.

Only the services, messages, and enums contained in the allowlist of visited addresses are included in the returned object. If there are no services, messages, or enums left, and no file level resources, return None.

Parameters

address_allowlist (Set[metadata.Address]) – A set of allowlisted metadata.Address objects to filter against. Objects with addresses not the allowlist will be removed from the returned Proto.

Returns

A truncated version of this proto. If there are no services, messages,

or enums left after the truncation process and there are no file level resources, returns None.

Return type

Optional[Proto]

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.

Returns

The package and module pair, intended for use in a from package import module type of statement.

Return type

Sequence[Tuple[str, str]]

property resource_messages: Mapping[str, gapic.schema.wrappers.MessageType]

Return the file level resources of the proto.

with_internal_methods(*, public_methods: Set[str]) → gapic.schema.api.Proto

Returns a version of this Proto with some Methods marked as internal.

The methods not in the public_methods set will be marked as internal and services containing these methods will also be marked as internal by extension. (See Service.is_internal() for more details).

Parameters

public_methods (Set[str]) – An allowlist of fully-qualified method names. Methods not in this allowlist will be marked as internal.

Returns

A version of this Proto with Method objects corresponding to methods

not in public_methods marked as internal.

Return type

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: Set[str] = <factory>)

child(child_name: str, path: Tuple[int, ...]) → gapic.schema.metadata.Address

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 is_proto_plus_type: bool

This function is used to determine whether a given package self.proto_package is using proto-plus types or protobuf types. There are 2 scenarios where the package is expected to use proto-plus types: 1) When self.proto_package starts with self.api_naming.proto_package, then the given package has the same namespace as the one that is being generated. It is assumed that the gapic generator always generates packages with proto-plus types. 2) When self.proto_package is explicitly in self.api_naming.proto_plus_deps which is populated via the generator option proto-plus-deps.

Returns

Whether the given package uses proto-plus types or not.

Return type

bool

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

Return the versioned 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

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

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

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: Set[str]) → gapic.schema.metadata.Address

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

class gapic.schema.metadata.FieldIdentifier(ident: gapic.schema.metadata.Address, repeated: bool, mapping: Optional[tuple] = None)

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

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: Set[str]) → gapic.schema.metadata.Metadata

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: typing.Tuple[str, ...] = <factory>, version: str = '', product_name: str = '', proto_package: str = '', _warehouse_package_name: str = '', proto_plus_deps: typing.Tuple[str, ...] = <factory>)

Naming data for an API.

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

A 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={}, rest_numeric_enums=False, proto_plus_deps=('',), PYTHON_GAPIC_PREFIX='python-gapic-', OPT_FLAGS=frozenset({'warehouse-package-name', 'rest-numeric-enums', 'lazy-import', 'add-iam-methods', 'service-yaml', 'proto-plus-deps', 'retry-config', 'transport', 'samples', 'metadata', 'autogen-snippets', 'old-naming'}))) → gapic.schema.naming.Naming

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.

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: typing.Tuple[str, ...] = <factory>, version: str = '', product_name: str = '', proto_package: str = '', _warehouse_package_name: str = '', proto_plus_deps: typing.Tuple[str, ...] = <factory>)

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: typing.Tuple[str, ...] = <factory>, version: str = '', product_name: str = '', proto_package: str = '', _warehouse_package_name: str = '', proto_plus_deps: typing.Tuple[str, ...] = <factory>)

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.CommonResource(type_name: str, pattern: str)

class gapic.schema.wrappers.EnumType(enum_pb: google.protobuf.descriptor_pb2.EnumDescriptorProto, values: typing.List[gapic.schema.wrappers.EnumValueType], meta: gapic.schema.metadata.Metadata = <factory>)

Description of an enum (defined with the enum keyword.)

add_to_address_allowlist(*, address_allowlist: Set[gapic.schema.metadata.Address]) → None

Adds to the set of Addresses of wrapper objects to be included in selective GAPIC generation.

This method is used to create an allowlist of addresses to be used to filter out unneeded services, methods, messages, and enums at a later step.

Parameters

address_allowlist (Set[metadata.Address]) – A set of allowlisted metadata.Address objects to add to. Only the addresses of the allowlisted methods, the services containing these methods, and messages/enums those methods use will be part of the final address_allowlist. The set may be modified during this call.

Returns

None

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: Set[str]) → gapic.schema.wrappers.EnumType

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

Description of an enum value.

class gapic.schema.wrappers.ExtendedOperationInfo(request_type: gapic.schema.wrappers.MessageType, operation_type: gapic.schema.wrappers.MessageType)

A handle to the request type of the extended operation polling method and the underlying operation type.

add_to_address_allowlist(*, address_allowlist: Set[gapic.schema.metadata.Address], resource_messages: Dict[str, gapic.schema.wrappers.MessageType]) → None

Adds to the set of Addresses of wrapper objects to be included in selective GAPIC generation.

This method is used to create an allowlist of addresses to be used to filter out unneeded services, methods, messages, and enums at a later step.

Parameters

• address_allowlist (Set[metadata.Address]) – A set of allowlisted metadata.Address objects to add to. Only the addresses of the allowlisted methods, the services containing these methods, and messages/enums those methods use will be part of the final address_allowlist. The set may be modified during this call.

• resource_messages (Dict[str, wrappers.MessageType]) – A dictionary mapping the unified resource type name of a resource message to the corresponding MessageType object representing that resource message. Only resources with a message representation should be included in the dictionary.

Returns

None

with_context(*, collisions: Set[str], visited_messages: Optional[Set[gapic.schema.wrappers.MessageType]] = None) → gapic.schema.wrappers.ExtendedOperationInfo

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: typing.Optional[gapic.schema.wrappers.MessageType] = None, enum: typing.Optional[gapic.schema.wrappers.EnumType] = None, meta: gapic.schema.metadata.Metadata = <factory>, oneof: typing.Optional[str] = None)

Description of a field.

add_to_address_allowlist(*, address_allowlist: Set[gapic.schema.metadata.Address], resource_messages: Dict[str, gapic.schema.wrappers.MessageType]) → None

Adds to the set of Addresses of wrapper objects to be included in selective GAPIC generation.

This method is used to create an allowlist of addresses to be used to filter out unneeded services, methods, messages, and enums at a later step.

Parameters

• address_allowlist (Set[metadata.Address]) – A set of allowlisted metadata.Address objects to add to. Only the addresses of the allowlisted methods, the services containing these methods, and messages/enums those methods use will be part of the final address_allowlist. The set may be modified during this call.

• resource_messages (Dict[str, wrappers.MessageType]) – A dictionary mapping the unified resource type name of a resource message to the corresponding MessageType object representing that resource message. Only resources with a message representation should be included in the dictionary.

Returns

None

property ident: gapic.schema.metadata.FieldIdentifier

Return the identifier to be used in templates.

inner_mock(stack, visited_fields) → str

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]]]

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.

primitive_mock_as_str() → str

Like primitive mock, but return the mock as a string.

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

bool

property required: bool

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

Returns

Whether this field is required.

Return type

bool

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.

property uuid4: bool

Return True if the format of this field is a Universally Unique Identifier, version 4 field, False otherwise.

Returns

Whether this field is UUID4.

Return type

bool

with_context(*, collisions: Set[str], visited_messages: Optional[Set[gapic.schema.wrappers.MessageType]] = None) → gapic.schema.wrappers.Field

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.FieldHeader(raw: str)

class gapic.schema.wrappers.HttpRule(method: str, uri: str, body: Optional[str])

Representation of the method’s http bindings.

path_fields(method: gapic.schema.wrappers.Method) → List[Tuple[gapic.schema.wrappers.Field, str, str]]

return list of (name, template) tuples extracted from uri.

sample_request(method: gapic.schema.wrappers.Method) → Dict[str, Any]

return json dict for sample request matching the uri template.

class gapic.schema.wrappers.MessageType(message_pb: google.protobuf.descriptor_pb2.DescriptorProto, fields: typing.Mapping[str, gapic.schema.wrappers.Field], nested_enums: typing.Mapping[str, gapic.schema.wrappers.EnumType], nested_messages: typing.Mapping[str, gapic.schema.wrappers.MessageType], meta: gapic.schema.metadata.Metadata = <factory>, oneofs: typing.Optional[typing.Mapping[str, gapic.schema.wrappers.Oneof]] = None)

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

add_to_address_allowlist(*, address_allowlist: Set[gapic.schema.metadata.Address], resource_messages: Dict[str, gapic.schema.wrappers.MessageType]) → None

Adds to the set of Addresses of wrapper objects to be included in selective GAPIC generation.

This method is used to create an allowlist of addresses to be used to filter out unneeded services, methods, messages, and enums at a later step.

Parameters

• address_allowlist (Set[metadata.Address]) – A set of allowlisted metadata.Address objects to add to. Only the addresses of the allowlisted methods, the services containing these methods, and messages/enums those methods use will be part of the final address_allowlist. The set may be modified during this call.

• resource_messages (Dict[str, wrappers.MessageType]) – A dictionary mapping the unified resource type name of a resource message to the corresponding MessageType object representing that resource message. Only resources with a message representation should be included in the dictionary.

Returns

None

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: Optional[Set[str]] = None) → gapic.schema.wrappers.Field

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.

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.

property resource_path_formatted: str

Returns a formatted version of resource_path. This re-writes patterns like: ‘projects/{project}/metricDescriptors/{metric_descriptor=**}’ to ‘projects/{project}/metricDescriptors/{metric_descriptor} so it can be used in an f-string.

with_context(*, collisions: Set[str], skip_fields: bool = False, visited_messages: Optional[Set[gapic.schema.wrappers.MessageType]] = None) → gapic.schema.wrappers.MessageType

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, is_internal: bool = False, lro: typing.Optional[gapic.schema.wrappers.OperationInfo] = None, extended_lro: typing.Optional[gapic.schema.wrappers.ExtendedOperationInfo] = None, retry: typing.Optional[gapic.schema.wrappers.RetryInfo] = None, timeout: typing.Optional[float] = None, meta: gapic.schema.metadata.Metadata = <factory>)

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

add_to_address_allowlist(*, address_allowlist: Set[gapic.schema.metadata.Address], resource_messages: Dict[str, gapic.schema.wrappers.MessageType], services_in_proto: Dict[str, gapic.schema.wrappers.Service]) → None

Adds to the allowlist of Addresses of wrapper objects to be included in selective GAPIC generation.

This method is used to create an allowlist of addresses to be used to filter out unneeded services, methods, messages, and enums at a later step.

Parameters

• address_allowlist (Set[metadata.Address]) – A set of allowlisted metadata.Address objects to add to. Only the addresses of the allowlisted methods, the services containing these methods, and messages/enums those methods use will be part of the final address_allowlist. The set may be modified during this call.

• method_allowlist (Set[str]) – An allowlist of fully-qualified method names.

• resource_messages (Dict[str, wrappers.MessageType]) – A dictionary mapping the unified resource type name of a resource message to the corresponding MessageType object representing that resource message. Only resources with a message representation should be included in the dictionary.

• services_in_proto (Dict[str, wrappers.Service]) – A dictionary mapping the names of Service objects in the proto containing this method to the Service objects. This is necessary for traversing the operation service in the case of extended LROs.

Returns

None

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: Set[str], visited_messages: Optional[Set[gapic.schema.wrappers.MessageType]] = None) → gapic.schema.wrappers.Method

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.

with_internal_methods(*, public_methods: Set[str]) → gapic.schema.wrappers.Method

Returns a version of this Method marked as internal

The methods not in the public_methods set will be marked as internal and this Service will as well by extension (see Service.is_internal()).

Parameters

public_methods (Set[str]) – An allowlist of fully-qualified method names. Methods not in this allowlist will be marked as internal.

Returns

A version of this Service with Method objects corresponding to methods

not in public_methods marked as internal.

Return type

Service

class gapic.schema.wrappers.MixinHttpRule(method: str, uri: str, body: Optional[str])

path_fields(uri)

return list of (name, template) tuples extracted from uri.

property sample_request

return json dict for sample request matching the uri template.

class gapic.schema.wrappers.MixinMethod(name: str, request_type: str, response_type: str)

class gapic.schema.wrappers.Oneof(oneof_pb: google.protobuf.descriptor_pb2.OneofDescriptorProto)

Description of a field.

class gapic.schema.wrappers.OperationInfo(response_type: gapic.schema.wrappers.MessageType, metadata_type: gapic.schema.wrappers.MessageType)

Representation of long-running operation info.

add_to_address_allowlist(*, address_allowlist: Set[gapic.schema.metadata.Address], resource_messages: Dict[str, gapic.schema.wrappers.MessageType]) → None

Adds to the set of Addresses of wrapper objects to be included in selective GAPIC generation.

This method is used to create an allowlist of addresses to be used to filter out unneeded services, methods, messages, and enums at a later step.

Parameters

• address_allowlist (Set[metadata.Address]) – A set of allowlisted metadata.Address objects to add to. Only the addresses of the allowlisted methods, the services containing these methods, and messages/enums those methods use will be part of the final address_allowlist. The set may be modified during this call.

• resource_messages (Dict[str, wrappers.MessageType]) – A dictionary mapping the unified resource type name of a resource message to the corresponding MessageType object representing that resource message. Only resources with a message representation should be included in the dictionary.

Returns

None

with_context(*, collisions: Set[str], visited_messages: Optional[Set[gapic.schema.wrappers.MessageType]] = None) → gapic.schema.wrappers.OperationInfo

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

A representation of a Python primitive type.

classmethod build(primitive_type: Optional[type])

Return a PrimitiveType object for the given Python primitive type.

Parameters

primitive_type (cls) – A Python primitive type, such as int or str. Despite not being a type, None is also accepted here.

Returns

The instantiated PrimitiveType object.

Return type

PrimitiveType

class gapic.schema.wrappers.PythonType(meta: gapic.schema.metadata.Metadata)

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.

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

Representation of the method’s retry behavior.

class gapic.schema.wrappers.RoutingParameter(field: str, path_template: str)

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

classmethod resolve(routing_rule: google.api.routing_pb2.RoutingRule, request: Union[dict, str]) → dict

Resolves the routing header which should be sent along with the request. The routing header is determined based on the given routing rule and request. See the following link for more information on explicit routing headers: https://google.aip.dev/client-libraries/4222#explicit-routing-headers-googleapirouting

Parameters

• routing_rule (routing_pb2.RoutingRule) – A collection of Routing Parameter specifications defined by routing_pb2.RoutingRule. See https://github.com/googleapis/googleapis/blob/cb39bdd75da491466f6c92bc73cd46b0fbd6ba9a/google/api/routing.proto#L391

• request (Union[dict, str]) – The request for which the routine rule should be resolved. The format can be either a dictionary or json string representing the request.

Returns(dict):

A dictionary containing the resolved routing header to the sent along with the given request.

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

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

add_to_address_allowlist(*, address_allowlist: Set[gapic.schema.metadata.Address], method_allowlist: Set[str], resource_messages: Dict[str, gapic.schema.wrappers.MessageType], services_in_proto: Dict[str, gapic.schema.wrappers.Service]) → None

Adds to the allowlist of Addresses of wrapper objects to be included in selective GAPIC generation.

This method is used to create an allowlist of addresses to be used to filter out unneeded services, methods, messages, and enums at a later step.

Parameters

• address_allowlist (Set[metadata.Address]) – A set of allowlisted metadata.Address objects to add to. Only the addresses of the allowlisted methods, the services containing these methods, and messages/enums those methods use will be part of the final address_allowlist. The set may be modified during this call.

• method_allowlist (Set[str]) – An allowlist of fully-qualified method names.

• resource_messages (Dict[str, wrappers.MessageType]) – A dictionary mapping the unified resource type name of a resource message to the corresponding MessageType object representing that resource message. Only resources with a message representation should be included in the dictionary.

• services_in_proto (Dict[str, Service]) –

Returns

None

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

str

property module_name: str

Return the appropriate module name for this service.

Returns

The service name, in snake case.

Return type

str

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]

prune_messages_for_selective_generation(*, address_allowlist: Set[gapic.schema.metadata.Address]) → gapic.schema.wrappers.Service

Returns a truncated version of this Service.

Only the methods, messages, and enums contained in the address allowlist are included in the returned object.

Parameters

address_allowlist (Set[metadata.Address]) – A set of allowlisted metadata.Address objects to filter against. Objects with addresses not the allowlist will be removed from the returned Proto.

Returns

A truncated version of this proto.

Return type

Service

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

str

property version: str

Return the API version for this service, if specified.

Returns

The API version for this service.

Return type

str

with_context(*, collisions: Set[str], visited_messages: Optional[Set[gapic.schema.wrappers.MessageType]] = None) → gapic.schema.wrappers.Service

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.

with_internal_methods(*, public_methods: Set[str]) → gapic.schema.wrappers.Service

Returns a version of this Service with some Methods marked as internal.

The methods not in the public_methods set will be marked as internal and this Service will as well by extension (see Service.is_internal()).

Parameters

public_methods (Set[str]) – An allowlist of fully-qualified method names. Methods not in this allowlist will be marked as internal.

Returns

A version of this Service with Method objects corresponding to methods

not in public_methods marked as internal.

Return type

Service