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
51
52class ClientOptions(object):
53    """Client Options used to set options on clients.
54
55    Args:
56        api_endpoint (Optional[str]): The desired API endpoint, e.g.,
57            compute.googleapis.com
58        client_cert_source (Optional[Callable[[], (bytes, bytes)]]): A callback
59            which returns client certificate bytes and private key bytes both in
60            PEM format. ``client_cert_source`` and ``client_encrypted_cert_source``
61            are mutually exclusive.
62        client_encrypted_cert_source (Optional[Callable[[], (str, str, bytes)]]):
63            A callback which returns client certificate file path, encrypted
64            private key file path, and the passphrase bytes.``client_cert_source``
65            and ``client_encrypted_cert_source`` are mutually exclusive.
66        quota_project_id (Optional[str]): A project name that a client's
67            quota belongs to.
68        credentials_file (Optional[str]): A path to a file storing credentials.
69        scopes (Optional[Sequence[str]]): OAuth access token override scopes.
70
71    Raises:
72        ValueError: If both ``client_cert_source`` and ``client_encrypted_cert_source``
73            are provided.
74    """
75
76    def __init__(
77        self,
78        api_endpoint=None,
79        client_cert_source=None,
80        client_encrypted_cert_source=None,
81        quota_project_id=None,
82        credentials_file=None,
83        scopes=None,
84    ):
85        if client_cert_source and client_encrypted_cert_source:
86            raise ValueError(
87                "client_cert_source and client_encrypted_cert_source are mutually exclusive"
88            )
89        self.api_endpoint = api_endpoint
90        self.client_cert_source = client_cert_source
91        self.client_encrypted_cert_source = client_encrypted_cert_source
92        self.quota_project_id = quota_project_id
93        self.credentials_file = credentials_file
94        self.scopes = scopes
95
96    def __repr__(self):
97        return "ClientOptions: " + repr(self.__dict__)
98
99
100def from_dict(options):
101    """Construct a client options object from a mapping object.
102
103    Args:
104        options (collections.abc.Mapping): A mapping object with client options.
105            See the docstring for ClientOptions for details on valid arguments.
106    """
107
108    client_options = ClientOptions()
109
110    for key, value in options.items():
111        if hasattr(client_options, key):
112            setattr(client_options, key, value)
113        else:
114            raise ValueError("ClientOptions does not accept an option '" + key + "'")
115
116    return client_options
117