ds_stoa.manager
===============

.. py:module:: ds_stoa.manager

.. autoapi-nested-parse::

   Manager module for the Stoa class.

   This module serves as the manager for the Stoa class, facilitating the management
   of messages within our system. The Stoa class provides methods for fetching, signing,
   authenticating, and ordering messages, which are crucial for secure and efficient
   communication and data exchange.

   **Usage Examples**:

   1. Creating an instance of the Stoa class with REST authentication::

       from ds_stoa.manager.client import StoaClient

       stoa = StoaClient(
           authentication="rest",
           product_group_name="exampleGroup",
           product_name="exampleProduct",
           workspace="apps",
           owner_id="owner123",
           email="user@example.com",
           password="securepassword"
       )

       stoa.authenticate()
       assert stoa.is_authenticated()


   2. Creating an instance of the Stoa class with OAuth2 authentication::

       from ds_stoa.manager.client import StoaClient

       stoa = StoaClient(
           authentication="oauth2",
           product_group_name="exampleGroup",
           product_name="exampleProduct",
           workspace="cart",
           owner_id="owner456",
           client_id="client_id_example",
           client_secret="client_secret_example"
       )

       stoa.authenticate()
       assert stoa.is_authenticated()


   3. Order, Sign & Fetch::

       stoa = StoaClient(**params)
       order_ids = stoa.order()
       signatures = stoa.sign()
       dataframe = stoa.fetch()


   **Note**: Replace the placeholder values (e.g., "user@example.com", "securepassword", "client_id_example", etc.)
   with your actual data when implementing these examples.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/ds_stoa/manager/client/index


Classes
-------

.. autoapisummary::

   ds_stoa.manager.StoaClient


Package Contents
----------------

.. py:class:: StoaClient(authentication: Literal['rest', 'oauth2'], product_group_name: str, product_name: str, workspace: Literal['apps', 'cart'], owner_id: str, version: str = '1.0', offset: int = 0, limit: int = 20, ascending: bool = False, email: Optional[str] = None, password: Optional[str] = None, client_id: Optional[str] = None, client_secret: Optional[str] = None)

   The Stoa class provides methods for handling messages within our system.
   These methods include operations for fetching, signing, authenticating,
   and ordering messages.


   .. py:property:: token
      :type: str

      Token getter that retrieves the current access token.

      :return: The access token.
      :raises ValueError: If the access token is missing.


   .. py:property:: order_ids
      :type: List[str]

      Order IDs getter that retrieves the current list of order IDs.

      :return: List of order IDs.
      :raises ValueError: If no order IDs are found.


   .. py:property:: signatures
      :type: Dict

      Signatures getter that retrieves the current dictionary of signatures.

      :return: Dictionary of signatures.
      :raises ValueError: If no signatures are found.


   .. py:method:: authenticate() -> None

      Authenticates a message to verify its origin. This method is used to
      check if a message came from a trusted source before it is processed
      by the system.

      :return: The access token for the authenticated request.
      :rtype: str
      :raises NotImplementedError: If the authentication method is invalid.

      **example**::
          >>> stoa = StoaClient(**params)
          >>> stoa.authenticate()
          >>> assert stoa.token



   .. py:method:: is_authenticated() -> bool

      Checks if a message is authenticated. This method is used to verify
      that a message has been authenticated before it is processed by the
      system.

      :return: True if the message is authenticated, False otherwise.
      :rtype: bool

      **example**::
          >>> stoa = StoaClient(**params)
          >>> stoa.authenticate()
          >>> assert stoa.is_authenticated()



   .. py:method:: order() -> List[str]

      Orders a message based on predefined rules. This method is used to
      sort or arrange messages according to certain criteria before they
      are processed by the system.

      :return: Ordered keys.
      :rtype: List
      :raises ValueError: If the workspace is invalid.

      **example**::
          >>> stoa = StoaClient(**params)
          >>> stoa.order()
          >>> assert stoa.order_ids



   .. py:method:: sign() -> Dict

      Signs a message to ensure its integrity and authenticity. This method
      is used to add a layer of security to our messages, making sure they
      are not tampered with during transit.

      :return: The pre-signed URLs for the messages.
      :rtype: Dict
      :raises ValueError: If the order IDs are missing.

      **example**::
          >>> stoa = StoaClient(**params)
          >>> stoa.order()
          >>> stoa.sign()
          >>> assert stoa.signatures



   .. py:method:: fetch(format: Literal['json', 'dataframe']) -> Union[List[Dict], pandas.DataFrame]

      Fetches a message from a predefined source. This method is responsible
      for retrieving messages that are to be processed by the system.

      :param format: The format in which to return the fetched data.
      :return: The fetched data in the specified format.
      :rtype: List[Dict]
      :raises ValueError: If the format is invalid.

      **example**::
          >>> stoa = StoaClient(**params)
          >>> stoa.fetch(format="json")