You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
334 lines
14 KiB
Python
334 lines
14 KiB
Python
"""
|
|
This type stub file was generated by pyright.
|
|
"""
|
|
|
|
from email.generator import BytesGenerator
|
|
from googleapiclient._helpers import positional
|
|
|
|
"""Client for discovery based APIs.
|
|
|
|
A client library for Google's discovery based APIs.
|
|
"""
|
|
__author__ = ...
|
|
__all__ = ["build", "build_from_document", "fix_method_name", "key2param"]
|
|
HAS_UNIVERSE = ...
|
|
logger = ...
|
|
URITEMPLATE = ...
|
|
VARNAME = ...
|
|
DISCOVERY_URI = ...
|
|
V1_DISCOVERY_URI = ...
|
|
V2_DISCOVERY_URI = ...
|
|
DEFAULT_METHOD_DOC = ...
|
|
HTTP_PAYLOAD_METHODS = ...
|
|
_MEDIA_SIZE_BIT_SHIFTS = ...
|
|
BODY_PARAMETER_DEFAULT_VALUE = ...
|
|
MEDIA_BODY_PARAMETER_DEFAULT_VALUE = ...
|
|
MEDIA_MIME_TYPE_PARAMETER_DEFAULT_VALUE = ...
|
|
_PAGE_TOKEN_NAMES = ...
|
|
GOOGLE_API_USE_CLIENT_CERTIFICATE = ...
|
|
GOOGLE_API_USE_MTLS_ENDPOINT = ...
|
|
GOOGLE_CLOUD_UNIVERSE_DOMAIN = ...
|
|
DEFAULT_UNIVERSE = ...
|
|
STACK_QUERY_PARAMETERS = ...
|
|
STACK_QUERY_PARAMETER_DEFAULT_VALUE = ...
|
|
class APICoreVersionError(ValueError):
|
|
def __init__(self) -> None:
|
|
...
|
|
|
|
|
|
|
|
RESERVED_WORDS = ...
|
|
class _BytesGenerator(BytesGenerator):
|
|
_write_lines = ...
|
|
|
|
|
|
def fix_method_name(name):
|
|
"""Fix method names to avoid '$' characters and reserved word conflicts.
|
|
|
|
Args:
|
|
name: string, method name.
|
|
|
|
Returns:
|
|
The name with '_' appended if the name is a reserved word and '$' and '-'
|
|
replaced with '_'.
|
|
"""
|
|
...
|
|
|
|
def key2param(key): # -> LiteralString:
|
|
"""Converts key names into parameter names.
|
|
|
|
For example, converting "max-results" -> "max_results"
|
|
|
|
Args:
|
|
key: string, the method key name.
|
|
|
|
Returns:
|
|
A safe method name based on the key name.
|
|
"""
|
|
...
|
|
|
|
@positional(2)
|
|
def build(serviceName, version, http=..., discoveryServiceUrl=..., developerKey=..., model=..., requestBuilder=..., credentials=..., cache_discovery=..., cache=..., client_options=..., adc_cert_path=..., adc_key_path=..., num_retries=..., static_discovery=..., always_use_jwt_access=...):
|
|
"""Construct a Resource for interacting with an API.
|
|
|
|
Construct a Resource object for interacting with an API. The serviceName and
|
|
version are the names from the Discovery service.
|
|
|
|
Args:
|
|
serviceName: string, name of the service.
|
|
version: string, the version of the service.
|
|
http: httplib2.Http, An instance of httplib2.Http or something that acts
|
|
like it that HTTP requests will be made through.
|
|
discoveryServiceUrl: string, a URI Template that points to the location of
|
|
the discovery service. It should have two parameters {api} and
|
|
{apiVersion} that when filled in produce an absolute URI to the discovery
|
|
document for that service.
|
|
developerKey: string, key obtained from
|
|
https://code.google.com/apis/console.
|
|
model: googleapiclient.Model, converts to and from the wire format.
|
|
requestBuilder: googleapiclient.http.HttpRequest, encapsulator for an HTTP
|
|
request.
|
|
credentials: oauth2client.Credentials or
|
|
google.auth.credentials.Credentials, credentials to be used for
|
|
authentication.
|
|
cache_discovery: Boolean, whether or not to cache the discovery doc.
|
|
cache: googleapiclient.discovery_cache.base.CacheBase, an optional
|
|
cache object for the discovery documents.
|
|
client_options: Mapping object or google.api_core.client_options, client
|
|
options to set user options on the client.
|
|
(1) The API endpoint should be set through client_options. If API endpoint
|
|
is not set, `GOOGLE_API_USE_MTLS_ENDPOINT` environment variable can be used
|
|
to control which endpoint to use.
|
|
(2) client_cert_source is not supported, client cert should be provided using
|
|
client_encrypted_cert_source instead. In order to use the provided client
|
|
cert, `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable must be
|
|
set to `true`.
|
|
More details on the environment variables are here:
|
|
https://google.aip.dev/auth/4114
|
|
adc_cert_path: str, client certificate file path to save the application
|
|
default client certificate for mTLS. This field is required if you want to
|
|
use the default client certificate. `GOOGLE_API_USE_CLIENT_CERTIFICATE`
|
|
environment variable must be set to `true` in order to use this field,
|
|
otherwise this field doesn't nothing.
|
|
More details on the environment variables are here:
|
|
https://google.aip.dev/auth/4114
|
|
adc_key_path: str, client encrypted private key file path to save the
|
|
application default client encrypted private key for mTLS. This field is
|
|
required if you want to use the default client certificate.
|
|
`GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable must be set to
|
|
`true` in order to use this field, otherwise this field doesn't nothing.
|
|
More details on the environment variables are here:
|
|
https://google.aip.dev/auth/4114
|
|
num_retries: Integer, number of times to retry discovery with
|
|
randomized exponential backoff in case of intermittent/connection issues.
|
|
static_discovery: Boolean, whether or not to use the static discovery docs
|
|
included in the library. The default value for `static_discovery` depends
|
|
on the value of `discoveryServiceUrl`. `static_discovery` will default to
|
|
`True` when `discoveryServiceUrl` is also not provided, otherwise it will
|
|
default to `False`.
|
|
always_use_jwt_access: Boolean, whether always use self signed JWT for service
|
|
account credentials. This only applies to
|
|
google.oauth2.service_account.Credentials.
|
|
|
|
Returns:
|
|
A Resource object with methods for interacting with the service.
|
|
|
|
Raises:
|
|
google.auth.exceptions.MutualTLSChannelError: if there are any problems
|
|
setting up mutual TLS channel.
|
|
"""
|
|
...
|
|
|
|
@positional(1)
|
|
def build_from_document(service, base=..., future=..., http=..., developerKey=..., model=..., requestBuilder=..., credentials=..., client_options=..., adc_cert_path=..., adc_key_path=..., always_use_jwt_access=...):
|
|
"""Create a Resource for interacting with an API.
|
|
|
|
Same as `build()`, but constructs the Resource object from a discovery
|
|
document that is it given, as opposed to retrieving one over HTTP.
|
|
|
|
Args:
|
|
service: string or object, the JSON discovery document describing the API.
|
|
The value passed in may either be the JSON string or the deserialized
|
|
JSON.
|
|
base: string, base URI for all HTTP requests, usually the discovery URI.
|
|
This parameter is no longer used as rootUrl and servicePath are included
|
|
within the discovery document. (deprecated)
|
|
future: string, discovery document with future capabilities (deprecated).
|
|
http: httplib2.Http, An instance of httplib2.Http or something that acts
|
|
like it that HTTP requests will be made through.
|
|
developerKey: string, Key for controlling API usage, generated
|
|
from the API Console.
|
|
model: Model class instance that serializes and de-serializes requests and
|
|
responses.
|
|
requestBuilder: Takes an http request and packages it up to be executed.
|
|
credentials: oauth2client.Credentials or
|
|
google.auth.credentials.Credentials, credentials to be used for
|
|
authentication.
|
|
client_options: Mapping object or google.api_core.client_options, client
|
|
options to set user options on the client.
|
|
(1) The API endpoint should be set through client_options. If API endpoint
|
|
is not set, `GOOGLE_API_USE_MTLS_ENDPOINT` environment variable can be used
|
|
to control which endpoint to use.
|
|
(2) client_cert_source is not supported, client cert should be provided using
|
|
client_encrypted_cert_source instead. In order to use the provided client
|
|
cert, `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable must be
|
|
set to `true`.
|
|
More details on the environment variables are here:
|
|
https://google.aip.dev/auth/4114
|
|
adc_cert_path: str, client certificate file path to save the application
|
|
default client certificate for mTLS. This field is required if you want to
|
|
use the default client certificate. `GOOGLE_API_USE_CLIENT_CERTIFICATE`
|
|
environment variable must be set to `true` in order to use this field,
|
|
otherwise this field doesn't nothing.
|
|
More details on the environment variables are here:
|
|
https://google.aip.dev/auth/4114
|
|
adc_key_path: str, client encrypted private key file path to save the
|
|
application default client encrypted private key for mTLS. This field is
|
|
required if you want to use the default client certificate.
|
|
`GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable must be set to
|
|
`true` in order to use this field, otherwise this field doesn't nothing.
|
|
More details on the environment variables are here:
|
|
https://google.aip.dev/auth/4114
|
|
always_use_jwt_access: Boolean, whether always use self signed JWT for service
|
|
account credentials. This only applies to
|
|
google.oauth2.service_account.Credentials.
|
|
|
|
Returns:
|
|
A Resource object with methods for interacting with the service.
|
|
|
|
Raises:
|
|
google.auth.exceptions.MutualTLSChannelError: if there are any problems
|
|
setting up mutual TLS channel.
|
|
"""
|
|
...
|
|
|
|
class ResourceMethodParameters:
|
|
"""Represents the parameters associated with a method.
|
|
|
|
Attributes:
|
|
argmap: Map from method parameter name (string) to query parameter name
|
|
(string).
|
|
required_params: List of required parameters (represented by parameter
|
|
name as string).
|
|
repeated_params: List of repeated parameters (represented by parameter
|
|
name as string).
|
|
pattern_params: Map from method parameter name (string) to regular
|
|
expression (as a string). If the pattern is set for a parameter, the
|
|
value for that parameter must match the regular expression.
|
|
query_params: List of parameters (represented by parameter name as string)
|
|
that will be used in the query string.
|
|
path_params: Set of parameters (represented by parameter name as string)
|
|
that will be used in the base URL path.
|
|
param_types: Map from method parameter name (string) to parameter type. Type
|
|
can be any valid JSON schema type; valid values are 'any', 'array',
|
|
'boolean', 'integer', 'number', 'object', or 'string'. Reference:
|
|
http://tools.ietf.org/html/draft-zyp-json-schema-03#section-5.1
|
|
enum_params: Map from method parameter name (string) to list of strings,
|
|
where each list of strings is the list of acceptable enum values.
|
|
"""
|
|
def __init__(self, method_desc) -> None:
|
|
"""Constructor for ResourceMethodParameters.
|
|
|
|
Sets default values and defers to set_parameters to populate.
|
|
|
|
Args:
|
|
method_desc: Dictionary with metadata describing an API method. Value
|
|
comes from the dictionary of methods stored in the 'methods' key in
|
|
the deserialized discovery document.
|
|
"""
|
|
...
|
|
|
|
def set_parameters(self, method_desc): # -> None:
|
|
"""Populates maps and lists based on method description.
|
|
|
|
Iterates through each parameter for the method and parses the values from
|
|
the parameter dictionary.
|
|
|
|
Args:
|
|
method_desc: Dictionary with metadata describing an API method. Value
|
|
comes from the dictionary of methods stored in the 'methods' key in
|
|
the deserialized discovery document.
|
|
"""
|
|
...
|
|
|
|
|
|
|
|
def createMethod(methodName, methodDesc, rootDesc, schema): # -> tuple[Any, Callable[..., Any]]:
|
|
"""Creates a method for attaching to a Resource.
|
|
|
|
Args:
|
|
methodName: string, name of the method to use.
|
|
methodDesc: object, fragment of deserialized discovery document that
|
|
describes the method.
|
|
rootDesc: object, the entire deserialized discovery document.
|
|
schema: object, mapping of schema names to schema descriptions.
|
|
"""
|
|
...
|
|
|
|
def createNextMethod(methodName, pageTokenName=..., nextPageTokenName=..., isPageTokenParameter=...): # -> tuple[Any, Callable[..., Any | None]]:
|
|
"""Creates any _next methods for attaching to a Resource.
|
|
|
|
The _next methods allow for easy iteration through list() responses.
|
|
|
|
Args:
|
|
methodName: string, name of the method to use.
|
|
pageTokenName: string, name of request page token field.
|
|
nextPageTokenName: string, name of response page token field.
|
|
isPageTokenParameter: Boolean, True if request page token is a query
|
|
parameter, False if request page token is a field of the request body.
|
|
"""
|
|
...
|
|
|
|
class Resource:
|
|
"""A class for interacting with a resource."""
|
|
def __init__(self, http, baseUrl, model, requestBuilder, developerKey, resourceDesc, rootDesc, schema, universe_domain=...) -> None:
|
|
"""Build a Resource from the API description.
|
|
|
|
Args:
|
|
http: httplib2.Http, Object to make http requests with.
|
|
baseUrl: string, base URL for the API. All requests are relative to this
|
|
URI.
|
|
model: googleapiclient.Model, converts to and from the wire format.
|
|
requestBuilder: class or callable that instantiates an
|
|
googleapiclient.HttpRequest object.
|
|
developerKey: string, key obtained from
|
|
https://code.google.com/apis/console
|
|
resourceDesc: object, section of deserialized discovery document that
|
|
describes a resource. Note that the top level discovery document
|
|
is considered a resource.
|
|
rootDesc: object, the entire deserialized discovery document.
|
|
schema: object, mapping of schema names to schema descriptions.
|
|
universe_domain: string, the universe for the API. The default universe
|
|
is "googleapis.com".
|
|
"""
|
|
...
|
|
|
|
def __getstate__(self): # -> dict[str, Any]:
|
|
"""Trim the state down to something that can be pickled.
|
|
|
|
Uses the fact that the instance variable _dynamic_attrs holds attrs that
|
|
will be wiped and restored on pickle serialization.
|
|
"""
|
|
...
|
|
|
|
def __setstate__(self, state): # -> None:
|
|
"""Reconstitute the state of the object from being pickled.
|
|
|
|
Uses the fact that the instance variable _dynamic_attrs holds attrs that
|
|
will be wiped and restored on pickle serialization.
|
|
"""
|
|
...
|
|
|
|
def __enter__(self): # -> Self:
|
|
...
|
|
|
|
def __exit__(self, exc_type, exc, exc_tb): # -> None:
|
|
...
|
|
|
|
def close(self): # -> None:
|
|
"""Close httplib2 connections."""
|
|
...
|
|
|
|
|
|
|