oracle-ads 2.13.7__py3-none-any.whl → 2.13.9rc0__py3-none-any.whl

ads/common/oci_resource.py

@@ -1,136 +0,0 @@
-#!/usr/bin/env python
-# -*- coding: utf-8; -*-
-
-# Copyright (c) 2021, 2022 Oracle and/or its affiliates.
-# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
-
-"""Contains class wrapping OCI resource search service
-"""
-import oci.resource_search
-from ads.common.oci_mixin import OCIClientMixin
-
-
-class ResourceNotFoundError(Exception):   # pragma: no cover
-    """Exception when an OCI resource is not found or user does not have permission to access it.
-    This could mean the resource does not exist, or
-    there is not enough permission to find/access the resource.
-    """
-
-
-class SEARCH_TYPE(str):
-    FREETEXT = "FreeText"
-    STRUCTURED = "Structured"
-
-
-class OCIResource(OCIClientMixin):
-    """Contains helper methods for getting information from OCIResourceSearch service.
-
-    Usage:
-    Find the compartment ID of an OCI resource:
-    >>> OCIResource.get_compartment_id("YOUR_OCID")
-    Search for OCI resource matching free text (Similar to the search box in OCI console):
-    >>> OCIResource.search("YOUR_FREE_TEXT")
-    Search for OCI resource matching structured text:
-    >>> OCIResource.search("STRUCTURED_TEXT", type="Structured")
-    """
-
-    @classmethod
-    def init_client(cls, **kwargs) -> oci.resource_search.ResourceSearchClient:
-        return cls._init_client(
-            client=oci.resource_search.ResourceSearchClient, **kwargs
-        )
-
-    @classmethod
-    def get_compartment_id(cls, ocid) -> str:
-        """Gets the compartment OCID of an OCI resource, given the resource's OCID.
-
-        Parameters
-        ----------
-        ocid : str
-            OCID of a resource
-
-        Returns
-        -------
-        str:
-            Compartment OCID of the resource
-
-
-        """
-        results = set([r.compartment_id for r in cls.search(ocid)])
-        if len(results) == 1:
-            return list(results)[0]
-        elif not results:
-            raise ResourceNotFoundError(
-                f"Resource not found for {ocid}. It may not exist or you may not have permission to list/access it."
-            )
-        else:
-            raise ValueError(
-                f"Unable determine compartment ID, multiple matches: {results}"
-            )
-
-    @classmethod
-    def search(
-        cls,
-        query: str,
-        type: str = "FreeText",
-        config: dict = None,
-        tenant_id: str = None,
-        limit: int = 500,
-        page: str = None,
-        **kwargs,
-    ) -> list:
-        """Search OCI resource by free text.
-
-        Parameters
-        ----------
-        query : str
-            The content to search for.
-        type :  str (optional)
-            The type of SearchDetails, whether "FreeText" or "Structured".
-            Defaults to "FreeText".
-        config: dict (optional)
-            Configuration keys and values as per SDK and Tool Configuration.
-            The from_file() method can be used to load configuration from a file.
-            Alternatively, a dict can be passed. You can validate_config the dict
-            using validate_config(). Defaults to None.
-        tenant_id: str (optional)
-            The tenancy ID, which can be used to specify a different tenancy
-            (for cross-tenancy authorization) when searching for resources in
-            a different tenancy. Defaults to None.
-        limit: int (optional)
-            The maximum number of items to return. The value must be between
-            1 and 1000. Defaults to 500.
-        page: str (optional)
-            The page at which to start retrieving results.
-
-        Returns
-        -------
-        list
-            A list of search results
-
-        """
-        if not config:
-            client = cls.init_client()
-        else:
-            client = oci.resource_search.ResourceSearchClient(config=config)
-
-        if type == "Structured":
-            search_details = oci.resource_search.models.StructuredSearchDetails(
-                type="Structured",
-                query=query,
-                matching_context_type=None,
-            )
-        elif type == "FreeText":
-            search_details = oci.resource_search.models.FreeTextSearchDetails(
-                text=query, type="FreeText"
-            )
-        else:
-            raise ValueError(f"Invalid Type: {type}")
-
-        return client.search_resources(
-            search_details,
-            limit=limit,
-            page=page,
-            tenant_id=tenant_id,
-            **kwargs,
-        ).data.items

ads/common/serializer.py

@@ -1,559 +0,0 @@
-#!/usr/bin/env python
-
-# Copyright (c) 2021, 2024 Oracle and/or its affiliates.
-# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
-
-"""
-This module provides a base class for serializable items, as well as methods for serializing and
-deserializing objects to and from JSON and YAML formats. It also includes methods for reading and
-writing serialized objects to and from files.
-"""
-
-import dataclasses
-import json
-from abc import ABC, abstractmethod
-from datetime import datetime
-from enum import Enum
-from typing import Dict, Optional, Union
-from urllib.parse import urlparse
-
-import fsspec
-import yaml
-
-from ads.common import logger
-from ads.common.auth import default_signer
-
-try:
-    from yaml import CSafeLoader as loader
-except:
-    from yaml import SafeLoader as loader
-
-
-class SideEffect(Enum):
-    CONVERT_KEYS_TO_LOWER = "lower"
-    CONVERT_KEYS_TO_UPPER = "upper"
-
-
-class Serializable(ABC):
-    """Base class that represents a serializable item.
-
-    Methods
-    -------
-    to_dict(self) -> dict
-        Serializes the object into a dictionary.
-    from_dict(cls, obj_dict) -> cls
-        Returns an instance of the class instantiated from the dictionary provided.
-    _write_to_file(s, uri, **kwargs)
-        Write string s into location specified by uri
-    _read_from_file(uri, **kwargs)
-        Returns contents from location specified by URI
-    to_json(self, uri=None, **kwargs)
-        Returns object serialized as a JSON string
-    from_json(cls, json_string=None, uri=None, **kwargs)
-        Creates an object from JSON string provided or from URI location containing JSON string
-    to_yaml(self, uri=None, **kwargs)
-        Returns object serialized as a YAML string
-    from_yaml(cls, yaml_string=None, uri=None, **kwargs)
-        Creates an object from YAML string provided or from URI location containing YAML string
-    from_string(cls, obj_string=None: str, uri=None, **kwargs)
-        Creates an object from string provided or from URI location containing string
-    """
-
-    @abstractmethod
-    def to_dict(self, **kwargs: Dict) -> Dict:
-        """Serializes an instance of class into a dictionary.
-
-        Parameters
-        ----------
-        **kwargs: Dict
-            Additional arguments.
-
-        Returns
-        -------
-        Dict
-            The result dictionary.
-        """
-
-    @classmethod
-    @abstractmethod
-    def from_dict(cls, obj_dict: dict, **kwargs) -> "Serializable":
-        """Returns an instance of the class instantiated by the dictionary provided.
-
-        Parameters
-        ----------
-        obj_dict: (dict)
-            Dictionary representation of the object.
-
-        Returns
-        -------
-        Serializable
-            A Serializable instance.
-        """
-        pass
-
-    @staticmethod
-    def serialize(obj):
-        """JSON serializer for objects not serializable by default json code."""
-        if isinstance(obj, datetime):
-            return obj.isoformat()
-        if hasattr(obj, "to_dict"):
-            return obj.to_dict()
-        raise TypeError(f"Type {type(obj)} not serializable.")
-
-    @staticmethod
-    def _write_to_file(s: str, uri: str, **kwargs) -> None:
-        """Write string s into location specified by uri.
-
-        Parameters
-        ----------
-        s: (string)
-            content
-        uri: (string)
-            URI location to save string s
-        kwargs : dict
-            keyword arguments to be passed into fsspec.open().
-            For OCI object storage, this can be config="path/to/.oci/config".
-
-        Returns
-        -------
-        None
-            Nothing
-        """
-
-        overwrite = kwargs.pop("overwrite", True)
-        if not overwrite:
-            dst_path_scheme = urlparse(uri).scheme or "file"
-            if fsspec.filesystem(dst_path_scheme, **kwargs).exists(uri):
-                raise FileExistsError(
-                    f"The `{uri}` is already exists. Set `overwrite` to True "
-                    "if you wish to overwrite."
-                )
-
-        with fsspec.open(uri, "w", **kwargs) as f:
-            f.write(s)
-
-    @staticmethod
-    def _read_from_file(uri: str, **kwargs) -> str:
-        """Returns contents from location specified by URI
-
-        Parameters
-        ----------
-        uri: (string)
-            URI location
-        kwargs : dict
-            keyword arguments to be passed into fsspec.open().
-            For OCI object storage, this can be config="path/to/.oci/config".
-
-        Returns
-        -------
-        string: Contents in file specified by URI
-        """
-        # Add default signer if the uri is an object storage uri, and
-        # the user does not specify config or signer.
-        if (
-            uri.startswith("oci://")
-            and "config" not in kwargs
-            and "signer" not in kwargs
-        ):
-            kwargs.update(default_signer())
-        with fsspec.open(uri, "r", **kwargs) as f:
-            return f.read()
-
-    def to_json(
-        self,
-        uri: str = None,
-        encoder: callable = json.JSONEncoder,
-        default: callable = None,
-        **kwargs,
-    ) -> str:
-        """Returns object serialized as a JSON string
-
-        Parameters
-        ----------
-        uri: (string, optional)
-            URI location to save the JSON string. Defaults to None.
-        encoder: (callable, optional)
-            Encoder for custom data structures. Defaults to JSONEncoder.
-        default: (callable, optional)
-            A function that gets called for objects that can't otherwise be serialized.
-            It should return JSON-serializable version of the object or original object.
-
-        kwargs
-        ------
-        overwrite: (bool, optional). Defaults to True.
-            Whether to overwrite existing file or not.
-
-        keyword arguments to be passed into fsspec.open().
-        For OCI object storage, this could be config="path/to/.oci/config".
-        For other storage connections consider e.g. host, port, username, password, etc.
-
-        Returns
-        -------
-        Union[str, None]
-            Serialized version of object.
-            `None` in case when `uri` provided.
-        """
-        json_string = json.dumps(
-            self.to_dict(**kwargs),
-            cls=encoder,
-            default=default or self.serialize,
-            indent=4,
-        )
-        if uri:
-            self._write_to_file(s=json_string, uri=uri, **kwargs)
-            return None
-        return json_string
-
-    @classmethod
-    def from_json(
-        cls,
-        json_string: str = None,
-        uri: str = None,
-        decoder: callable = json.JSONDecoder,
-        **kwargs,
-    ):
-        """Creates an object from JSON string provided or from URI location containing JSON string
-
-        Parameters
-        ----------
-        json_string: (string, optional)
-            JSON string. Defaults to None.
-        uri: (string, optional)
-            URI location of file containing JSON string. Defaults to None.
-        decoder: (callable, optional)
-            Custom decoder. Defaults to simple JSON decoder.
-        kwargs
-        ------
-        keyword arguments to be passed into fsspec.open(). For OCI object storage, this should be config="path/to/.oci/config".
-            For other storage connections consider e.g. host, port, username, password, etc.
-
-        Raises
-        ------
-        ValueError
-            Raised if neither string nor uri is provided
-
-        Returns
-        -------
-        cls
-            Returns instance of the class
-        """
-        if json_string:
-            return cls.from_dict(json.loads(json_string, cls=decoder), **kwargs)
-        if uri:
-            json_dict = json.loads(cls._read_from_file(uri, **kwargs), cls=decoder)
-            return cls.from_dict(json_dict)
-        raise ValueError("Must provide either JSON string or URI location")
-
-    def to_yaml(
-        self, uri: str = None, dumper: callable = yaml.SafeDumper, **kwargs
-    ) -> Union[str, None]:
-        """Returns object serialized as a YAML string
-
-        Parameters
-        ----------
-        uri : str, optional
-            URI location to save the YAML string, by default None
-        dumper : callable, optional
-            Custom YAML Dumper, by default yaml.SafeDumper
-        kwargs : dict
-            overwrite: (bool, optional). Defaults to True.
-                Whether to overwrite existing file or not.
-            note: (str, optional)
-                The note that needs to be added in the beginning of the YAML.
-                It will be added as is without any formatting.
-            side_effect: Optional[SideEffect]
-                side effect to take on the dictionary. The side effect can be either
-                convert the dictionary keys to "lower" (SideEffect.CONVERT_KEYS_TO_LOWER.value)
-                or "upper"(SideEffect.CONVERT_KEYS_TO_UPPER.value) cases.
-
-            The other keyword arguments to be passed into fsspec.open().
-            For OCI object storage, this could be config="path/to/.oci/config".
-
-        Returns
-        -------
-        Union[str, None]
-            Serialized version of object.
-            `None` in case when `uri` provided.
-        """
-        note = kwargs.pop("note", "")
-
-        yaml_string = f"{note}\n" + yaml.dump(self.to_dict(**kwargs), Dumper=dumper)
-        if uri:
-            self._write_to_file(s=yaml_string, uri=uri, **kwargs)
-            return None
-
-        return yaml_string
-
-    @classmethod
-    def from_yaml(
-        cls,
-        yaml_string: str = None,
-        uri: str = None,
-        loader: callable = loader,
-        **kwargs,
-    ):
-        """Creates an object from YAML string provided or from URI location containing YAML string
-
-        Parameters
-        ----------
-        yaml_string (string, optional)
-            YAML string. Defaults to None.
-        uri (string, optional)
-            URI location of file containing YAML string. Defaults to None.
-        loader (callable, optional)
-            Custom YAML loader. Defaults to CLoader/SafeLoader.
-        kwargs (dict)
-            keyword arguments to be passed into fsspec.open().
-            For OCI object storage, this should be config="path/to/.oci/config".
-            For other storage connections consider e.g. host, port, username, password, etc.
-
-        Raises
-        ------
-        ValueError
-            Raised if neither string nor uri is provided
-
-        Returns
-        -------
-        cls
-            Returns instance of the class
-        """
-        if yaml_string:
-            return cls.from_dict(yaml.load(yaml_string, Loader=loader), **kwargs)
-        if uri:
-            yaml_dict = yaml.load(cls._read_from_file(uri=uri, **kwargs), Loader=loader)
-            return cls.from_dict(yaml_dict, **kwargs)
-        raise ValueError("Must provide either YAML string or URI location")
-
-    @classmethod
-    def from_string(
-        cls,
-        obj_string: str = None,
-        uri: str = None,
-        loader: callable = loader,
-        **kwargs,
-    ) -> "Serializable":
-        """Creates an object from string provided or from URI location containing string
-
-        Parameters
-        ----------
-        obj_string: (str, optional)
-            String representing the object
-        uri: (str, optional)
-            URI location of file containing string. Defaults to None.
-        loader: (callable, optional)
-            Custom YAML loader. Defaults to CLoader/SafeLoader.
-        kwargs: (dict)
-            keyword arguments to be passed into fsspec.open(). For OCI object storage, this should be config="path/to/.oci/config".
-            For other storage connections consider e.g. host, port, username, password, etc.
-
-        Returns
-        -------
-        Serializable
-            A Serializable instance
-        """
-        return cls.from_yaml(yaml_string=obj_string, uri=uri, loader=loader, **kwargs)
-
-    def __repr__(self):
-        """Returns printable version of object.
-
-        Returns
-        ----------
-        string
-            Serialized version of object as a YAML string
-        """
-        return self.to_yaml()
-
-    def __str__(self):
-        """Returns printable version of object.
-
-        Returns
-        ----------
-        string
-            Serialized version of object as a YAML string
-        """
-        return self.to_json()
-
-
-class DataClassSerializable(Serializable):
-    """Wrapper class that inherit from Serializable class.
-
-    Methods
-    -------
-    to_dict(self) -> dict
-        Serializes the object into a dictionary.
-    from_dict(cls, obj_dict) -> cls
-        Returns an instance of the class instantiated from the dictionary provided.
-    """
-
-    @classmethod
-    def _validate_dict(cls, obj_dict: Dict) -> bool:
-        """validate the dictionary.
-
-        Parameters
-        ----------
-        obj_dict: (dict)
-            Dictionary representation of the object
-
-        Returns
-        -------
-        bool
-            True if the validation passed, else False.
-        """
-        pass
-
-    def to_dict(self, **kwargs) -> Dict:
-        """Serializes instance of class into a dictionary
-
-        kwargs
-        ------
-        side_effect: Optional[SideEffect]
-            side effect to take on the dictionary. The side effect can be either
-            convert the dictionary keys to "lower" (SideEffect.CONVERT_KEYS_TO_LOWER.value)
-            or "upper"(SideEffect.CONVERT_KEYS_TO_UPPER.value) cases.
-
-        Returns
-        -------
-        Dict
-            A dictionary.
-        """
-        obj_dict = dataclasses.asdict(self)
-        if "side_effect" in kwargs and kwargs["side_effect"]:
-            obj_dict = DataClassSerializable._normalize_dict(
-                obj_dict=obj_dict, case=kwargs["side_effect"], recursively=True
-            )
-        return obj_dict
-
-    @classmethod
-    def from_dict(
-        cls,
-        obj_dict: dict,
-        side_effect: Optional[SideEffect] = SideEffect.CONVERT_KEYS_TO_LOWER.value,
-        ignore_unknown: Optional[bool] = False,
-        **kwargs,
-    ) -> "DataClassSerializable":
-        """Returns an instance of the class instantiated by the dictionary provided.
-
-        Parameters
-        ----------
-        obj_dict: (dict)
-            Dictionary representation of the object
-        side_effect: Optional[SideEffect]
-            side effect to take on the dictionary. The side effect can be either
-            convert the dictionary keys to "lower" (SideEffect.CONVERT_KEYS_TO_LOWER.value)
-            or "upper"(SideEffect.CONVERT_KEYS_TO_UPPER.value) cases.
-        ignore_unknown: (bool, optional). Defaults to `False`.
-            Whether to ignore unknown fields or not.
-
-        Returns
-        -------
-        DataClassSerializable
-            A DataClassSerializable instance.
-        """
-        assert obj_dict, "`obj_dict` must not be None."
-        if not isinstance(obj_dict, dict):
-            raise TypeError("`obj_dict` must be a dictionary.")
-        # check if dict not is None and not empty and type is dict
-        cls._validate_dict(obj_dict=obj_dict)
-        if side_effect:
-            obj_dict = cls._normalize_dict(obj_dict, case=side_effect)
-
-        allowed_fields = set([f.name for f in dataclasses.fields(cls)])
-        wrong_fields = set(obj_dict.keys()) - allowed_fields
-        if wrong_fields and not ignore_unknown:
-            logger.warning(
-                f"The class {cls.__name__} doesn't contain attributes: `{list(wrong_fields)}`. "
-                "These fields will be ignored."
-            )
-
-        obj = cls(**{key: obj_dict.get(key) for key in allowed_fields})
-
-        for key, value in obj_dict.items():
-            if (
-                key in allowed_fields
-                and isinstance(value, dict)
-                and hasattr(getattr(cls(), key).__class__, "from_dict")
-            ):
-                attribute = getattr(cls(), key).__class__.from_dict(
-                    value,
-                    ignore_unknown=ignore_unknown,
-                    side_effect=side_effect,
-                    **kwargs,
-                )
-                setattr(obj, key, attribute)
-
-        return obj
-
-    @staticmethod
-    def _normalize_dict(
-        obj_dict: Dict,
-        recursively: bool = False,
-        case: str = SideEffect.CONVERT_KEYS_TO_LOWER.value,
-        **kwargs,
-    ) -> Dict:
-        """lower all the keys.
-
-        Parameters
-        ----------
-        obj_dict: (Dict)
-            Dictionary representation of the object.
-        case: (optional, str). Defaults to "lower".
-            the case to normalized to. can be either "lower" (SideEffect.CONVERT_KEYS_TO_LOWER.value)
-            or "upper"(SideEffect.CONVERT_KEYS_TO_UPPER.value).
-        recursively: (bool, optional). Defaults to `False`.
-            Whether to recursively normalize the dictionary or not.
-
-        Returns
-        -------
-        Dict
-            Dictionary representation of the object.
-        """
-        normalized_obj_dict = {}
-        for key, value in obj_dict.items():
-            if recursively and isinstance(value, dict):
-                value = DataClassSerializable._normalize_dict(
-                    value, case=case, recursively=recursively, **kwargs
-                )
-            normalized_obj_dict = DataClassSerializable._normalize_key(
-                normalized_obj_dict=normalized_obj_dict,
-                key=key,
-                value=value,
-                case=case,
-                **kwargs,
-            )
-        return normalized_obj_dict
-
-    @staticmethod
-    def _normalize_key(
-        normalized_obj_dict: Dict, key: str, value: Union[str, Dict], case: str
-    ) -> Dict:
-        """helper function to normalize the key in the case specified and add it back to the dictionary.
-
-        Parameters
-        ----------
-        normalized_obj_dict: (Dict)
-            the dictionary to append the key and value to.
-        key: (str)
-            key to be normalized.
-        value: (Union[str, Dict])
-            value to be added.
-        case: (str)
-            The case to normalized to. can be either "lower" (SideEffect.CONVERT_KEYS_TO_LOWER.value)
-            or "upper"(SideEffect.CONVERT_KEYS_TO_UPPER.value).
-
-        Raises
-        ------
-        NotImplementedError
-            Raised when `case` is not supported.
-
-        Returns
-        -------
-        Dict
-            Normalized dictionary with the key and value added in the case specified.
-        """
-        if case.lower() == SideEffect.CONVERT_KEYS_TO_LOWER.value:
-            normalized_obj_dict[key.lower()] = value
-        elif case.lower() == SideEffect.CONVERT_KEYS_TO_UPPER.value:
-            normalized_obj_dict[key.upper()] = value
-        else:
-            raise NotImplementedError("`case` is not supported.")
-        return normalized_obj_dict