alpha-python 0.4.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

alpha/__init__.py

@@ -1,3 +1,4 @@
+from alpha.adapters.rest_api_unit_of_work import RestApiUnitOfWork
 from alpha.adapters.sqla_unit_of_work import SqlAlchemyUnitOfWork
 from alpha.factories.jwt_factory import JWTFactory
 from alpha.factories.logging_handler_factory import LoggingHandlerFactory
@@ -20,6 +21,7 @@ from alpha.interfaces.pydantic_instance import PydanticInstance
 from alpha.interfaces.openapi_model import OpenAPIModel
 from alpha.interfaces.updateable import Updateable
 from alpha.interfaces.patchable import Patchable
+from alpha.interfaces.api_repository import ApiRepository
 from alpha.interfaces.sql_repository import SqlRepository
 from alpha.interfaces.sql_mapper import SqlMapper
 from alpha.interfaces.sql_database import SqlDatabase
@@ -44,8 +46,10 @@ from alpha.providers.models.credentials import PasswordCredentials
 from alpha.providers.models.token import Token
 from alpha.providers.oidc_provider import OIDCProvider, KeyCloakProvider
 from alpha.repositories.models.repository_model import RepositoryModel
+from alpha.repositories.rest_api_repository import RestApiRepository
 from alpha.repositories.sql_alchemy_repository import SqlAlchemyRepository
 from alpha.services.authentication_service import AuthenticationService
+from alpha.services.user_lifecycle_management import UserLifecycleManagement
 from alpha.utils.is_attrs import is_attrs
 from alpha.utils.is_pydantic import is_pydantic
 from alpha.utils.logging_configurator import (
@@ -53,6 +57,7 @@ from alpha.utils.logging_configurator import (
     GunicornLogger,
 )
 from alpha.utils.logging_level_checker import logging_level_checker
+from alpha.utils.request_headers import Headers
 from alpha.utils.response_object import create_response_object
 from alpha.utils.verify_identity import verify_identity
 from alpha.utils.version_checker import minor_version_gte
@@ -60,13 +65,20 @@ from alpha.encoder import JSONEncoder
 
 # Optional LDAP support - only import if ldap3 is available
 try:
-    from alpha.infra.connectors.ldap_connector import LDAPConnector  # noqa: F401
-    from alpha.providers.ldap_provider import LDAPProvider, ADProvider  # noqa: F401
+    from alpha.infra.connectors.ldap_connector import (
+        LDAPConnector,  # noqa: F401
+    )
+    from alpha.providers.ldap_provider import (
+        LDAPProvider,  # noqa: F401
+        ADProvider,  # noqa: F401
+    )
+
     _LDAP_AVAILABLE = True
 except ImportError:
-    _LDAP_AVAILABLE = False # type: ignore
+    _LDAP_AVAILABLE = False  # type: ignore
 
 __all__ = [
+    "RestApiUnitOfWork",
     "SqlAlchemyUnitOfWork",
     "JWTFactory",
     "LoggingHandlerFactory",
@@ -91,6 +103,7 @@ __all__ = [
     "OpenAPIModel",
     "Updateable",
     "Patchable",
+    "ApiRepository",
     "SqlRepository",
     "SqlMapper",
     "SqlDatabase",
@@ -112,13 +125,16 @@ __all__ = [
     "OIDCProvider",
     "KeyCloakProvider",
     "RepositoryModel",
+    "RestApiRepository",
     "SqlAlchemyRepository",
     "AuthenticationService",
+    "UserLifecycleManagement",
     "is_attrs",
     "is_pydantic",
     "LoggingConfigurator",
     "GunicornLogger",
     "logging_level_checker",
+    "Headers",
     "create_response_object",
     "verify_identity",
     "minor_version_gte",
@@ -128,8 +144,10 @@ __all__ = [
 
 # Conditionally add LDAP-related exports if available
 if _LDAP_AVAILABLE:
-    __all__.extend([
-        "LDAPConnector",
-        "LDAPProvider",
-        "ADProvider",
-    ])
+    __all__.extend(
+        [
+            "LDAPConnector",
+            "LDAPProvider",
+            "ADProvider",
+        ]
+    )

alpha/adapters/__init__.py

@@ -1,5 +1,7 @@
+from alpha.adapters.rest_api_unit_of_work import RestApiUnitOfWork
 from alpha.adapters.sqla_unit_of_work import SqlAlchemyUnitOfWork
 
 __all__ = [
+    "RestApiUnitOfWork",
     "SqlAlchemyUnitOfWork",
 ]

alpha/adapters/rest_api_unit_of_work.py

@@ -0,0 +1,105 @@
+"""Contains the REST API Unit of Work implementation."""
+
+from typing import Any, TypeVar
+
+import requests
+
+from alpha.repositories.models.repository_model import RepositoryModel
+
+
+UOW = TypeVar("UOW", bound="RestApiUnitOfWork")
+
+
+class RestApiUnitOfWork:
+    """Unit of Work implementation for REST API interactions."""
+
+    def __init__(
+        self,
+        repos: list[RepositoryModel[Any]],
+        session: requests.sessions.Session | None = None,
+    ) -> None:
+        """Initialize the Unit of Work with repositories.
+
+        Parameters
+        ----------
+        repos : list[RepositoryModel]
+            The list of repository models to use.
+        session : requests.sessions.Session | None
+            The requests session (or compatible HTTP client, e.g., httpx) to
+            use for context management, by default None
+
+        Raises
+        ------
+        TypeError
+            If any repository does not implement its specified interface.
+        """
+        self._repositories = repos
+        self._session = session
+
+    def __enter__(self: UOW) -> UOW:
+        """Enter the REST API Unit of Work context.
+        Initializes a :class:`requests.sessions.Session` if one was not
+        provided and attaches the configured repositories as attributes on the
+        unit of work instance. Each repository is constructed using the shared
+        session and its associated configuration, and optionally validated
+        against a declared interface.
+
+        Returns
+        -------
+        UOW
+            The configured :class:`RestApiUnitOfWork` instance to be used
+            within the context manager.
+        """
+        self._session = self._session or requests.sessions.Session()
+
+        for repo in self._repositories:
+            name: str = repo.name
+            interface: Any = repo.interface
+            additional_config: dict[str, Any] = dict(
+                repo.additional_config or {}
+            )
+
+            self.__setattr__(
+                name,
+                repo.repository(
+                    session=self._session,
+                    default_model=repo.default_model,
+                    **additional_config,
+                ),
+            )
+
+            if interface:
+                if not isinstance(getattr(self, name), interface):
+                    raise TypeError(f"Repository for {name} has no interface")
+
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Finalize the Unit of Work context."""
+        if self._session:
+            self._session.close()
+
+    def commit(self) -> None:
+        raise NotImplementedError("RestApiUnitOfWork does not support commit")
+
+    def flush(self) -> None:
+        raise NotImplementedError("RestApiUnitOfWork does not support flush")
+
+    def rollback(self) -> None:
+        raise NotImplementedError(
+            "RestApiUnitOfWork does not support rollback"
+        )
+
+    def refresh(self, obj: object) -> None:
+        raise NotImplementedError("RestApiUnitOfWork does not support refresh")
+
+    @property
+    def session(self) -> requests.sessions.Session | None:
+        """Get the current session.
+
+        Returns
+        -------
+        requests.sessions.Session | None
+            The current session used for API interactions.
+        """
+        return self._session

alpha/adapters/sqla_unit_of_work.py

@@ -14,7 +14,11 @@ UOW = TypeVar("UOW", bound="SqlAlchemyUnitOfWork")
 class SqlAlchemyUnitOfWork:
     """Unit of Work implementation for SQLAlchemy databases."""
 
-    def __init__(self, db: SqlDatabase, repos: list[RepositoryModel]) -> None:
+    def __init__(
+        self,
+        db: SqlDatabase,
+        repos: list[RepositoryModel[Any]],
+    ) -> None:
         """Initialize the Unit of Work with a database and repositories.
 
         Parameters
@@ -28,9 +32,6 @@ class SqlAlchemyUnitOfWork:
         ------
         TypeError
             If the provided database is not a valid SqlDatabase instance.
-        TypeError
-            If the provided repositories list is empty or contains invalid
-            models.
         """
         if not isinstance(db, SqlDatabase):  # type: ignore
             raise TypeError("No valid database provided")
@@ -55,17 +56,16 @@ class SqlAlchemyUnitOfWork:
         self._session = self._db.get_session()
 
         for repo in self._repositories:
-            session = self._session
-            model = repo.default_model
-
             name: str = repo.name
-            repository = repo.repository
             interface: Any = repo.interface
 
             self.__setattr__(
                 name,
-                repository(session=session, default_model=model),  # type: ignore
+                repo.repository(
+                    session=self._session, default_model=repo.default_model
+                ),
             )
+
             if interface:
                 if not isinstance(getattr(self, name), interface):
                     raise TypeError(f"Repository for {name} has no interface")

alpha/domain/models/group.py

@@ -0,0 +1,35 @@
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Sequence, cast
+from uuid import UUID
+
+from alpha.domain.models.base_model import BaseDomainModel, DomainModel
+from alpha.domain.models.life_cycle_base import LifeCycleBase
+
+
+@dataclass(kw_only=True)
+class Group(LifeCycleBase, BaseDomainModel):
+    id: UUID | int | str | None = None
+    name: str | None = None
+    description: str | None = None
+    permissions: Sequence[str] | None = None
+    is_active: bool = True
+
+    def update(self, obj: DomainModel) -> DomainModel:
+        """Update the Group instance with data from another Group instance.
+
+        Parameters
+        ----------
+        obj
+            Group object to update from.
+        """
+        if not isinstance(obj, Group):
+            raise TypeError("Group.update expects a Group instance.")
+
+        self.name = obj.name
+        self.description = obj.description
+        self.permissions = obj.permissions
+        self.modified_at = datetime.now(tz=timezone.utc)
+        self.is_active = obj.is_active
+
+        return cast(DomainModel, self)

alpha/domain/models/user.py

@@ -1,25 +1,89 @@
 from dataclasses import dataclass
 from datetime import datetime, timezone
+from enum import Enum, auto
 from typing import Self, Sequence, cast
 from uuid import UUID
 
 from alpha.domain.models.base_model import BaseDomainModel, DomainModel
+from alpha.domain.models.group import Group
 from alpha.domain.models.life_cycle_base import LifeCycleBase
 
 from alpha.providers.models.identity import Identity
 
 
+class Role(Enum):
+    """Defines user roles with varying levels of permissions. The roles are
+    ordered from highest to lowest permissions. The comparison methods allow
+    for easy comparison of roles based on their hierarchy. The roles are
+    ordered on a scale from highest to lowest permissions.
+
+    Typical permissions are as follows:
+    - CREATE: Permission to create new content or data, but not modify existing
+    content.
+    - READ: Permission to read content or data.
+    - UPDATE: Permission to modify existing content or data, but not create new
+    content.
+    - DELETE: Permission to delete content or data.
+    - MANAGE_USERS: Permission to manage user accounts and permissions.
+    - MANAGE_SETTINGS: Permission to manage system settings and configurations.
+    - ALL: Permission to perform all actions, including user management and
+    system settings.
+
+    Roles:
+    - ADMIN: Role with permissions to manage users, content, and system
+    settings. Typically has the ALL permissions.
+    - SUPERUSER: Role with all permissions, including system settings and user
+    management. Typically has the ALL permissions, but may be used to denote a
+    special type of admin user with additional privileges or responsibilities.
+    - OWNER: Role with permissions to manage their own resources and users, but
+    not system settings. Typically has permissions similar to ADMIN, but
+    limited to their own scope of resources.
+    - MODERATOR: Role with permissions to manage content and users, but not
+    system settings. Typically has permissions to UPDATE and DELETE content,
+    and MANAGE_USERS, but not MANAGE_SETTINGS.
+    - EDITOR: Role with permissions to create and edit content, but not manage
+    users or settings. Typically has permissions to CREATE, READ, UPDATE, and
+    DELETE content, but not MANAGE_USERS or MANAGE_SETTINGS.
+    - USER: Default role with standard permissions. Typically has permissions
+    to CREATE, READ, and UPDATE their own content, but not DELETE content or
+    manage users or settings.
+    - VIEWER: Typical read-only role with limited permissions. Typically has
+    permission to READ content, but not CREATE, UPDATE, DELETE, or manage users
+    or settings.
+    """
+
+    ADMIN = auto()
+    SUPERUSER = auto()
+    OWNER = auto()
+    MODERATOR = auto()
+    EDITOR = auto()
+    USER = auto()
+    VIEWER = auto()
+
+    def __lt__(self, obj: Self) -> bool:
+        return self.value < obj.value
+
+    def __le__(self, obj: Self) -> bool:
+        return self.value <= obj.value
+
+    def __gt__(self, obj: Self) -> bool:
+        return self.value > obj.value
+
+    def __ge__(self, obj: Self) -> bool:
+        return self.value >= obj.value
+
+
 @dataclass(kw_only=True)
 class User(LifeCycleBase, BaseDomainModel):
     id: UUID | int | str | None = None
     username: str | None = None
     password: str | None = None
-    role: str | None = None
+    role: str | Role | None = None
     email: str | None = None
     phone: str | None = None
     display_name: str | None = None
     permissions: Sequence[str] | None = None
-    groups: Sequence[str] | None = None
+    groups: Sequence[str | Group] | None = None
     is_active: bool = True
     admin: bool = False
 

alpha/exceptions.py

@@ -19,6 +19,10 @@ class NotFoundException(ClientErrorException):
     """Equivalent to HTTP code 404"""
 
 
+class MethodNotAllowedException(ClientErrorException):
+    """Equivalent to HTTP code 405"""
+
+
 class NotAcceptableException(ClientErrorException):
     """Equivalent to HTTP code 406"""
 
@@ -55,11 +59,19 @@ class ServiceUnavailableException(ServerErrorException):
     """Equivalent to HTTP code 503"""
 
 
+class GatewayTimeoutException(ServerErrorException):
+    """Equivalent to HTTP code 504"""
+
+
 # General Exceptions
 class MissingConfigurationException(Exception):
     """Raised when a required configuration is missing."""
 
 
+class InvalidAttributeError(Exception):
+    """Raised when a required attribute is invalid."""
+
+
 class MissingDependencyException(Exception):
     """Raised when a required dependency is missing."""
 

alpha/factories/jwt_factory.py

@@ -18,7 +18,33 @@ class JWTFactory:
         lifetime_hours: str | None = "12",
         issuer: str = "http://localhost",
         jwt_algorithm: str = "HS256",
+        options: dict[str, Any] | None = None,
     ) -> None:
+        """Initialize the JWTFactory. This method sets up the necessary
+        configuration for creating and validating JWT tokens. It requires a
+        secret key for signing the tokens and allows optional configuration
+        for token lifetime, issuer, algorithm, and decoding options.
+
+        Parameters
+        ----------
+        secret
+            The secret key used to sign the JWT.
+        lifetime_hours, optional
+            The lifetime of the JWT in hours, by default "12"
+        issuer, optional
+            The issuer of the JWT, by default "http://localhost"
+        jwt_algorithm, optional
+            The algorithm used to sign the JWT, by default "HS256"
+        options, optional
+            A dictionary of options to customize the decoding behavior, by
+            default None. If not provided, it defaults to requiring standard
+            claims and verifying the signature.
+
+        Raises
+        ------
+        ValueError
+            If the secret value is empty.
+        """
         if not secret:
             raise ValueError("Secret value cannot be empty")
         if lifetime_hours is None:
@@ -28,6 +54,10 @@ class JWTFactory:
         self.JWT_ISSUER = issuer
         self.JWT_ALGORITHM = jwt_algorithm
         self.JWT_LIFETIME_SECONDS = 3600 * int(lifetime_hours)
+        self.JWT_OPTIONS = options or {
+            "require": ["exp", "iat", "nbf", "iss", "sub"],
+            "verify_signature": True,
+        }
 
     def create(
         self,
@@ -75,13 +105,19 @@ class JWTFactory:
         )
         return token
 
-    def validate(self, token: str) -> bool:
-        """Validate a JWT token.
+    def validate(
+        self, token: str, options: dict[str, Any] | None = None
+    ) -> bool:
+        """Validate a JWT token. This method checks the token's signature,
+        expiration, and issuer. If the token is invalid, it raises an
+        appropriate exception. If the token is valid, it returns True.
 
         Parameters
         ----------
         token
             The JWT token to be validated.
+        options
+            A dictionary of options to customize the decoding behavior.
 
         Returns
         -------
@@ -94,15 +130,62 @@ class JWTFactory:
             InvalidSignatureException
                 If the token signature is invalid.
         """
+        if self._decode(token, options):
+            return True
+        return False
+
+    def get_payload(
+        self, token: str, options: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Retrieve the payload from a JWT token. This method does not perform
+        validation of the token by default. It simply decodes the token and
+        extracts the payload.
+
+        If the `options` parameter is provided, it will be passed to the
+        `jwt.decode` function. This allows customization of the decoding
+        behavior, such as enabling or disabling signature verification.
+
+        Parameters
+        ----------
+        token
+            The JWT token from which to extract the payload.
+        options
+            A dictionary of options to customize the decoding behavior.
+
+        Returns
+        -------
+            A dictionary containing the payload data extracted from the token.
+        """
+        decoded = self._decode(token, options)
+        return decoded.get("payload", {})
+
+    def _decode(
+        self, token: str, options: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Decode a JWT token without performing validation. This method is
+        intended for internal use and should not be exposed as part of the
+        public API.
+
+        Parameters
+        ----------
+        token
+            The JWT token to be decoded.
+        options
+            A dictionary of options to customize the decoding behavior.
+
+        Returns
+        -------
+            A dictionary containing the decoded token data.
+        """
         try:
-            jwt.decode(
+            decoded: dict[str, Any] = jwt.decode(
                 jwt=token,
                 key=self.JWT_SECRET,
                 algorithms=[self.JWT_ALGORITHM],
                 issuer=self.JWT_ISSUER,
-                verify=True,
+                options=options or self.JWT_OPTIONS,
             )
-            return True
+            return decoded
         except jwt.ExpiredSignatureError as e:
             raise exceptions.TokenExpiredException(str(e)) from e
         except jwt.InvalidSignatureError as e:
@@ -111,23 +194,3 @@ class JWTFactory:
             raise exceptions.InvalidTokenException(
                 f"Token is invalid: {str(e)}"
             ) from e
-
-    def get_payload(self, token: str) -> dict[str, Any]:
-        """Retrieve the payload from a JWT token.
-
-        Parameters
-        ----------
-        token
-            The JWT token from which to extract the payload.
-
-        Returns
-        -------
-            A dictionary containing the payload data extracted from the token.
-        """
-        decoded: dict[str, Any] = jwt.decode(
-            jwt=token,
-            key=self.JWT_SECRET,
-            algorithms=[self.JWT_ALGORITHM],
-            issuer=self.JWT_ISSUER,
-        )
-        return decoded.get("payload", {})

alpha/factories/password_factory.py

@@ -11,6 +11,7 @@ from alpha import exceptions
 class PasswordFactory:
     """This class provides methods for hashing and verifying passwords using
     the argon2 library. It includes the following methods:
+
     - hash_password: Hashes a given password and returns the hashed value as a
         hexadecimal string.
     - verify_password: Verifies a given password against a provided hash and