HedgeTech 0.3.2b1__tar.gz → 0.4.0b0__tar.gz

hedgetech-0.4.0b0/HedgeTech/Auth/__AuthAsyncClient.py

@@ -0,0 +1,224 @@
+# ========================================|======================================== #
+#                                      Imports                                      #
+# ========================================|======================================== #
+
+from .__utils import RetriableAsyncClient
+from httpx import (
+    AsyncClient ,
+    Timeout ,
+)
+from jwt import decode
+
+# ========================================|======================================== #
+#                                 Class Definitions                                 #
+# ========================================|======================================== #
+
+class AuthAsyncClient:
+    """
+    Asynchronous client for interacting with the HedgeTech API using JWT-based authentication.
+
+    This class provides a high-level interface to authenticate users, manage JWT tokens,
+    and make authorized HTTP requests using an `httpx.AsyncClient`.
+
+    Normally an instance is created with ``AuthAsyncClient.login(...)``. Calling the
+    constructor directly is only useful when you already have a configured HTTP client and
+    a valid token. The resulting object is what the data clients
+    (``DataEngine_Ime_AsyncClient``, ``DataEngine_TseIfb_AsyncClient``) receive: they use
+    ``httpx_Client`` for REST requests and ``token`` as the WebSocket headers.
+
+    Note:
+        * The client does not refresh the token. When the JWT expires, requests start to
+          fail and you need to call ``login`` again to get a new client.
+        * ``Permissions`` is decoded WITHOUT verifying the signature or the expiry, so it is
+          only meant for reading the claims (e.g. to display them), never for making
+          security decisions.
+
+    Attributes:
+        httpx_Client (AsyncClient): The HTTP client used for authorized requests. When created
+            by ``login`` it is a ``RetriableAsyncClient`` (a wrapper around ``httpx.AsyncClient``
+            that retries failed requests, up to 10 times) configured with:
+
+            - the authentication headers (the token returned by the server plus an ``origin``
+              header) and the cookies received at login;
+            - HTTP/2 only (``http1=False``, ``http2=True``) with TLS verification enabled;
+            - short timeouts: connect 0.25 s, read 1.5 s, write 1.5 s, pool 0.25 s.
+        token (dict[str, str]): Dictionary containing the authentication tokens. It must contain
+            the ``'Authorization'`` key holding the JWT string. It is also passed as the
+            ``additional_headers`` of WebSocket connections.
+        Permissions (dict): The decoded JWT payload (its claims), set by ``UpdatePermission``
+            when the object is created. The available claims depend on the server.
+
+    Example:
+        >>> client = await AuthAsyncClient.login(
+        ...     UserName_or_Email="user@example.com",
+        ...     Password="secure_password"
+        ... )
+        >>> client.token['Authorization'][:10]
+        'eyJ0eXAiOi'
+        >>> client.Permissions  # Decoded JWT payload
+        {'sub': 'user_id', 'exp': 1700350200, ...}
+        >>> data_client = DataEngine_TseIfb_AsyncClient(AuthAsyncClient=client)
+    """
+
+    def __init__(
+        self,
+        *,
+        httpx_Client:AsyncClient,
+        token:dict[str,str],
+    ):
+        """
+        Initialize the AuthAsyncClient with an existing httpx.AsyncClient and authentication token.
+
+        Both arguments are keyword-only. The token is decoded immediately (see
+        ``UpdatePermission``), so ``Permissions`` is available right after construction.
+
+        Args:
+            httpx_Client (AsyncClient): Preconfigured AsyncClient for making authorized requests.
+                It should already send the authentication headers (``login`` does this for you).
+            token (dict[str, str]): Dictionary containing authentication tokens. It must contain
+                the ``'Authorization'`` key with the JWT string.
+
+        Raises:
+            ValueError: If the token cannot be decoded (see ``UpdatePermission``).
+
+        Example:
+            >>> client = AuthAsyncClient(
+            ...     httpx_Client=my_httpx_client,
+            ...     token={"Authorization": "<jwt>"}
+            ... )
+            >>> client.Permissions
+            {'sub': 'user_id', 'exp': 1700350200, ...}
+        """
+
+        self.httpx_Client : AsyncClient = httpx_Client
+        self.token : dict[str,str] = token
+
+        self.UpdatePermission
+
+
+    @property
+    def UpdatePermission(self)-> None:
+
+        """
+        Decodes the JWT 'Authorization' token to extract user permissions.
+
+        This is a **property**, not a method: reading ``client.UpdatePermission`` (without
+        parentheses) performs the work and returns ``None``. It is read once in ``__init__``;
+        read it again to re-decode ``token`` after you replace it.
+
+        The decoded payload is stored in ``self.Permissions``. The token is decoded
+        WITHOUT verifying the signature, and the expiry (``exp``) is not checked either.
+
+        Raises:
+            ValueError: If the JWT cannot be decoded. Any underlying error is wrapped in
+                ``ValueError``, including a missing ``'Authorization'`` key in ``token``.
+
+        Example:
+            >>> client.token = new_token
+            >>> client.UpdatePermission  # no parentheses; re-decodes the token
+            >>> client.Permissions
+            {'sub': 'user_id', 'exp': 1700350200, ...}
+        """
+
+        try :
+
+            self.Permissions = decode(
+                jwt=self.token['Authorization'].encode(),
+                algorithms='HS256',
+                options={"verify_signature": False},
+            )
+
+        except Exception as e:
+
+            raise ValueError(e)
+
+
+    @classmethod
+    async def login(
+        cls,
+        *,
+        UserName_or_Email : str,
+        Password : str
+    )-> "AuthAsyncClient":
+
+        """
+        Authenticate a user and return an instance of `AuthAsyncClient`.
+
+        This method performs the login request to the HedgeTech API, retrieves JWT tokens,
+        and configures an `httpx.AsyncClient` with authentication headers and cookies.
+
+        It sends ``POST https://core.hedgetech.ir/auth/user/token/issue`` with the credentials as
+        form data. The login succeeds only when the server answers with HTTP status ``201``.
+        The JSON body of that answer is used as ``token`` and is also sent as headers on every
+        later request, together with an ``origin: https://core.hedgetech.ir`` header. The cookies
+        set at login are kept.
+
+        Args:
+            UserName_or_Email (str): The username or email of the user.
+            Password (str): The user's password.
+
+        Returns:
+            AuthAsyncClient: An initialized client ready to make authorized requests. Its
+                ``httpx_Client`` is a ``RetriableAsyncClient`` (10 retries) using HTTP/2 with the
+                short timeouts described in the class docstring.
+
+        Raises:
+            ValueError: If the login attempt fails (e.g., wrong credentials), i.e. the status is
+                not ``201``. The message is the server's ``detail`` field, which is ``None`` if
+                the server did not send one. The same exception is raised if the token returned
+                by the server cannot be decoded (see ``UpdatePermission``).
+
+        Note:
+            Network errors while sending the login request (for example a connection failure or
+            timeout) are raised by ``httpx`` as they are and are not converted to ``ValueError``.
+
+        Example:
+            >>> client = await AuthAsyncClient.login(
+            ...     UserName_or_Email="user@example.com",
+            ...     Password="secure_password"
+            ... )
+            >>> client.token['Authorization'][:10]
+            'eyJ0eXAiOi'
+        """
+
+        httpx_Client = AsyncClient(verify=True ,http1=False ,http2=True)
+
+        login_res = await httpx_Client.post(
+            url='https://core.hedgetech.ir/auth/user/token/issue',
+            data={
+                'UserName_or_Email' : UserName_or_Email,
+                'Password' : Password
+            }
+        )
+
+        if login_res.status_code == 201:
+
+            token = login_res.json()
+            headers = {'origin'  : 'https://core.hedgetech.ir'}
+            headers.update(token)
+
+            httpx_Client = RetriableAsyncClient(
+                client = AsyncClient(
+                    verify=True ,
+                    http1=False ,
+                    http2=True ,
+                    headers=headers,
+                    cookies=httpx_Client.cookies,
+                    timeout=Timeout(
+                        connect=.250,
+                        read=1.5,
+                        write=1.5,
+                        pool=.250,
+                    ),
+                ),
+                retries= 10
+            )
+
+            return cls(
+                httpx_Client = httpx_Client,
+                token = token
+            )
+
+        else :
+
+            raise ValueError(login_res.json().get('detail'))

hedgetech-0.4.0b0/HedgeTech/Auth/__AuthSyncClient.py

@@ -0,0 +1,230 @@
+# ========================================|======================================== #
+#                                      Imports                                      #
+# ========================================|======================================== #
+
+from .__utils import RetriableSyncClient
+from httpx import (
+    Client ,
+    Timeout ,
+)
+from jwt import decode
+
+# ========================================|======================================== #
+#                                 Class Definitions                                 #
+# ========================================|======================================== #
+
+
+class AuthSyncClient:
+    """
+    Synchronous client for interacting with the HedgeTech API using JWT-based authentication.
+
+    This class provides a high-level interface to authenticate users, manage JWT tokens,
+    and make authorized HTTP requests using an `httpx.Client`.
+
+    This is the blocking twin of ``AuthAsyncClient``: same login endpoint, token handling and
+    configuration, only the calling style differs (plain calls instead of ``await``).
+
+    Normally an instance is created with ``AuthSyncClient.login(...)``. Calling the
+    constructor directly is only useful when you already have a configured HTTP client and
+    a valid token. The resulting object is what the data clients
+    (``DataEngine_Ime_SyncClient``, ``DataEngine_TseIfb_SyncClient``) receive: they use
+    ``httpx_Client`` for REST requests and ``token`` as the WebSocket headers.
+
+    Note:
+        * The client does not refresh the token. When the JWT expires, requests start to
+          fail and you need to call ``login`` again to get a new client.
+        * ``Permissions`` is decoded WITHOUT verifying the signature or the expiry, so it is
+          only meant for reading the claims (e.g. to display them), never for making
+          security decisions.
+
+    Attributes:
+        httpx_Client (Client): The HTTP client used for authorized requests. When created
+            by ``login`` it is a ``RetriableSyncClient`` (a wrapper around ``httpx.Client``
+            that retries failed requests, up to 10 times) configured with:
+
+            - the authentication headers (the token returned by the server plus an ``origin``
+              header) and the cookies received at login;
+            - HTTP/2 only (``http1=False``, ``http2=True``) with TLS verification enabled;
+            - short timeouts: connect 0.25 s, read 1.5 s, write 1.5 s, pool 0.25 s.
+        token (dict[str, str]): Dictionary containing the authentication tokens. It must contain
+            the ``'Authorization'`` key holding the JWT string. It is also passed as the
+            ``additional_headers`` of WebSocket connections.
+        Permissions (dict): The decoded JWT payload (its claims), set by ``UpdatePermission``
+            when the object is created. The available claims depend on the server.
+
+    Example:
+        >>> client = AuthSyncClient.login(
+        ...     UserName_or_Email="user@example.com",
+        ...     Password="secure_password"
+        ... )
+        >>> client.token['Authorization'][:10]
+        'eyJ0eXAiOi'
+        >>> client.Permissions  # Decoded JWT payload
+        {'sub': 'user_id', 'exp': 1700350200, ...}
+        >>> data_client = DataEngine_TseIfb_SyncClient(AuthSyncClient=client)
+    """
+
+    def __init__(
+        self,
+        *,
+        httpx_Client:Client,
+        token:dict[str,str],
+    ):
+        """
+        Initialize the AuthSyncClient with an existing httpx.Client and authentication token.
+
+        Both arguments are keyword-only. The token is decoded immediately (see
+        ``UpdatePermission``), so ``Permissions`` is available right after construction.
+
+        Args:
+            httpx_Client (Client): Preconfigured Client for making authorized requests.
+                It should already send the authentication headers (``login`` does this for you).
+            token (dict[str, str]): Dictionary containing authentication tokens. It must contain
+                the ``'Authorization'`` key with the JWT string.
+
+        Raises:
+            ValueError: If the token cannot be decoded (see ``UpdatePermission``).
+
+        Example:
+            >>> client = AuthSyncClient(
+            ...     httpx_Client=my_httpx_client,
+            ...     token={"Authorization": "<jwt>"}
+            ... )
+            >>> client.Permissions
+            {'sub': 'user_id', 'exp': 1700350200, ...}
+        """
+
+        self.httpx_Client : Client = httpx_Client
+        self.token : dict[str,str] = token
+
+        self.UpdatePermission
+
+
+    @property
+    def UpdatePermission(self)-> None:
+
+        """
+        Decodes the JWT 'Authorization' token to extract user permissions.
+
+        This is a **property**, not a method: reading ``client.UpdatePermission`` (without
+        parentheses) performs the work and returns ``None``. It is read once in ``__init__``;
+        read it again to re-decode ``token`` after you replace it.
+
+        The decoded payload is stored in ``self.Permissions``. The token is decoded
+        WITHOUT verifying the signature, and the expiry (``exp``) is not checked either.
+
+        Raises:
+            ValueError: If the JWT cannot be decoded. Any underlying error is wrapped in
+                ``ValueError``, including a missing ``'Authorization'`` key in ``token``.
+
+        Example:
+            >>> client.token = new_token
+            >>> client.UpdatePermission  # no parentheses; re-decodes the token
+            >>> client.Permissions
+            {'sub': 'user_id', 'exp': 1700350200, ...}
+        """
+
+        try :
+
+            self.Permissions = decode(
+                jwt=self.token['Authorization'].encode(),
+                algorithms='HS256',
+                options={"verify_signature": False},
+            )
+
+        except Exception as e:
+
+            raise ValueError(e)
+
+
+    @classmethod
+    def login(
+        cls,
+        *,
+        UserName_or_Email : str,
+        Password : str
+    )-> "AuthSyncClient":
+
+        """
+        Authenticate a user synchronously and return an instance of `AuthSyncClient`.
+
+        This method performs the login request to the HedgeTech API, retrieves JWT tokens,
+        and configures an `httpx.Client` with authentication headers and cookies.
+
+        It sends ``POST https://core.hedgetech.ir/auth/user/token/issue`` with the credentials as
+        form data. The login succeeds only when the server answers with HTTP status ``201``.
+        The JSON body of that answer is used as ``token`` and is also sent as headers on every
+        later request, together with an ``origin: https://core.hedgetech.ir`` header. The cookies
+        set at login are kept.
+
+        Args:
+            UserName_or_Email (str): The username or email of the user.
+            Password (str): The user's password.
+
+        Returns:
+            AuthSyncClient: An initialized client ready to make authorized requests. Its
+                ``httpx_Client`` is a ``RetriableSyncClient`` (10 retries) using HTTP/2 with the
+                short timeouts described in the class docstring.
+
+        Raises:
+            ValueError: If the login attempt fails (e.g., wrong credentials), i.e. the status is
+                not ``201``. The message is the server's ``detail`` field, which is ``None`` if
+                the server did not send one. The same exception is raised if the token returned
+                by the server cannot be decoded (see ``UpdatePermission``).
+
+        Note:
+            Network errors while sending the login request (for example a connection failure or
+            timeout) are raised by ``httpx`` as they are and are not converted to ``ValueError``.
+
+        Example:
+            >>> client = AuthSyncClient.login(
+            ...     UserName_or_Email="user@example.com",
+            ...     Password="secure_password"
+            ... )
+            >>> client.token['Authorization'][:10]
+            'eyJ0eXAiOi'
+        """
+
+        httpx_Client = Client(verify=True ,http1=False ,http2=True)
+
+
+        login_res = httpx_Client.post(
+            url='https://core.hedgetech.ir/auth/user/token/issue',
+            data={
+                'UserName_or_Email' : UserName_or_Email,
+                'Password' : Password
+            }
+        )
+
+
+        if login_res.status_code == 201:
+
+            token = login_res.json()
+            headers = {'origin'  : 'https://core.hedgetech.ir'}
+            headers.update(token)
+
+            httpx_Client = RetriableSyncClient(
+                client = Client(
+                    verify=True ,
+                    http1=False ,
+                    http2=True ,
+                    headers=headers,
+                    cookies=httpx_Client.cookies,
+                    timeout=Timeout(
+                        connect=.250,
+                        read=1.5,
+                        write=1.5,
+                        pool=.250,
+                    ),
+                ),
+                retries= 10
+            )
+
+            return cls(
+                httpx_Client = httpx_Client,
+                token = token
+            )
+
+        else :
+
+            raise ValueError(login_res.json().get('detail'))