everysk-lib 1.10.2__cp312-cp312-win_amd64.whl

everysk/sdk/entities/report/base.py

@@ -0,0 +1,214 @@
+###############################################################################
+#
+# (C) Copyright 2023 EVERYSK TECHNOLOGIES
+#
+# This is an unpublished work containing confidential and proprietary
+# information of EVERYSK TECHNOLOGIES. Disclosure, use, or reproduction
+# without authorization of EVERYSK TECHNOLOGIES is prohibited.
+#
+###############################################################################
+from everysk.config import settings
+from everysk.core.exceptions import SDKValueError
+from everysk.core.fields import ListField, StrField, DictField
+from everysk.sdk.entities.base import BaseEntity, ScriptMetaClass
+from everysk.sdk.entities.fields import EntityNameField, EntityDescriptionField, EntityLinkUIDField, EntityWorkspaceField, EntityDateTimeField, EntityTagsField
+from everysk.sdk.entities.query import Query
+from everysk.sdk.entities.script import Script
+
+
+###############################################################################
+#   Report Class Implementation
+###############################################################################
+class Report(BaseEntity, metaclass=ScriptMetaClass):
+    """
+    This class represents a report entity object and provides methods to validate and manage the entity's data.
+
+    Attributes:
+        script (Script): The script object associated with the report.
+        id (StrField): The unique identifier of the report.
+        workspace (EntityWorkspaceField): The workspace of the report.
+        name (EntityNameField): The name of the report.
+        tags (EntityTagsField): The tags of the report.
+        description (EntityDescriptionField): The description of the report.
+        link_uid (EntityLinkUIDField): The link UID of the report.
+        date (EntityDateTimeField): The date associated with the report.
+        widgets (ListField): A list of widgets associated with the report.
+        url (StrField): The URL of the report.
+        authorization (StrField): The authorization string for accessing the report.
+        config_cascaded (DictField): A dictionary of cascaded configuration settings.
+        layout_content (DictField): A dictionary representing the layout content of the report.
+
+        version (StrField): The version of the report.
+        created_on (DateTimeField): The created on date of the report.
+        updated_on (DateTimeField): The updated on date of the report.
+
+    Example:
+        >>> from everysk.sdk.entities.report.base import Report
+        >>> report = Report()
+        >>> report.script = 'my_script'
+        >>> report.id = 'repo_12345678'
+        >>> report.name = 'My Report'
+        >>> report.tags = ['tag1', 'tag2']
+        >>> report.description = 'This is a sample report.'
+        >>> report.workspace = 'my_workspace'
+        >>> report.date = '20220101'
+        >>> report.widgets = [{'type': 'chart', 'data': {...}}, {'type': 'table', 'data': {...}}]
+        >>> report.url = '/sefdsf5s54sdfsksdfs5'
+        >>> report.authorization = 'private'
+        >>> report.data_hash = 'hash123'
+        >>> report.config_cascaded = {'setting1': 'value1', 'setting2': 'value2'}
+        >>> report.layout_content = {'section1': {...}, 'section2': {...}}
+        >>> report.create()
+        >>> print(report)
+        {
+            'id': 'repo_12345678',
+            'script': 'my_script',
+            'name': 'My Report',
+            'description': 'This is a sample report.',
+            'tags': ['tag1', 'tag2'],
+            'link_uid': None,
+            'workspace': 'my_workspace',
+            'date': '20220101',
+            'widgets': [{'type': 'chart', 'data': {...}}, {'type': 'table', 'data': {...}}],
+            'url': '/sefdsf5s54sdfsksdfs5',
+            'authorization': 'private',
+            'config_cascaded': {'setting1': 'value1', 'setting2': 'value2'},
+            'layout_content': {'section1': {...}, 'section2': {...}}
+        }
+    """
+
+    script: Script = None
+    _orderable_attributes = ListField(default=['date', 'created_on', 'updated_on', 'name'], readonly=True)
+
+    id = StrField(regex=settings.REPORT_ID_REGEX, max_size=settings.REPORT_ID_MAX_SIZE, required_lazy=True, empty_is_none=True)
+
+    name = EntityNameField()
+    description = EntityDescriptionField()
+    tags = EntityTagsField()
+    link_uid = EntityLinkUIDField()
+    workspace = EntityWorkspaceField()
+    date = EntityDateTimeField()
+
+    widgets = ListField()
+    url = StrField(required_lazy=True)
+    authorization = StrField(default=None, regex=settings.REPORT_AUTHORIZATION_REGEX, required_lazy=True)
+    config_cascaded = DictField(required_lazy=True)
+    layout_content = DictField(required_lazy=True)
+
+    def validate(self) -> bool:
+        """
+        This method validates the entity object and raises an exception if it is not
+        valid. The validation is performed by calling the `validate` method of each field
+        of the entity.
+
+        Args:
+            self (Self): The entity object to be validated.
+
+        Raises:
+            FieldValueError: If the entity object is not valid.
+
+        Returns:
+            bool: True if the entity object is valid, False otherwise.
+
+        Example:
+            >>> entity = Entity()
+            >>> entity.validate()
+            True
+        """
+        return self.get_response(self_obj=self)
+
+    @staticmethod
+    def get_id_prefix() -> str:
+        """
+        Returns the prefix of the report id field value.
+
+        Returns:
+            str: The prefix of the report id field value.
+
+        Example:
+            >>> from everysk.sdk.entities.report.base import Report
+            >>> Report.get_id_prefix()
+            'repo_'
+
+        Notes:
+            The prefix is typically used to distinguish report IDs from the other types of IDs
+        """
+        return settings.REPORT_ID_PREFIX
+
+    def _check_query(self, query: Query) -> bool:
+        """
+        Check the query object.
+
+        Args:
+            query (Query): The query object.
+
+        Returns:
+            Query: The query object.
+        """
+        return True
+
+    def _check_entity_to_query(self) -> bool:
+        """
+        Check the entity object to query.
+
+        Returns:
+            bool: True if the entity object is valid.
+        """
+        super()._check_entity_to_query()
+        if self.url and (self.name or self.tags or self.link_uid):
+            raise SDKValueError("Can't filter by URL and Name, Tags or Link UID at the same time")
+
+        return True
+
+    def _mount_query(self, query: Query) -> Query:
+        """
+        Mount the query object.
+
+        Args:
+            query (Query): The query object.
+
+        Returns:
+            Query: The query object.
+        """
+        query = super()._mount_query(query)
+        if self.url is not None:
+            query = query.where('url', self.url)
+
+        return query
+
+    def to_dict(self, add_class_path: bool = False, recursion: bool = False) -> dict:
+        """
+        Convert the entity to a JSON-serializable dictionary.
+        This method converts the entity object into a dictionary that can be easily
+        serialized to JSON.
+
+        Args:
+            self (Self): The entity instance to convert.
+            with_internals (bool, optional): Whether to include internal parameters. Defaults to True.
+            recursion (bool, optional): Whether to include nested entities. Defaults to False.
+
+        Returns:
+            dict: A dictionary representation of the entity.
+
+        Raises:
+            NotImplementedError: This method should be implemented in subclasses.
+        """
+        dct: dict = super().to_dict(add_class_path=add_class_path, recursion=recursion)
+
+        if add_class_path is False:
+            relative_url: None | str = None
+            absolute_url: None | str = None
+            if self.url is not None:
+                relative_url = f'{settings.REPORT_URL_PATH}{self.url}'
+                absolute_url = f'{settings.EVERYSK_APP_URL}{relative_url}'
+
+            dct['url'] = absolute_url
+            dct['absolute_url'] = absolute_url
+            dct['relative_url'] = relative_url
+
+            dct['authorization'] = dct['authorization'].upper() if dct['authorization'] else None
+
+            dct.pop('config_cascaded', None)
+            dct.pop('layout_content', None)
+
+        return dct

everysk/sdk/entities/report/settings.py

@@ -0,0 +1,23 @@
+###############################################################################
+#
+# (C) Copyright 2023 EVERYSK TECHNOLOGIES
+#
+# This is an unpublished work containing confidential and proprietary
+# information of EVERYSK TECHNOLOGIES. Disclosure, use, or reproduction
+# without authorization of EVERYSK TECHNOLOGIES is prohibited.
+#
+###############################################################################
+from everysk.core.fields import StrField, IntField, RegexField
+
+
+REPORT_ID_REGEX = RegexField(default=r'^repo_[a-zA-Z0-9]', readonly=True)
+REPORT_ID_PREFIX = StrField(default='repo_', readonly=True)
+
+REPORT_ID_MAX_SIZE = IntField(default=30, readonly=True)
+REPORT_LEVEL_MAX_LENGTH = IntField(default=32, readonly=True)
+
+REPORT_AUTHORIZATION_PUBLIC = StrField(default='public', readonly=True)
+REPORT_AUTHORIZATION_PRIVATE = StrField(default='private', readonly=True)
+REPORT_AUTHORIZATION_REGEX = RegexField(default=r'public|private', readonly=True)
+
+REPORT_URL_PATH = StrField(default='/report', readonly=True)

everysk/sdk/entities/script.py

@@ -0,0 +1,310 @@
+###############################################################################
+#
+# (C) Copyright 2023 EVERYSK TECHNOLOGIES
+#
+# This is an unpublished work containing confidential and proprietary
+# information of EVERYSK TECHNOLOGIES. Disclosure, use, or reproduction
+# without authorization of EVERYSK TECHNOLOGIES is prohibited.
+#
+###############################################################################
+from typing import Any, Callable, TypedDict
+from inspect import isclass
+
+from everysk.config import settings
+from everysk.core.exceptions import FieldValueError, InvalidArgumentError
+from everysk.core.object import BaseDict, BaseDictConfig
+from everysk.core.string import import_from_string
+from everysk.sdk.base import BaseSDK
+
+
+###############################################################################
+#   StorageSettings Class Implementation
+###############################################################################
+class StorageSettings(TypedDict):
+    storage_mode: str
+    consistency_check: bool
+    skip_validation: bool
+    create_fallback: bool
+
+
+###############################################################################
+#   Script Class Implementation
+###############################################################################
+class Script(BaseDict, BaseSDK):
+    """
+    A base class for scripted queries.
+    This class provides a base implementation for scripted queries.
+
+    Attributes:
+        - _klass (callable): The class to instantiate when fetching an entity.
+
+    Example:
+        To fetch an entity:
+        >>> script = Script(klass=MyEntity)
+        >>> entity = script.fetch(user_input, variant, workspace)
+    """
+    class Config(BaseDictConfig):
+        exclude_keys: frozenset[str] = frozenset(['_is_frozen', '_silent', '_errors', '_orderable_attributes'])
+
+    _klass: Callable = None
+    _config: Config = None
+
+    def __init__(self, _klass: Callable) -> None:
+        super().__init__(_klass=None)
+
+        if _klass is not None and not isclass(_klass):
+            try:
+                _klass = import_from_string(settings.EVERYSK_SDK_ENTITIES_MODULES_PATH[_klass])
+            except KeyError:
+                raise FieldValueError(f"The _klass value '{_klass}' must be a class or a string with the class name.") from KeyError
+
+        self._klass = _klass
+
+    def _process__klass(self, value: Any) -> Any:
+        """
+        This method is used to process the '_klass' attribute.
+        """
+        return value.__name__
+
+    def _process_entity_output(self, user_input: Any) -> Any:
+        """
+        Processes the user input and returns an instance of the class or the input itself.
+
+        If the `user_input` is a dictionary or an instance of `BaseDict`, it will be passed as keyword arguments
+        to the class constructor (`self._klass`) and an instance of that class will be returned. Otherwise,
+        the `user_input` is returned as-is.
+
+        Args:
+            user_input (Any): The input data to be processed. This can be a dictionary, an instance of `BaseDict`,
+                            or any other type.
+
+        Returns:
+            Any: An instance of the class if `user_input` is a dictionary or `BaseDict`; otherwise, the `user_input`
+                itself is returned.
+        """
+        return self._klass(**user_input) if isinstance(user_input, (dict, BaseDict)) else user_input # pylint: disable=not-callable
+
+    def inner_fetch(self, user_input: Any, variant: str, workspace: str = Undefined) -> Any:
+        """
+        Makes a call to the client to fetch an entity based on user input, variant, and workspace.
+
+        Args:
+            user_input (Any): The input provided by the user, which can be used for filtering or as a direct entity ID.
+            variant (str): The type of scripted query to execute. Determines how the method processes the user input and constructs the query. Supported variants include 'previousWorkers', 'tagLatest', any string starting with 'select', and potentially others.
+            workspace (str): The workspace context for the query. Used for scoping and verifying entity retrieval.
+
+        Returns:
+            Any: Depending on the variant and user input, the method might return an entity, or None.
+
+        """
+        response = self.get_response(self_obj=self, params={'user_input': user_input, 'variant': variant, 'workspace': workspace})
+
+        return self._process_entity_output(response)
+
+    def fetch(self, user_input: Any, variant: str, workspace: str = Undefined) -> Any:
+        """
+        Fetches an entity based on user input, variant, and workspace.
+
+        This method provides a way to construct and execute different types of queries
+        based on the specified variant. It's designed to handle a variety of scenarios
+        and return the desired entity or entities based on the input parameters.
+
+        Args:
+            - user_input (Any): The input provided by the user, which can be used for filtering
+            or as a direct entity ID.
+            - variant (str): The type of scripted query to execute. Determines how the method
+            processes the user input and constructs the query. Supported variants include
+            'previousWorkers', 'tagLatest', any string starting with 'select', and potentially
+            others.
+            - workspace (str): The workspace context for the query. Used for scoping and
+            verifying entity retrieval.
+
+        Returns:
+            - Any: Depending on the variant and user input, the method might return an entity,
+            or None.
+
+        Raises:
+            - ValueError: If there's an attempted cross-workspace operation or other variant-specific
+            error conditions are met.
+
+        Note:
+            The method behavior can vary greatly depending on the `variant` parameter, and it's
+            important to ensure that the variant aligns with the expected user input structure.
+
+        """
+        if not user_input:
+            return None
+
+        if variant == 'previousWorkers' and isinstance(user_input, (dict, BaseDict, self._klass)) and (user_input.get('is_transient') or user_input.get('id') is None):
+            return self._process_entity_output(user_input)
+
+        entity: Any = self.inner_fetch(user_input, variant, workspace)
+
+        return entity
+
+    def inner_fetch_list(self, user_input: Any, variant: str, workspace: str = Undefined) -> list:
+        """
+        Fetches a list of entities based on user input, variant, and workspace.
+
+        This method makes a call to the client to perform the necessary query actions.
+
+        Args:
+            user_input (Any): The input provided by the user, which can be used for filtering or as a direct entity ID.
+            variant (str): The type of scripted query to execute.
+            workspace (str): The workspace context for the query.
+
+        Returns:
+            list: The list of entities retrieved based on the input parameters.
+
+        """
+        return self.get_response(self_obj=self, params={'user_input': user_input, 'variant': variant, 'workspace': workspace})
+
+
+    def fetch_list(self, user_input: Any, variant: str, workspace: str = Undefined) -> list:
+        """
+        Fetches an entity based on user input, variant, and workspace.
+
+        This method provides a way to construct and execute different types of queries
+        based on the specified variant. It's designed to handle a variety of scenarios
+        and return the desired entity or entities based on the input parameters.
+
+        Args:
+            user_input (Any): The input provided by the user, which can be used for filtering or as a direct entity ID.
+            variant (str): The type of scripted query to execute. Determines how the method processes the user input and constructs the query. Supported variants include 'previousWorkers', 'tagLatest', any string starting with 'select', and potentially others.
+            workspace (str): The workspace context for the query. Used for scoping and verifying entity retrieval.
+
+        Returns:
+            list: The method will return a list of entities or an empty list.
+
+        Raises:
+            ValueError: If there's an attempted cross-workspace operation or other variant-specific error conditions are met.
+
+        Note:
+            The method behavior can vary greatly depending on the `variant` parameter, and it's important to ensure that the variant aligns with the expected user input structure.
+
+        """
+        if not user_input:
+            return []
+
+        entity_list: list = self.inner_fetch_list(user_input, variant, workspace)
+
+        return [self._klass(**item) if item is not None else item for item in entity_list] # pylint: disable=not-callable
+
+    def inner_fetch_multi(self, user_input_list: list[Any], variant_list: list[str], workspace_list: list[str] = Undefined) -> list:
+        """
+        Fetches a list of entities based on user inputs, query variants, and workspace contexts.
+
+        This method sends a request to the client to execute the necessary query actions,
+        dynamically constructed based on the provided parameters.
+
+        Args:
+            user_input_list (list[Any]): A list of inputs provided by the user.
+            variant_list (list[str]): A list of query variants, each specifying the type of query to execute.
+            workspace_list (list[str], optional): A list of workspace contexts, used for scoping and validating
+                entity retrieval. Defaults to `Undefined`.
+
+        Returns:
+            list: A list of entities retrieved based on the provided parameters. Returns an empty list
+            if no entities match the query.
+        """
+        return self.get_response(self_obj=self, params={'user_input_list': user_input_list, 'variant_list': variant_list, 'workspace_list': workspace_list})
+
+
+    def fetch_multi(self, user_input_list: list[Any], variant_list: list[str], workspace_list: list[str] = Undefined) -> list:
+        """
+        Fetches entities based on user inputs, query variants, and workspace contexts.
+
+        This method provides a higher-level interface for constructing and executing different
+        types of queries, delegating the core functionality to `inner_fetch_multi`.
+
+        Args:
+            user_input_list (list[Any]): A list of inputs provided by the user.
+            variant_list (list[str]): A list of query variants, each specifying the type of query to execute.
+            workspace_list (list[str], optional): A list of workspace contexts, used for scoping and validating
+                entity retrieval. Defaults to `Undefined`.
+
+        Returns:
+            list: A list of entities processed and instantiated using the class constructor (`self._klass`).
+            Returns an empty list if no entities match the query.
+        """
+        if not user_input_list:
+            return []
+
+        entity_list: list = self.inner_fetch_multi(user_input_list, variant_list, workspace_list)
+
+        return [self._klass(**item) for item in entity_list] # pylint: disable=not-callable
+
+    def persist(self, entity: Any, persist: str, consistency_check: bool = False) -> Any:
+        """
+        This method provides a way to persist an entity based on the specified persist type.
+
+        Args:
+            - entity (Any): The entity to persist.
+            - persist (str): The type of persist to execute. Determines how the method
+            persists the entity. Supported persists include 'insert', 'update', and 'delete'.
+            - consistency_check (bool): A flag to enable consistency checks before persisting.
+
+        Returns:
+            - Any: Depending on the persist type, the method might return an entity.
+
+        """
+        response = self.get_response(self_obj=self, params={'entity': entity, 'persist': persist, 'consistency_check': consistency_check})
+
+        if isinstance(response, dict):
+            response = self._klass(**response) # pylint: disable=not-callable
+
+        return response
+
+    def inner_storage(self, entity: Any, storage_settings: StorageSettings) -> Any:
+        """
+        Handles the storage actions for a given entity using specified storage settings.
+
+        This method makes a call to the client to perform the necessary storage actions.
+
+        Args:
+            entity (Any): The entity to be stored.
+            storage_settings (StorageSettings): The settings and configurations for storage.
+
+        Returns:
+            Any: The response from the client after performing the storage actions.
+
+        """
+        response = self.get_response(self_obj=self, params={'entity': entity, 'storage_settings': storage_settings})
+
+        return self._process_entity_output(response)
+
+
+    def storage(self, entity: Any, storage_settings: StorageSettings) -> Any:
+        """
+        Stores an entity based on the specified storage settings.
+
+        This method determines the appropriate storage actions for an entity, including handling
+        different storage modes, performing consistency checks, and optionally skipping validation.
+
+        Args:
+            entity (Any): The entity to be stored.
+            storage_settings (StorageSettings): A configuration object containing:
+                - storage_mode (str): The storage mode to use. Supported modes include 'transient', 'create', and 'update'.
+                - consistency_check (bool): A flag indicating whether to perform a consistency check.
+                - validate (bool): A flag indicating whether to validate the entity parameters or not.
+                - create_fallback (bool): A flag indicating whether to create an entity if it does not exist.
+
+        Returns:
+            Any: Depending on the storage mode, the method might return the stored entity or a list of entities.
+
+        Raises:
+            InvalidArgumentError: If the entity is empty.
+
+        """
+        if not entity:
+            raise InvalidArgumentError('Entity should not be empty.')
+
+        if storage_settings['storage_mode'] == 'transient':
+            entity.is_transient = True
+
+            if not storage_settings['validate']:
+                return self._process_entity_output(entity)
+
+        entity: Any = self.inner_storage(entity, storage_settings)
+
+        return entity

everysk/sdk/entities/secrets/base.py

@@ -0,0 +1,128 @@
+# -*- coding: utf_8 -*-
+###############################################################################
+#
+# (C) Copyright 2023 EVERYSK TECHNOLOGIES
+#
+# This is an unpublished work containing confidential and proprietary
+# information of EVERYSK TECHNOLOGIES. Disclosure, use, or reproduction
+# without authorization of EVERYSK TECHNOLOGIES is prohibited.
+#
+###############################################################################
+from typing import Any
+
+from everysk.config import settings
+from everysk.core.exceptions import FieldValueError
+from everysk.core.fields import DictField, ListField, StrField
+from everysk.core.object import BaseDict
+from everysk.sdk.entities.base import BaseEntity
+from everysk.sdk.entities.fields import EntityDescriptionField, EntityNameField
+from everysk.sdk.entities.secrets.script import SecretsScript, SecretsScriptMetaClass
+
+
+###############################################################################
+#   Secrets Class Implementation
+###############################################################################
+class Secrets(BaseEntity, metaclass=SecretsScriptMetaClass):
+    script: SecretsScript = None
+    _orderable_attributes = ListField(default=['created_on', 'updated_on', 'name'], readonly=True)
+
+    id = StrField(regex=settings.SECRETS_ID_REGEX, required_lazy=True, empty_is_none=True)
+
+    name = EntityNameField()
+    description = EntityDescriptionField()
+    data = DictField(required_lazy=True, empty_is_none=True)
+
+    def to_dict(self, add_class_path: bool = False, recursion: bool = False) -> dict:
+        """
+        Convert the entity to a dictionary.
+
+        Args:
+            add_class_path (bool): If True, include the class path in the dictionary. Defaults to False.
+            recursion (bool): If True, recursively convert nested entities to dictionaries. Defaults to False.
+
+        Returns:
+            dict: The entity as a dictionary.
+        """
+        dct = super().to_dict(add_class_path, recursion)
+
+        if add_class_path is False and self.data and isinstance(self.data, BaseDict):
+            dct['data'] = self.data.to_dict()
+
+        return dct
+
+    @staticmethod
+    def get_id_prefix() -> str:
+        """Get the ID prefix for the Secrets entity."""
+        return settings.SECRETS_ID_PREFIX
+
+    def _validate_data(self) -> None:
+        """Validates the data field."""
+        if not self.data:
+            raise FieldValueError('data is required')
+
+        if not isinstance(self.data, dict):
+            raise FieldValueError('data must be a dictionary of version to Secret')
+
+    def validate(self) -> bool:
+        """
+        Validate the entity properties.
+
+        Raises:
+            FieldValueError: If the entity properties are invalid.
+            RequiredFieldError: If a required field is missing.
+
+        Returns:
+            bool: True if the entity properties are valid, False otherwise.
+
+        Example usage:
+            >>> entity = Secrets()
+            >>> entity.validate()
+            Traceback (most recent call last):
+                ...
+            everysk.sdk.exceptions.RequiredFieldError: The field 'name' is required.
+        """
+        super().validate()
+        self._validate_data()
+        return True
+
+    @classmethod
+    def _split_path(cls, path: str) -> tuple[str, list[str]]:
+        """
+        Split a path into id and keys.
+
+        Args:
+            path (str): The path to split.
+
+        Returns:
+            tuple[str, list[str]]: The id and keys.
+
+        Raises:
+            ValueError: If the path is invalid.
+        """
+        if not path or not isinstance(path, str) or '.' not in path:
+            raise ValueError('Invalid path format. Expected format: "<secret_id>.<key1>.<key2>..."')
+
+        values: list[str] = path.split('.')
+        id, keys = values[0], values[1:]
+
+        if cls.validate_id(id) is False:
+            raise ValueError(f'Invalid id format: {id}')
+
+        return id, keys
+
+    @classmethod
+    def value_from_path(cls, path: str) -> Any:
+        """
+        Retrieve a value from a given path.
+
+        Args:
+            path (str): The path to retrieve the value from.
+
+        Returns:
+            Any | None: The value retrieved from the path or None if the path is empty.
+        """
+        if not path:
+            return None
+
+        _, _ = cls._split_path(path)
+        return cls.get_response(params={'path': path})