alpha-python 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

alpha/__init__.py

@@ -1,16 +1,25 @@
+from importlib.metadata import version
+
 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
 from alpha.factories.model_class_factory import ModelClassFactory
 from alpha.domain.models.user import User
-from alpha.domain.models.base_model import BaseDomainModel, DomainModel
+from alpha.domain.models.group import Group
+from alpha.domain.models.role import Role
+from alpha.domain.models.base_model import (
+    BaseDomainModel,
+    DomainModel,
+    DomainModelCovariant,
+    DomainModelContravariant,
+)
 from alpha.domain.models.life_cycle_base import LifeCycleBase
 from alpha.infra.connectors.oidc_connector import (
     OIDCConnector,
     KeyCloakOIDCConnector,
 )
-from alpha.infra.databases.sql_alchemy import SqlAlchemyDatabase
+from alpha.infra.connectors.sql_alchemy import SqlAlchemyDatabase
 from alpha.infra.models.filter_operators import And, Or
 from alpha.infra.models.json_patch import JsonPatch
 from alpha.infra.models.order_by import OrderBy, Order
@@ -19,7 +28,7 @@ from alpha.interfaces.attrs_instance import AttrsInstance
 from alpha.interfaces.dataclass_instance import DataclassInstance
 from alpha.interfaces.pydantic_instance import PydanticInstance
 from alpha.interfaces.openapi_model import OpenAPIModel
-from alpha.interfaces.updateable import Updateable
+from alpha.interfaces.updatable import Updatable
 from alpha.interfaces.patchable import Patchable
 from alpha.interfaces.api_repository import ApiRepository
 from alpha.interfaces.sql_repository import SqlRepository
@@ -36,6 +45,8 @@ from alpha.interfaces.providers import (
 )
 from alpha.interfaces.token_factory import TokenFactory
 from alpha.mixins.jwt_provider import JWTProviderMixin
+from alpha.mixins.user_lifecycle import UserLifecycleMixin
+from alpha.mixins.group_lifecycle import GroupLifecycleMixin
 from alpha.providers.models.identity import (
     Identity,
     DEFAULT_LDAP_MAPPINGS,
@@ -44,11 +55,17 @@ from alpha.providers.models.identity import (
 )
 from alpha.providers.models.credentials import PasswordCredentials
 from alpha.providers.models.token import Token
-from alpha.providers.oidc_provider import OIDCProvider, KeyCloakProvider
+from alpha.providers.oidc_provider import (
+    OIDCProvider,
+    KeyCloakProvider,
+    DEFAULT_OIDC_MAPPINGS,
+    DEFAULT_KEYCLOAK_MAPPINGS,
+)
 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 (
@@ -56,11 +73,13 @@ 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
 from alpha.encoder import JSONEncoder
 
+
 # Optional LDAP support - only import if ldap3 is available
 try:
     from alpha.infra.connectors.ldap_connector import (
@@ -75,6 +94,9 @@ try:
 except ImportError:
     _LDAP_AVAILABLE = False  # type: ignore
 
+
+__version__ = version("alpha-python")
+
 __all__ = [
     "RestApiUnitOfWork",
     "SqlAlchemyUnitOfWork",
@@ -83,8 +105,12 @@ __all__ = [
     "ModelClassFactory",
     "BaseDomainModel",
     "DomainModel",
+    "DomainModelCovariant",
+    "DomainModelContravariant",
     "LifeCycleBase",
     "User",
+    "Group",
+    "Role",
     "OIDCConnector",
     "KeyCloakOIDCConnector",
     "SqlAlchemyDatabase",
@@ -99,7 +125,7 @@ __all__ = [
     "DataclassInstance",
     "PydanticInstance",
     "OpenAPIModel",
-    "Updateable",
+    "Updatable",
     "Patchable",
     "ApiRepository",
     "SqlRepository",
@@ -114,6 +140,8 @@ __all__ = [
     "TokenIssuer",
     "TokenFactory",
     "JWTProviderMixin",
+    "UserLifecycleMixin",
+    "GroupLifecycleMixin",
     "Identity",
     "DEFAULT_LDAP_MAPPINGS",
     "DEFAULT_AD_MAPPINGS",
@@ -122,15 +150,19 @@ __all__ = [
     "Token",
     "OIDCProvider",
     "KeyCloakProvider",
+    "DEFAULT_OIDC_MAPPINGS",
+    "DEFAULT_KEYCLOAK_MAPPINGS",
     "RepositoryModel",
     "RestApiRepository",
     "SqlAlchemyRepository",
     "AuthenticationService",
+    "UserLifecycleManagement",
     "is_attrs",
     "is_pydantic",
     "LoggingConfigurator",
     "GunicornLogger",
     "logging_level_checker",
+    "Headers",
     "create_response_object",
     "verify_identity",
     "minor_version_gte",
@@ -147,3 +179,27 @@ if _LDAP_AVAILABLE:
             "ADProvider",
         ]
     )
+
+
+def _ensure_ast_str_compat() -> None:
+    """Provide ast.Str compatibility for Python 3.14+.
+
+    Older Werkzeug versions (used by Flask 1.x) still instantiate ast.Str.
+    Python 3.14 removed that alias, so we recreate it with ast.Constant.
+    """
+    if hasattr(ast, "Str"):
+        return
+
+    class _StrCompat(ast.Constant):
+        def __new__(cls, s: str = "", **kwargs):  # noqa: N804
+            return ast.Constant(value=s, **kwargs)
+
+    setattr(ast, "Str", _StrCompat)
+
+
+try:
+    import ast
+
+    _ensure_ast_str_compat()
+except ImportError:
+    pass

alpha/adapters/rest_api_unit_of_work.py

@@ -11,7 +11,13 @@ UOW = TypeVar("UOW", bound="RestApiUnitOfWork")
 
 
 class RestApiUnitOfWork:
-    """Unit of Work implementation for REST API interactions."""
+    """Unit of Work implementation for REST API interactions.
+
+    This class manages the lifecycle of a shared HTTP session and provides
+    access to configured repositories for API interactions. It does not support
+    transactional operations like commit, flush, rollback, or refresh, as these
+    concepts do not apply to REST API interactions.
+    """
 
     def __init__(
         self,
@@ -22,9 +28,9 @@ class RestApiUnitOfWork:
 
         Parameters
         ----------
-        repos : list[RepositoryModel]
+        repos
             The list of repository models to use.
-        session : requests.sessions.Session | None
+        session
             The requests session (or compatible HTTP client, e.g., httpx) to
             use for context management, by default None
 

alpha/adapters/sqla_unit_of_work.py

@@ -12,7 +12,12 @@ UOW = TypeVar("UOW", bound="SqlAlchemyUnitOfWork")
 
 
 class SqlAlchemyUnitOfWork:
-    """Unit of Work implementation for SQLAlchemy databases."""
+    """Unit of Work implementation for SQLAlchemy databases.
+
+    This class manages the lifecycle of a SQLAlchemy session and provides
+    access to configured repositories for database interactions. It supports
+    transactional operations such as commit, flush, rollback, and refresh.
+    """
 
     def __init__(
         self,
@@ -23,9 +28,9 @@ class SqlAlchemyUnitOfWork:
 
         Parameters
         ----------
-        db : SqlDatabase
+        db
             The database instance to use.
-        repos : list[RepositoryModel]
+        repos
             The list of repository models to use.
 
         Raises
@@ -45,6 +50,7 @@ class SqlAlchemyUnitOfWork:
 
         Returns
         -------
+        UOW
             The Unit of Work instance.
 
         Raises
@@ -107,7 +113,13 @@ class SqlAlchemyUnitOfWork:
         self._session.rollback()
 
     def refresh(self, obj: object) -> None:
-        """Refresh the state of a given object."""
+        """Refresh the state of a given object.
+
+        Parameters
+        ----------
+        obj
+            The object to refresh.
+        """
         if not self._session:
             raise exceptions.DatabaseSessionError(
                 "No active database session is defined"
@@ -116,5 +128,11 @@ class SqlAlchemyUnitOfWork:
 
     @property
     def session(self) -> Session | None:
-        """Get the current database session."""
+        """Get the current database session.
+
+        Returns
+        -------
+        Session | None
+            The current database session.
+        """
         return self._session

alpha/containers/container.py

@@ -8,13 +8,18 @@ from alpha.handlers.models.argument import Argument
 
 
 class Container(containers.DeclarativeContainer):
-    """Dependency injection container for the alpha package."""
+    """Dependency injection container for the alpha package.
+
+    The container is used to manage the dependencies of the alpha package,
+    including the API generation and running commands. It allows for easy
+    configuration and extension of the commands and their dependencies.
+    """
 
     config = providers.Configuration()
 
     api_gen_command = providers.Factory(
         Command,
-        name='gen',
+        name="gen",
         help=(
             "Generate the API code and watch OpenAPI spec file. The API code "
             "will be generated into the ./api folder."
@@ -23,46 +28,46 @@ class Container(containers.DeclarativeContainer):
         arguments=providers.List(
             providers.Factory(
                 Argument,
-                default='specification/openapi.yaml',
-                name='--spec-file',
-                help='Path to the specification file',
+                default="specification/openapi.yaml",
+                name="--spec-file",
+                help="Path to the specification file",
                 args={
-                    'type': str,
-                    'nargs': '?',
+                    "type": str,
+                    "nargs": "?",
                 },
             ),
             providers.Factory(
                 Argument,
                 default=config.api_package_name,
-                name='--api-package',
+                name="--api-package",
                 help=(
                     "Name of the API package to generate. Automatically "
                     "determined or guessed. If incorrect, "
                     "just use this argument."
                 ),
                 args={
-                    'type': str,
-                    'nargs': '?',
+                    "type": str,
+                    "nargs": "?",
                 },
             ),
             providers.Factory(
                 Argument,
                 default=config.service_package_name,
-                name='--service-package',
+                name="--service-package",
                 help=(
                     "Name of the service package to use. Automatically "
                     "determined or guessed. If incorrect, "
                     "just use this argument."
                 ),
                 args={
-                    'type': str,
-                    'nargs': '?',
+                    "type": str,
+                    "nargs": "?",
                 },
             ),
             providers.Factory(
                 Argument,
                 default=config.container_import,
-                name='--container-import',
+                name="--container-import",
                 help=(
                     "Name of the container to use. Automatically "
                     "determined or guessed. If incorrect, "
@@ -70,76 +75,76 @@ class Container(containers.DeclarativeContainer):
                     "use empty string for this variable"
                 ),
                 args={
-                    'type': str,
-                    'nargs': '?',
+                    "type": str,
+                    "nargs": "?",
                 },
             ),
             providers.Factory(
                 Argument,
                 default=config.init_container_from,
-                name='--init-container-from',
+                name="--init-container-from",
                 help=(
                     "Location of where the container initialize function "
                     "should be imported from."
                 ),
                 args={
-                    'type': str,
-                    'nargs': '?',
+                    "type": str,
+                    "nargs": "?",
                 },
             ),
             providers.Factory(
                 Argument,
                 default=config.init_container_function,
-                name='--init-container-function',
+                name="--init-container-function",
                 help="Name of the container initialize function.",
                 args={
-                    'type': str,
-                    'nargs': '?',
+                    "type": str,
+                    "nargs": "?",
                 },
             ),
             providers.Factory(
                 Argument,
-                default='post_process.py',
-                name='--post-process-file',
+                default="post_process.py",
+                name="--post-process-file",
                 help="Path to the post process file to use after generation",
                 args={
-                    'type': str,
-                    'nargs': '?',
+                    "type": str,
+                    "nargs": "?",
                 },
             ),
             providers.Factory(
                 Argument,
-                default='python-flask',
-                name='--generator-name',
+                default="python-flask",
+                name="--generator-name",
                 help="Name of the openapi generator to use",
                 args={
-                    'type': str,
-                    'nargs': '?',
+                    "type": str,
+                    "nargs": "?",
                 },
             ),
             providers.Factory(
                 Argument,
                 default=False,
-                name='--no-watch',
+                name="--no-watch",
                 help=(
                     "To prevent watching the spec file for changes and only "
                     "run the generation once."
                 ),
                 args={
-                    'action': 'store_true',
+                    "action": "store_true",
                 },
             ),
             providers.Factory(
                 Argument,
                 default=False,
-                name='--templates-only',
+                name="--templates-only",
                 help=(
                     "Only create a templates folder containing openapi "
                     "mustache templates in the current working directory. "
                     "Skip generation of API code."
                 ),
                 args={
-                    'action': 'store_true',
+                    "action": "store_true",
                 },
             ),
         ),
@@ -147,28 +152,28 @@ class Container(containers.DeclarativeContainer):
 
     api_run_command = providers.Factory(
         Command,
-        name='run',
-        help='Run API in development mode',
+        name="run",
+        help="Run API in development mode",
         handler=providers.Factory(ApiRunHandler),
         arguments=providers.List(
             providers.Factory(
                 Argument,
                 default=config.api_package_name,
-                name='--api-package',
-                help='Name of the API package to generate',
+                name="--api-package",
+                help="Name of the API package to generate",
                 args={
-                    'type': str,
-                    'nargs': '?',
+                    "type": str,
+                    "nargs": "?",
                 },
             ),
             providers.Factory(
                 Argument,
-                default='8080',
-                name='--port',
-                help='Port to run server on',
+                default="8080",
+                name="--port",
+                help="Port to run server on",
                 args={
-                    'type': str,
-                    'nargs': '?',
+                    "type": str,
+                    "nargs": "?",
                 },
             ),
         ),
@@ -176,8 +181,8 @@ class Container(containers.DeclarativeContainer):
 
     api_section = providers.Factory(
         Section,
-        name='api',
-        description='OpenAPI development commands.',
+        name="api",
+        description="OpenAPI development commands.",
         help=(
             "All commands for generating and developing an API using the "
             "OpenAPI standards"

alpha/domain/__init__.py

@@ -1,10 +1,21 @@
 from alpha.domain.models.user import User
-from alpha.domain.models.base_model import BaseDomainModel, DomainModel
+from alpha.domain.models.group import Group
+from alpha.domain.models.role import Role
+from alpha.domain.models.base_model import (
+    BaseDomainModel,
+    DomainModel,
+    DomainModelCovariant,
+    DomainModelContravariant,
+)
 from alpha.domain.models.life_cycle_base import LifeCycleBase
 
 __all__ = [
     "BaseDomainModel",
     "DomainModel",
+    "DomainModelCovariant",
+    "DomainModelContravariant",
     "LifeCycleBase",
     "User",
+    "Group",
+    "Role",
 ]

alpha/domain/models/__init__.py

@@ -1,10 +1,21 @@
 from alpha.domain.models.user import User
-from alpha.domain.models.base_model import BaseDomainModel, DomainModel
+from alpha.domain.models.group import Group
+from alpha.domain.models.role import Role
+from alpha.domain.models.base_model import (
+    BaseDomainModel,
+    DomainModel,
+    DomainModelCovariant,
+    DomainModelContravariant,
+)
 from alpha.domain.models.life_cycle_base import LifeCycleBase
 
 __all__ = [
     "BaseDomainModel",
     "DomainModel",
+    "DomainModelCovariant",
+    "DomainModelContravariant",
     "LifeCycleBase",
     "User",
+    "Group",
+    "Role",
 ]

alpha/domain/models/base_model.py

@@ -12,7 +12,24 @@ DomainModelContravariant = TypeVar(
 
 @dataclass
 class BaseDomainModel:
+    """Base class for all domain models which can be inherited by all domain
+    models in the application.
+
+    This class is mainly being used to provide a common interface for all
+    domain models, and to provide a common method for converting the domain
+    model instance to a dictionary.
+
+    It has no attributes of its own.
+    """
+
     def to_dict(self) -> dict[str, Any]:
+        """Convert the domain model instance to a dictionary.
+
+        Returns
+        -------
+        dict[str, Any]
+            A dictionary representation of the domain model instance.
+        """
         obj: dict[str, Any] = {}
         for attr in self.__dataclass_fields__.keys():
             if not attr.startswith("_"):
@@ -22,4 +39,23 @@ class BaseDomainModel:
         return obj
 
     def update(self, obj: DomainModel) -> DomainModel:
-        raise NotImplementedError("Subclasses must implement the update method")
+        """Update the current instance with the values from another instance.
+
+        Parameters
+        ----------
+        obj
+            Object to update the current instance with.
+
+        Returns
+        -------
+        DomainModel
+            The updated instance of the domain model.
+
+        Raises
+        ------
+        NotImplementedError
+            If the method is not implemented in the subclass.
+        """
+        raise NotImplementedError(
+            "Subclasses must implement the update method"
+        )

alpha/domain/models/group.py

@@ -1,6 +1,6 @@
 from dataclasses import dataclass
 from datetime import datetime, timezone
-from typing import Sequence, cast
+from typing import Any, Sequence, cast
 from uuid import UUID
 
 from alpha.domain.models.base_model import BaseDomainModel, DomainModel
@@ -9,12 +9,52 @@ from alpha.domain.models.life_cycle_base import LifeCycleBase
 
 @dataclass(kw_only=True)
 class Group(LifeCycleBase, BaseDomainModel):
+    """Group domain model which represents a group of users with specific
+    permissions. The Group model includes attributes for group identification,
+    description, permissions, and lifecycle attributes for tracking creation
+    and modification times.
+
+    Attributes
+    ----------
+    id
+        Unique identifier for the group, which can be a UUID, integer, or
+        string.
+    name
+        The name of the group, used for identification and display purposes.
+    description
+        A brief description of the group and its purpose.
+    permissions
+        A list of specific permissions assigned to the group, which can be used
+        for group-based access control. Each permission can represent a
+        specific action or resource that the group has access to.
+    is_active
+        A boolean flag indicating whether the group is active. Inactive groups
+        may not be able to be assigned to users or may not grant permissions to
+        users assigned to the group.
+    """
+
     id: UUID | int | str | None = None
     name: str | None = None
     description: str | None = None
     permissions: Sequence[str] | None = None
     is_active: bool = True
 
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the Group instance to a dictionary.
+
+        Returns
+        -------
+        dict[str, Any]
+            A dictionary representation of the Group instance.
+        """
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "permissions": self.permissions,
+            "is_active": self.is_active,
+        }
+
     def update(self, obj: DomainModel) -> DomainModel:
         """Update the Group instance with data from another Group instance.
 
@@ -22,6 +62,16 @@ class Group(LifeCycleBase, BaseDomainModel):
         ----------
         obj
             Group object to update from.
+
+        Returns
+        -------
+        DomainModel
+            The updated instance of the Group.
+
+        Raises
+        ------
+        TypeError
+            If the provided object is not a Group instance.
         """
         if not isinstance(obj, Group):
             raise TypeError("Group.update expects a Group instance.")

alpha/domain/models/life_cycle_base.py

@@ -4,6 +4,25 @@ from datetime import datetime
 
 @dataclass
 class LifeCycleBase:
+    """Base class for lifecycle model attributes which can be inherited by all
+    domain models in the application.
+
+    Attributes
+    ----------
+    created_by
+        The identifier of the user who created the instance. This can be a
+        string or None.
+    created_at
+        The timestamp when the instance was created. This can be a datetime
+        object or None.
+    modified_by
+        The identifier of the user who last modified the instance. This can be
+        a string or None.
+    modified_at
+        The timestamp when the instance was last modified. This can be a
+        datetime object or None.
+    """
+
     created_by: str | None = None
     created_at: datetime | None = None
     modified_by: str | None = None