pinecone.openapi_support.configuration

  1import copy
  2import logging
  3import multiprocessing
  4
  5from http import client as http_client
  6from .exceptions import PineconeApiValueError
  7from typing import TypedDict
  8
  9
 10class HostSetting(TypedDict):
 11    url: str
 12    description: str
 13
 14
 15JSON_SCHEMA_VALIDATION_KEYWORDS = {
 16    "multipleOf",
 17    "maximum",
 18    "exclusiveMaximum",
 19    "minimum",
 20    "exclusiveMinimum",
 21    "maxLength",
 22    "minLength",
 23    "pattern",
 24    "maxItems",
 25    "minItems",
 26}
 27
 28
 29class Configuration:
 30    """Class to hold the configuration of the API client.
 31
 32        :param host: Base url
 33        :param api_key: Dict to store API key(s).
 34          Each entry in the dict specifies an API key.
 35          The dict key is the name of the security scheme in the OAS specification.
 36          The dict value is the API key secret.
 37        :param api_key_prefix: Dict to store API prefix (e.g. Bearer)
 38          The dict key is the name of the security scheme in the OAS specification.
 39          The dict value is an API key prefix when generating the auth data.
 40        :param discard_unknown_keys: Boolean value indicating whether to discard
 41          unknown properties. A server may send a response that includes additional
 42          properties that are not known by the client in the following scenarios:
 43          1. The OpenAPI document is incomplete, i.e. it does not match the server
 44             implementation.
 45          2. The client was generated using an older version of the OpenAPI document
 46             and the server has been upgraded since then.
 47          If a schema in the OpenAPI document defines the additionalProperties attribute,
 48          then all undeclared properties received by the server are injected into the
 49          additional properties map. In that case, there are undeclared properties, and
 50          nothing to discard.
 51        :param disabled_client_side_validations (string): Comma-separated list of
 52          JSON schema validation keywords to disable JSON schema structural validation
 53          rules. The following keywords may be specified: multipleOf, maximum,
 54          exclusiveMaximum, minimum, exclusiveMinimum, maxLength, minLength, pattern,
 55          maxItems, minItems.
 56          By default, the validation is performed for data generated locally by the client
 57          and data received from the server, independent of any validation performed by
 58          the server side. If the input data does not satisfy the JSON schema validation
 59          rules specified in the OpenAPI document, an exception is raised.
 60          If disabled_client_side_validations is set, structural validation is
 61          disabled. This can be useful to troubleshoot data validation problem, such as
 62          when the OpenAPI document validation rules do not match the actual API data
 63          received by the server.
 64        :param server_operation_index: Mapping from operation ID to an index to server
 65          configuration.
 66        :param server_operation_variables: Mapping from operation ID to a mapping with
 67          string values to replace variables in templated server configuration.
 68          The validation of enums is performed for variables with defined enum values before.
 69        :param ssl_ca_cert: str - the path to a file of concatenated CA certificates
 70          in PEM format
 71
 72        :Example:
 73
 74        API Key Authentication Example.
 75        Given the following security scheme in the OpenAPI specification:
 76          components:
 77            securitySchemes:
 78              cookieAuth:         # name for the security scheme
 79                type: apiKey
 80                in: cookie
 81                name: JSESSIONID  # cookie name
 82
 83        You can programmatically set the cookie:
 84
 85    conf = pinecone.openapi_support.Configuration(
 86        api_key={'cookieAuth': 'abc123'}
 87        api_key_prefix={'cookieAuth': 'JSESSIONID'}
 88    )
 89
 90        The following cookie will be added to the HTTP request:
 91           Cookie: JSESSIONID abc123
 92    """
 93
 94    _default = None
 95
 96    def __init__(
 97        self,
 98        host=None,
 99        api_key=None,
100        api_key_prefix=None,
101        discard_unknown_keys=False,
102        disabled_client_side_validations="",
103        server_index=None,
104        server_variables=None,
105        server_operation_index=None,
106        server_operation_variables=None,
107        ssl_ca_cert=None,
108    ):
109        """Constructor"""
110        self._base_path = "https://api.pinecone.io" if host is None else host
111        """Default Base url
112        """
113        self.server_index = 0 if server_index is None and host is None else server_index
114        self.server_operation_index = server_operation_index or {}
115        """Default server index
116        """
117        self.server_variables = server_variables or {}
118        self.server_operation_variables = server_operation_variables or {}
119        """Default server variables
120        """
121        self.temp_folder_path = None
122        """Temp file folder for downloading files
123        """
124        # Authentication Settings
125        self.api_key = {}
126        if api_key:
127            self.api_key = api_key
128        """dict to store API key(s)
129        """
130        self.api_key_prefix = {}
131        if api_key_prefix:
132            self.api_key_prefix = api_key_prefix
133        """dict to store API prefix (e.g. Bearer)
134        """
135        self.refresh_api_key_hook = None
136        """function hook to refresh API key if expired
137        """
138        self.discard_unknown_keys = discard_unknown_keys
139        self.disabled_client_side_validations = disabled_client_side_validations
140        self.logger = {}
141        """Logging Settings
142        """
143        self.logger["package_logger"] = logging.getLogger("pinecone.openapi_support")
144        self.logger["urllib3_logger"] = logging.getLogger("urllib3")
145        self.logger_format = "%(asctime)s %(levelname)s %(message)s"
146        """Log format
147        """
148        self.logger_stream_handler = None
149        """Log stream handler
150        """
151        self.logger_file_handler = None
152        """Log file handler
153        """
154        self.logger_file = None
155        """Debug file location
156        """
157        self.debug = False
158        """Debug switch
159        """
160
161        self.verify_ssl = True
162        """SSL/TLS verification
163           Set this to false to skip verifying SSL certificate when calling API
164           from https server.
165        """
166        self.ssl_ca_cert = ssl_ca_cert
167        """Set this to customize the certificate file to verify the peer.
168        """
169        self.cert_file = None
170        """client certificate file
171        """
172        self.key_file = None
173        """client key file
174        """
175        self.assert_hostname = None
176        """Set this to True/False to enable/disable SSL hostname verification.
177        """
178
179        self.connection_pool_maxsize = multiprocessing.cpu_count() * 5
180        """urllib3 connection pool's maximum number of connections saved
181           per pool. urllib3 uses 1 connection as default value, but this is
182           not the best value when you are making a lot of possibly parallel
183           requests to the same host, which is often the case here.
184           cpu_count * 5 is used as default value to increase performance.
185        """
186
187        self.proxy = None
188        """Proxy URL
189        """
190        self.proxy_headers = None
191        """Proxy headers
192        """
193        self.safe_chars_for_path_param = ""
194        """Safe chars for path_param
195        """
196        self.retries = None
197        """Adding retries to override urllib3 default value 3
198        """
199        # Enable client side validation
200        self.client_side_validation = True
201
202        # Options to pass down to the underlying urllib3 socket
203        self.socket_options = None
204
205    def __deepcopy__(self, memo):
206        cls = self.__class__
207        result = cls.__new__(cls)
208        memo[id(self)] = result
209        for k, v in self.__dict__.items():
210            if k not in ("logger", "logger_file_handler"):
211                setattr(result, k, copy.deepcopy(v, memo))
212        # shallow copy of loggers
213        result.logger = copy.copy(self.logger)
214        # use setters to configure loggers
215        result.logger_file = self.logger_file
216        result.debug = self.debug
217        return result
218
219    def __setattr__(self, name, value):
220        object.__setattr__(self, name, value)
221        if name == "disabled_client_side_validations":
222            s = set(filter(None, value.split(",")))
223            for v in s:
224                if v not in JSON_SCHEMA_VALIDATION_KEYWORDS:
225                    raise PineconeApiValueError("Invalid keyword: '{0}''".format(v))
226            self._disabled_client_side_validations = s
227
228    @classmethod
229    def set_default(cls, default):
230        """Set default instance of configuration.
231
232        It stores default configuration, which can be
233        returned by get_default_copy method.
234
235        :param default: object of Configuration
236        """
237        cls._default = copy.deepcopy(default)
238
239    @classmethod
240    def get_default_copy(cls):
241        """Return new instance of configuration.
242
243        This method returns newly created, based on default constructor,
244        object of Configuration class or returns a copy of default
245        configuration passed by the set_default method.
246
247        :return: The configuration object.
248        """
249        if cls._default is not None:
250            return copy.deepcopy(cls._default)
251        return Configuration()
252
253    @property
254    def logger_file(self):
255        """The logger file.
256
257        If the logger_file is None, then add stream handler and remove file
258        handler. Otherwise, add file handler and remove stream handler.
259
260        :param value: The logger_file path.
261        :type: str
262        """
263        return self.__logger_file
264
265    @logger_file.setter
266    def logger_file(self, value):
267        """The logger file.
268
269        If the logger_file is None, then add stream handler and remove file
270        handler. Otherwise, add file handler and remove stream handler.
271
272        :param value: The logger_file path.
273        :type: str
274        """
275        self.__logger_file = value
276        if self.__logger_file:
277            # If set logging file,
278            # then add file handler and remove stream handler.
279            self.logger_file_handler = logging.FileHandler(self.__logger_file)
280            self.logger_file_handler.setFormatter(self.logger_formatter)
281            for _, logger in self.logger.items():
282                logger.addHandler(self.logger_file_handler)
283
284    @property
285    def debug(self):
286        """Debug status
287
288        :param value: The debug status, True or False.
289        :type: bool
290        """
291        return self.__debug
292
293    @debug.setter
294    def debug(self, value):
295        """Debug status
296
297        :param value: The debug status, True or False.
298        :type: bool
299        """
300        self.__debug = value
301        if self.__debug:
302            # if debug status is True, turn on debug logging
303            for _, logger in self.logger.items():
304                logger.setLevel(logging.DEBUG)
305            # turn on http_client debug
306            http_client.HTTPConnection.debuglevel = 1
307        else:
308            # if debug status is False, turn off debug logging,
309            # setting log level to default `logging.WARNING`
310            for _, logger in self.logger.items():
311                logger.setLevel(logging.WARNING)
312            # turn off http_client debug
313            http_client.HTTPConnection.debuglevel = 0
314
315    @property
316    def logger_format(self):
317        """The logger format.
318
319        The logger_formatter will be updated when sets logger_format.
320
321        :param value: The format string.
322        :type: str
323        """
324        return self.__logger_format
325
326    @logger_format.setter
327    def logger_format(self, value):
328        """The logger format.
329
330        The logger_formatter will be updated when sets logger_format.
331
332        :param value: The format string.
333        :type: str
334        """
335        self.__logger_format = value
336        self.logger_formatter = logging.Formatter(self.__logger_format)
337
338    def get_api_key_with_prefix(self, identifier, alias=None):
339        """Gets API key (with prefix if set).
340
341        :param identifier: The identifier of apiKey.
342        :param alias: The alternative identifier of apiKey.
343        :return: The token for api key authentication.
344        """
345        if self.refresh_api_key_hook is not None:
346            self.refresh_api_key_hook(self)
347        key = self.api_key.get(identifier, self.api_key.get(alias) if alias is not None else None)
348        if key:
349            prefix = self.api_key_prefix.get(identifier)
350            if prefix:
351                return "%s %s" % (prefix, key)
352            else:
353                return key
354
355    def auth_settings(self):
356        """Gets Auth Settings dict for api client.
357
358        :return: The Auth Settings information dict.
359        """
360        auth = {}
361        if "ApiKeyAuth" in self.api_key:
362            auth["ApiKeyAuth"] = {
363                "type": "api_key",
364                "in": "header",
365                "key": "Api-Key",
366                "value": self.get_api_key_with_prefix("ApiKeyAuth"),
367            }
368        return auth
369
370    def get_host_settings(self):
371        """Gets an array of host settings
372
373        :return: An array of host settings
374        """
375        return [{"url": "https://api.pinecone.io", "description": "Production API endpoints"}]
376
377    def get_host_from_settings(self, index, variables=None, servers=None):
378        """Gets host URL based on the index and variables
379        :param index: array index of the host settings
380        :param variables: hash of variable and the corresponding value
381        :param servers: an array of host settings or None
382        :return: URL based on host settings
383        """
384        if index is None:
385            return self._base_path
386
387        variables = {} if variables is None else variables
388        servers = self.get_host_settings() if servers is None else servers
389
390        try:
391            server = servers[index]
392        except IndexError:
393            raise ValueError(
394                "Invalid index {0} when selecting the host settings. Must be less than {1}".format(
395                    index, len(servers)
396                )
397            )
398
399        url = server["url"]
400
401        # go through variables and replace placeholders
402        for variable_name, variable in server.get("variables", {}).items():
403            used_value = variables.get(variable_name, variable["default_value"])
404
405            if "enum_values" in variable and used_value not in variable["enum_values"]:
406                raise ValueError(
407                    "The variable `{0}` in the host URL has invalid value {1}. Must be {2}.".format(
408                        variable_name, variables[variable_name], variable["enum_values"]
409                    )
410                )
411
412            url = url.replace("{" + variable_name + "}", used_value)
413
414        return url
415
416    @property
417    def host(self):
418        """Return generated host."""
419        return self.get_host_from_settings(self.server_index, variables=self.server_variables)
420
421    @host.setter
422    def host(self, value):
423        """Fix base path."""
424        self._base_path = value
425        self.server_index = None
426
427    def __repr__(self):
428        attrs = [
429            f"host={self.host}",
430            "api_key=***",
431            f"api_key_prefix={self.api_key_prefix}",
432            f"connection_pool_maxsize={self.connection_pool_maxsize}",
433            f"discard_unknown_keys={self.discard_unknown_keys}",
434            f"disabled_client_side_validations={self.disabled_client_side_validations}",
435            f"server_index={self.server_index}",
436            f"server_variables={self.server_variables}",
437            f"server_operation_index={self.server_operation_index}",
438            f"server_operation_variables={self.server_operation_variables}",
439            f"ssl_ca_cert={self.ssl_ca_cert}",
440        ]
441        return f"Configuration({', '.join(attrs)})"