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. 14 15"""Client options class. 16 17Client options provide a consistent interface for user options to be defined 18across clients. 19 20You can pass a client options object to a client. 21 22.. code-block:: python 23 24 from google.api_core.client_options import ClientOptions 25 from google.cloud.vision_v1 import ImageAnnotatorClient 26 27 def get_client_cert(): 28 # code to load client certificate and private key. 29 return client_cert_bytes, client_private_key_bytes 30 31 options = ClientOptions(api_endpoint="foo.googleapis.com", 32 client_cert_source=get_client_cert) 33 34 client = ImageAnnotatorClient(client_options=options) 35 36You can also pass a mapping object. 37 38.. code-block:: python 39 40 from google.cloud.vision_v1 import ImageAnnotatorClient 41 42 client = ImageAnnotatorClient( 43 client_options={ 44 "api_endpoint": "foo.googleapis.com", 45 "client_cert_source" : get_client_cert 46 }) 47 48 49""" 50 51from typing import Callable, Mapping, Optional, Sequence, Tuple 52 53 54class ClientOptions(object): 55 """Client Options used to set options on clients. 56 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. 72 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`_. 80 81 .. _Validate credential configurations from external sources: 82 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}`. 97 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 """ 102 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 132 133 def __repr__(self) -> str: 134 return "ClientOptions: " + repr(self.__dict__) 135 136 137def from_dict(options: Mapping[str, object]) -> ClientOptions: 138 """Construct a client options object from a mapping object. 139 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 """ 144 145 client_options = ClientOptions() 146 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 + "'") 152 153 return client_options 154