everysk-lib 1.10.2__cp312-cp312-win_amd64.whl

everysk/sdk/entities/portfolio/base.py

@@ -0,0 +1,248 @@
+# -*- 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, TYPE_CHECKING
+import csv
+import six
+
+from everysk.config import settings
+from everysk.core.fields import ListField, StrField, FloatField, BoolField
+from everysk.core.string import to_string
+from everysk.sdk.entities.base import BaseEntity, ScriptMetaClass
+from everysk.sdk.entities.fields import EntityNameField, EntityDescriptionField, EntityLinkUIDField, EntityWorkspaceField, EntityDateTimeField, EntityTagsField, CurrencyField
+from everysk.sdk.entities.portfolio.securities import Securities
+from everysk.sdk.entities.script import Script
+
+if TYPE_CHECKING:
+    from io import StringIO
+
+
+###############################################################################
+#   SecuritiesField Class Implementation
+###############################################################################
+class SecuritiesField(ListField):
+    attr_type = Securities
+
+    def __init__(self, default: Any = None, required_lazy: bool = True, **kwargs) -> None:
+        """
+        This method initializes the field.
+
+        Args:
+            default (Any): The default value of the field.
+            required_lazy (bool): True if the field is required, False otherwise.
+            **kwargs (dict): The keyword arguments of the field.
+        """
+        super().__init__(default=default, required_lazy=required_lazy, **kwargs)
+
+    def clean_value(self, value: Any) -> Securities:
+        """
+        This method cleans the value of the field.
+
+        Args:s
+            value (Any): The value to be cleaned.
+
+        Returns:
+            Securities: The cleaned value.
+        """
+        if isinstance(value, list):
+            value = self.attr_type(value)
+        return super().clean_value(value)
+
+
+###############################################################################
+#   Portfolio Class Implementation
+###############################################################################
+class Portfolio(BaseEntity, metaclass=ScriptMetaClass):
+    """
+    This class represents a portfolio entity object and provides methods to validate
+    and convert the entity object to a dictionary or a CSV string representation.
+
+    Attributes:
+        script (Script): The script object associated to the entity.
+        id (StrField): The unique identifier of the portfolio.
+        workspace (EntityWorkspaceField): The workspace of the portfolio.
+        name (EntityNameField): The name of the portfolio.
+        tags (EntityTagsField): The tags of the portfolio.
+        link_uid (EntityLinkUIDField): The link uid of the portfolio.
+        description (EntityDescriptionField): The description of the portfolio.
+        nlv (FloatField): The nlv of the portfolio.
+        base_currency (CurrencyField): The base currency of the portfolio.
+        date (EntityDateTimeField): The date of the portfolio.
+        securities (SecuritiesField): The securities of the portfolio.
+        level (StrField): The level of the portfolio.
+
+        version (StrField): The version of the portfolio.
+        created_on (DateTimeField): The created on date of the portfolio.
+        updated_on (DateTimeField): The updated on date of the portfolio.
+
+    Example:
+        >>> from everysk.sdk.entities.portfolio.base import Portfolio
+        >>> portfolio = Portfolio()
+        >>> portfolio.workspace = 'my_workspace'
+        >>> portfolio.name = 'My Portfolio'
+        >>> portfolio.tags = ['tag1', 'tag2']
+        >>> portfolio.nlv = 1000.0
+        >>> portfolio.base_currency = 'USD'
+        >>> portfolio.date = '20210101'
+        >>> portfolio.securities = ['sec1', 'sec2', 'sec3']
+        >>> portfolio.save()
+        >>> print(portfolio)
+        {
+            'id': 'port_12345678',
+            'workspace': 'my_workspace',
+            'name': 'My Portfolio',
+            'tags': ['tag1', 'tag2'],
+            'nlv': 1000.0,
+            'base_currency': 'USD',
+            'date': '20210101',
+            'securities': ['sec1', 'sec2', 'sec3'],
+            'version': 'v1',
+            'created_on': '2021-01-01T00:00:00.000000Z',
+            'updated_on': '2021-01-01T00:00:00.000000Z',
+            'level': 'portfolio'
+        }
+
+    """
+    script: Script
+    _orderable_attributes = ListField(default=['date', 'created_on', 'updated_on', 'name'], readonly=True)
+
+    id = StrField(regex=settings.PORTFOLIO_ID_REGEX, max_size=settings.PORTFOLIO_ID_MAX_SIZE, required_lazy=True, empty_is_none=True)
+
+    name = EntityNameField()
+    description = EntityDescriptionField()
+    tags = EntityTagsField()
+    link_uid = EntityLinkUIDField()
+    workspace = EntityWorkspaceField()
+
+    nlv = FloatField(min_size=float('-inf'), max_size=float('inf'))
+    base_currency = CurrencyField()
+    date = EntityDateTimeField()
+    securities = SecuritiesField(min_size=0, max_size=settings.PORTFOLIO_MAX_SIZE, required_lazy=True)
+    level = StrField(min_size=1, max_size=settings.PORTFOLIO_LEVEL_MAX_LENGTH)
+
+    check_securities = BoolField(default=False)
+
+    ###############################################################################
+    #   Portfolio Basics Implementation
+    ###############################################################################
+
+    @staticmethod
+    def get_id_prefix() -> str:
+        """
+        Returns the prefix of the portfolio id field value.
+
+        Returns:
+            str: The prefix of the portfolio id field value.
+
+        Example:
+            >>> Portfolio.get_id_prefix()
+            'port_'
+
+        Notes:
+            The prefix is typically used to distinguish portfolio IDs from other types of IDs.
+        """
+        return settings.PORTFOLIO_ID_PREFIX
+
+    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.
+            RequiredFieldError: If a required field is missing.
+
+        Returns:
+            bool: True if the entity object is valid, False otherwise.
+
+        Example:
+            >>> entity = Entity()
+            >>> entity.validate()
+            True
+        """
+        return self.get_response(self_obj=self)
+
+    def to_csv(self) -> str:
+        """
+        This method converts the entity object into a CSV string representation of the
+        entity object.
+
+        Returns:
+            str: A CSV string representation of the entity.
+
+        Example:
+            >>> entity = Entity()
+            >>> entity.to_csv()
+            "name,date,base_currency,nlv,description,tags,securities
+            My Portfolio,2021-01-01,USD,1000.0,My Portfolio Description,tag1 tag2,sec1,sec2,sec3"
+        """
+        def write_row(csv_writer_: Any, line: list[str], length: int) -> None:
+            """
+            Write a row to a CSV file
+
+            Args:
+                csv_writer_ (Any): CSV writer object to use for writing the row
+                line (list[str]): The list of values to write as a row
+                length (int): The desired length of the row
+
+            Returns:
+                None
+
+            Example:
+                >>> from everysk.sdk.entities.portfolio.base import Portfolio
+                >>> import csv
+                >>> csv_file = open('output'.csv', 'w', newline='')
+                >>> write = csv.writer(csv_file)
+                >>> Portfolio.write_row(writer, ['value1', 'value2'], 5)
+                >>> csv_file.close()
+
+            Notes:
+                This function pads the row with empty strings to ensure the fixed length.
+            """
+            out: list[str] = line + ([''] * (length - len(line)))
+            out = [to_string(s) if s is not None else None for s in out]
+            csv_writer_.writerow(out)
+            return None
+
+        csv_file: StringIO = six.StringIO()
+        csv_writer: Any = csv.writer(csv_file)
+
+        date_: str = self.date.strftime()
+        nlv_: str = '' if not self.nlv else to_string(self.nlv)
+        pre_headers: list[str] = [self.name, date_, self.base_currency, nlv_, self.description, ' '.join(self.tags)]
+
+        securities_as_lists: list[list[str]] = self.securities.to_lists()
+
+        headers: list[str] = securities_as_lists[0]
+        headers_len: int = len(headers)
+        write_row(csv_writer, pre_headers, headers_len)
+        write_row(csv_writer, headers, headers_len)
+
+        for sec_as_list in securities_as_lists[1:]:
+            write_row(csv_writer, sec_as_list, headers_len)
+
+        out: str = csv_file.getvalue()
+        csv_file.close()
+        return out
+
+    def to_dict(self, add_class_path: bool = False, recursion: bool = False) -> dict:
+        """
+        This method is used to convert the object to a dictionary.
+        """
+        dct: dict = super().to_dict(add_class_path=add_class_path, recursion=recursion)
+
+        if isinstance(dct['securities'], Securities):
+            dct['securities'] = dct['securities'].to_list(add_class_path=add_class_path, recursion=recursion)
+
+        return dct

everysk/sdk/entities/portfolio/securities.py

@@ -0,0 +1,241 @@
+# -*- 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, Self
+
+from everysk.core.exceptions import FieldValueError, HttpError, SDKError
+from everysk.core.http import HttpSDKPOSTConnection
+from everysk.core.object import BaseDict
+from everysk.sdk.entities.base_list import EntityList
+from everysk.sdk.entities.portfolio.security import Security
+
+
+###############################################################################
+#   Securities Class Implementation
+###############################################################################
+class Securities(EntityList):
+    _attr_type: Security = Security
+
+    def _validate(self, value: dict) -> Security:
+        """
+        Validates a dictionary value and converts it into a `Security` object.
+
+        Args:
+            value (dict): A dictionary representing the security data.
+
+        Returns:
+            Security: A `Security` object created from the provided dictionary.
+
+        Raises:
+            FieldValueError: If the provided value is not a valid dictionary.
+            TypeError: If the provided value is not of dictionary type.
+
+        Example:
+            >>> from my_module import Security
+            >>> security_data = {'symbol': 'AAPL', 'name': 'Apple Inc.', 'price': 150.0}
+            >>> validated_security = self._validate(security_data)
+            >>> isinstance(validated_security, Security)
+            True
+        """
+        if not isinstance(value, (dict, BaseDict)):
+            raise FieldValueError(f'Security: The value must be a dict or BaseDict. {type(value)}') from TypeError
+        return self._attr_type(**value)
+
+    def validate(self) -> bool:
+        """
+        Validates the required fields of each security in the collection.
+
+        This method iterates through the collection of securities and calls the
+        `validate_required_fields` method for each security to ensure that all
+        required fields are present and have valid values.
+
+        Returns:
+            bool: True if validation succeeds for all securities, otherwise False.
+
+        Raises:
+            FieldValueError: If the collection of securities is empty.
+
+        Example:
+            >>> from everysk.sdk.entities.portfolio.securities import Securities
+            >>> security_data = [{'symbol': 'AAPL', 'name': 'Apple Inc.', 'price': 150.0},
+            ...                  {'symbol': 'GOOGL', 'name': 'Alphabet Inc.', 'price': 2800.0}]
+            >>> security_collection = Securities(security_data)
+            >>> security_collection.validate()
+            True
+        """
+        if len(self) == 0:
+            raise FieldValueError('The quantity of securities cannot be zero.')
+
+        for security in self:
+            security.validate_required_fields()
+        return True
+
+    @staticmethod
+    def from_lists(security_list: list[list[Any]]) -> Self:
+        """
+        Create a Securities collection from a list of lists representing securities.
+
+        This static method takes a list of lists where each inner list represents a security.
+        The first inner list (header) is used to extract attribute names, and the subsequent
+        lists are used to create individual `Security` objects within a `Securities` collection.
+
+        Args:
+            security_list (list[list[Any]]): A list of lists where each inner list represents a security.
+
+        Returns:
+            Self: A `Securities` collection containing `Security` objects created from the provided data.
+
+        Example:
+            >>> from everysk.sdk.entities.portfolio.securities import Securities
+            >>> security_data = [
+            ...     ['symbol', 'name', 'price'],
+            ...     ['AAPL', 'Apple Inc.', 150.0],
+            ...     ['GOOGL', 'Alphabet Inc.', 2800.0]
+            ... ]
+            >>> securities_collection = Securities.from_lists(security_data)
+            >>> len(securities_collection)
+            2
+        """
+        header: list[str] = security_list.pop(0)
+        return Securities([Securities._attr_type.from_list(sec_as_list, header) for sec_as_list in security_list])
+
+    @staticmethod
+    def diff(securities_a: list[dict], securities_b: list[dict], accessor: str = 'comparable') -> dict:
+        """
+        Diff two securities list. The securities list are compared by the
+        accessor provided. The accessor is used to compare the securities
+        list. The accessor must be a key in the securities list.
+
+        Args:
+            securities_a (Securities): Securities list to compare.
+            securities_b (Securities): Securities list to compare.
+            accessor (str): Accessor to compare.
+
+        Returns:
+            dict: Diff result.
+                Keys:
+                    added_positions (Securities): Added positions.
+                    removed_positions (Securities): Removed positions.
+                    partial_positions (Securities): Partial positions.
+                    equal_positions (Securities): Equal positions.
+        """
+        try:
+            response: dict = HttpSDKPOSTConnection(
+                cls_name='Securities',
+                params={'securities_a': securities_a, 'securities_b': securities_b, 'accessor': accessor},
+            ).get_response_decode()
+        except HttpError as error:
+            raise SDKError(error.msg) from error
+
+        return response
+
+    def consolidate(self, consolidation_keys) -> Self:
+        """
+        Consolidate securities list. If no consolidation keys are provided,
+        the securities list is returned as is. Otherwise, the securities list
+        is consolidated by the provided keys.
+
+        Args:
+            consolidation_keys (List[str]): List of keys to consolidate
+            by (e.g. ['symbol', 'instrument_class']). If no keys are provided,
+            the securities list is returned as is.
+
+        Returns:
+            Securities: Consolidated securities list.
+        """
+        try:
+            response: dict = HttpSDKPOSTConnection(
+                cls_name='Securities', params={'consolidation_keys': consolidation_keys}
+            ).get_response_decode()
+        except HttpError as error:
+            raise SDKError(error.msg) from error
+
+        return type(self)(**response)
+
+    def remove_errors(self) -> Self:
+        """
+        Create a new Securities collection with securities having a status other than 'ERROR'.
+
+        This method filters the current Securities collection, creating a new collection that
+        includes only securities with a status attribute other than 'ERROR'.
+
+        Returns:
+            Self: A new Securities collection containing securities without the 'ERROR' status.
+
+        Example:
+            >>> from everysk.sdk.entities.portfolio.securities import Securities
+            >>> security_data = [{'symbol': 'AAPL', 'status': 'OK'},
+            ...                  {'symbol': 'GOOGL', 'status': 'ERROR'},
+            ...                  {'symbol': 'MSFT', 'status': 'OK'}]
+            >>> securities_collection = Securities(security_data)
+            >>> filtered_securities = securities_collection.remove_errors()
+            >>> len(filtered_securities)
+            2
+        """
+        return Securities([security for security in self if security.status != 'ERROR'])
+
+    def to_lists(self, header: list[str] = None) -> list[list[Any]]:
+        """
+        Convert the Securities collection to a list of lists.
+
+        This method converts each `Security` object in the collection to a list representation.
+
+        Args:
+            header (list[str], optional): A list of strings representing the header row. If not provided,
+                the method will create a header based on the keys of the first security in the collection.
+
+        Returns:
+            list[list[Any]]: A list of lists representing the securities in the collection, including the header.
+
+        Example:
+            >>> from everysk.sdk.entities.portfolio.securities import Securities
+            >>> security_data = [{'symbol': 'AAPL', 'name': 'Apple Inc.', 'price': 150.0},
+            ...                  {'symbol': 'GOOGL', 'name': 'Alphabet Inc.', 'price': 2800.0}]
+            >>> securities_collection = Securities(securities=security_data)
+            >>> securities_list = securities_collection.to_lists()
+            >>> len(securities_list)
+            3  # Including the header row
+        """
+        if header is None:
+            first_security: Security = self[0]
+            extra_data: dict = first_security.get('extra_data') or {}
+            header = list(first_security.keys()) + list(extra_data.keys())
+            header = self._attr_type.sort_header(header)
+
+        security_list: list[list[Any]] = [security.to_list(header=header) for security in self]
+        security_list.insert(0, header)
+
+        return security_list
+
+    def to_list(self, add_class_path: bool = False, recursion: bool = False) -> list[dict]:
+        """
+        This method converts each `Security` object in the collection to a dictionary representation.
+
+        Args:
+            with_internals (bool, optional): Indicates whether to include internal attributes in the dictionaries.
+                Defaults to True.
+
+        Returns:
+            list[dict]: A list of dictionaries representing the securities in the collection.
+
+        Example:
+            >>> from everysk.sdk.entities.portfolio.securities import Securities
+            >>> security_data = [{'symbol': 'AAPL', 'name': 'Apple Inc.', 'price': 150.0},
+            ...                  {'symbol': 'GOOGL', 'name': 'Alphabet Inc.', 'price': 2800.0}]
+            >>> securities_collection = Securities(security_data)
+            >>> securities_dict = securities_collection.to_list()
+            >>> len(securities_dict)
+            2
+        """
+        return [
+            security.to_dict(add_class_path=add_class_path, recursion=recursion)
+            for security in self
+            if hasattr(security, 'to_dict')
+        ]