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"""
51from typing import Callable, Mapping, Optional, Sequence, Tuple
54class ClientOptions(object):
55 """Client Options used to set options on clients.
57 Args:
58 api_endpoint (Optional[str]): The desired API endpoint, e.g.,
59 compute.googleapis.com
60 client_cert_source (Optional[Callable[[], Tuple[bytes, bytes]]]): A callback
61 which returns client certificate bytes and private key bytes both in
62 PEM format. ``client_cert_source`` and ``client_encrypted_cert_source``
63 are mutually exclusive.
64 client_encrypted_cert_source (Optional[Callable[[], Tuple[str, str, bytes]]]):
65 A callback which returns client certificate file path, encrypted
66 private key file path, and the passphrase bytes.``client_cert_source``
67 and ``client_encrypted_cert_source`` are mutually exclusive.
68 quota_project_id (Optional[str]): A project name that a client's
69 quota belongs to.
70 credentials_file (Optional[str]): A path to a file storing credentials.
71 ``credentials_file` and ``api_key`` are mutually exclusive.
73 .. warning::
74 Important: If you accept a credential configuration (credential JSON/File/Stream)
75 from an external source for authentication to Google Cloud Platform, you must
76 validate it before providing it to any Google API or client library. Providing an
77 unvalidated credential configuration to Google APIs or libraries can compromise
78 the security of your systems and data. For more information, refer to
79 `Validate credential configurations from external sources`_.
81 .. _Validate credential configurations from external sources:
83 https://cloud.google.com/docs/authentication/external/externally-sourced-credentials
84 scopes (Optional[Sequence[str]]): OAuth access token override scopes.
85 api_key (Optional[str]): Google API key. ``credentials_file`` and
86 ``api_key`` are mutually exclusive.
87 api_audience (Optional[str]): The intended audience for the API calls
88 to the service that will be set when using certain 3rd party
89 authentication flows. Audience is typically a resource identifier.
90 If not set, the service endpoint value will be used as a default.
91 An example of a valid ``api_audience`` is: "https://language.googleapis.com".
92 universe_domain (Optional[str]): The desired universe domain. This must match
93 the one in credentials. If not set, the default universe domain is
94 `googleapis.com`. If both `api_endpoint` and `universe_domain` are set,
95 then `api_endpoint` is used as the service endpoint. If `api_endpoint` is
96 not specified, the format will be `{service}.{universe_domain}`.
98 Raises:
99 ValueError: If both ``client_cert_source`` and ``client_encrypted_cert_source``
100 are provided, or both ``credentials_file`` and ``api_key`` are provided.
101 """
103 def __init__(
104 self,
105 api_endpoint: Optional[str] = None,
106 client_cert_source: Optional[Callable[[], Tuple[bytes, bytes]]] = None,
107 client_encrypted_cert_source: Optional[
108 Callable[[], Tuple[str, str, bytes]]
109 ] = None,
110 quota_project_id: Optional[str] = None,
111 credentials_file: Optional[str] = None,
112 scopes: Optional[Sequence[str]] = None,
113 api_key: Optional[str] = None,
114 api_audience: Optional[str] = None,
115 universe_domain: Optional[str] = None,
116 ):
117 if client_cert_source and client_encrypted_cert_source:
118 raise ValueError(
119 "client_cert_source and client_encrypted_cert_source are mutually exclusive"
120 )
121 if api_key and credentials_file:
122 raise ValueError("api_key and credentials_file are mutually exclusive")
123 self.api_endpoint = api_endpoint
124 self.client_cert_source = client_cert_source
125 self.client_encrypted_cert_source = client_encrypted_cert_source
126 self.quota_project_id = quota_project_id
127 self.credentials_file = credentials_file
128 self.scopes = scopes
129 self.api_key = api_key
130 self.api_audience = api_audience
131 self.universe_domain = universe_domain
133 def __repr__(self) -> str:
134 return "ClientOptions: " + repr(self.__dict__)
137def from_dict(options: Mapping[str, object]) -> ClientOptions:
138 """Construct a client options object from a mapping object.
140 Args:
141 options (collections.abc.Mapping): A mapping object with client options.
142 See the docstring for ClientOptions for details on valid arguments.
143 """
145 client_options = ClientOptions()
147 for key, value in options.items():
148 if hasattr(client_options, key):
149 setattr(client_options, key, value)
150 else:
151 raise ValueError("ClientOptions does not accept an option '" + key + "'")
153 return client_options