Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# Copyright 2019 Google LLC
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7# http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
15"""Client options class.
17Client options provide a consistent interface for user options to be defined
18across clients.
20You can pass a client options object to a client.
22.. code-block:: python
24 from google.api_core.client_options import ClientOptions
25 from google.cloud.vision_v1 import ImageAnnotatorClient
27 def get_client_cert():
28 # code to load client certificate and private key.
29 return client_cert_bytes, client_private_key_bytes
31 options = ClientOptions(api_endpoint="foo.googleapis.com",
32 client_cert_source=get_client_cert)
34 client = ImageAnnotatorClient(client_options=options)
36You can also pass a mapping object.
38.. code-block:: python
40 from google.cloud.vision_v1 import ImageAnnotatorClient
42 client = ImageAnnotatorClient(
43 client_options={
44 "api_endpoint": "foo.googleapis.com",
45 "client_cert_source" : get_client_cert
46 })
49"""
51import typing
52import warnings
53from typing import Callable, Mapping, Optional, Sequence, Tuple
55if typing.TYPE_CHECKING:
56 import opentelemetry.trace
58from google.api_core import general_helpers
61class ClientOptions(object):
62 """Client Options used to set options on clients.
64 Args:
65 api_endpoint (Optional[str]): The desired API endpoint, e.g.,
66 compute.googleapis.com
67 client_cert_source (Optional[Callable[[], Tuple[bytes, bytes]]]): A callback
68 which returns client certificate bytes and private key bytes both in
69 PEM format. ``client_cert_source`` and ``client_encrypted_cert_source``
70 are mutually exclusive.
71 client_encrypted_cert_source (Optional[Callable[[], Tuple[str, str, bytes]]]):
72 A callback which returns client certificate file path, encrypted
73 private key file path, and the passphrase bytes.``client_cert_source``
74 and ``client_encrypted_cert_source`` are mutually exclusive.
75 quota_project_id (Optional[str]): A project name that a client's
76 quota belongs to.
77 credentials_file (Optional[str]): Deprecated. A path to a file storing credentials.
78 ``credentials_file` and ``api_key`` are mutually exclusive. This argument will be
79 removed in the next major version of `google-api-core`.
81 .. warning::
82 Important: If you accept a credential configuration (credential JSON/File/Stream)
83 from an external source for authentication to Google Cloud Platform, you must
84 validate it before providing it to any Google API or client library. Providing an
85 unvalidated credential configuration to Google APIs or libraries can compromise
86 the security of your systems and data. For more information, refer to
87 `Validate credential configurations from external sources`_.
89 .. _Validate credential configurations from external sources:
91 https://cloud.google.com/docs/authentication/external/externally-sourced-credentials
92 scopes (Optional[Sequence[str]]): OAuth access token override scopes.
93 api_key (Optional[str]): Google API key. ``credentials_file`` and
94 ``api_key`` are mutually exclusive.
95 api_audience (Optional[str]): The intended audience for the API calls
96 to the service that will be set when using certain 3rd party
97 authentication flows. Audience is typically a resource identifier.
98 If not set, the service endpoint value will be used as a default.
99 An example of a valid ``api_audience`` is: "https://language.googleapis.com".
100 universe_domain (Optional[str]): The desired universe domain. This must match
101 the one in credentials. If not set, the default universe domain is
102 `googleapis.com`. If both `api_endpoint` and `universe_domain` are set,
103 then `api_endpoint` is used as the service endpoint. If `api_endpoint` is
104 not specified, the format will be `{service}.{universe_domain}`.
105 tracer_provider (Optional["opentelemetry.trace.TracerProvider"]): The OpenTelemetry tracer provider to use
106 for tracing in supported libraries.
108 Raises:
109 ValueError: If both ``client_cert_source`` and ``client_encrypted_cert_source``
110 are provided, or both ``credentials_file`` and ``api_key`` are provided.
111 """
113 def __init__(
114 self,
115 api_endpoint: Optional[str] = None,
116 client_cert_source: Optional[Callable[[], Tuple[bytes, bytes]]] = None,
117 client_encrypted_cert_source: Optional[
118 Callable[[], Tuple[str, str, bytes]]
119 ] = None,
120 quota_project_id: Optional[str] = None,
121 credentials_file: Optional[str] = None,
122 scopes: Optional[Sequence[str]] = None,
123 api_key: Optional[str] = None,
124 api_audience: Optional[str] = None,
125 universe_domain: Optional[str] = None,
126 tracer_provider: Optional["opentelemetry.trace.TracerProvider"] = None,
127 ):
128 if credentials_file is not None:
129 warnings.warn(general_helpers._CREDENTIALS_FILE_WARNING, DeprecationWarning)
131 if client_cert_source and client_encrypted_cert_source:
132 raise ValueError(
133 "client_cert_source and client_encrypted_cert_source are mutually exclusive"
134 )
135 if api_key and credentials_file:
136 raise ValueError("api_key and credentials_file are mutually exclusive")
137 self.api_endpoint = api_endpoint
138 self.client_cert_source = client_cert_source
139 self.client_encrypted_cert_source = client_encrypted_cert_source
140 self.quota_project_id = quota_project_id
141 self.credentials_file = credentials_file
142 self.scopes = scopes
143 self.api_key = api_key
144 self.api_audience = api_audience
145 self.universe_domain = universe_domain
146 self.tracer_provider = tracer_provider
148 def __repr__(self) -> str:
149 return "ClientOptions: " + repr(self.__dict__)
152def from_dict(options: Mapping[str, object]) -> ClientOptions:
153 """Construct a client options object from a mapping object.
155 Args:
156 options (collections.abc.Mapping): A mapping object with client options.
157 See the docstring for ClientOptions for details on valid arguments.
158 """
160 client_options = ClientOptions()
162 for key, value in options.items():
163 if hasattr(client_options, key):
164 setattr(client_options, key, value)
165 else:
166 raise ValueError("ClientOptions does not accept an option '" + key + "'")
168 return client_options