alpha-python 0.5.1__py3-none-any.whl → 0.6.1__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,7 +55,12 @@ 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
@@ -63,6 +79,7 @@ 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 (
@@ -77,6 +94,9 @@ try:
 except ImportError:
     _LDAP_AVAILABLE = False  # type: ignore
 
+
+__version__ = version("alpha-python")
+
 __all__ = [
     "RestApiUnitOfWork",
     "SqlAlchemyUnitOfWork",
@@ -85,8 +105,12 @@ __all__ = [
     "ModelClassFactory",
     "BaseDomainModel",
     "DomainModel",
+    "DomainModelCovariant",
+    "DomainModelContravariant",
     "LifeCycleBase",
     "User",
+    "Group",
+    "Role",
     "OIDCConnector",
     "KeyCloakOIDCConnector",
     "SqlAlchemyDatabase",
@@ -101,7 +125,7 @@ __all__ = [
     "DataclassInstance",
     "PydanticInstance",
     "OpenAPIModel",
-    "Updateable",
+    "Updatable",
     "Patchable",
     "ApiRepository",
     "SqlRepository",
@@ -116,6 +140,8 @@ __all__ = [
     "TokenIssuer",
     "TokenFactory",
     "JWTProviderMixin",
+    "UserLifecycleMixin",
+    "GroupLifecycleMixin",
     "Identity",
     "DEFAULT_LDAP_MAPPINGS",
     "DEFAULT_AD_MAPPINGS",
@@ -124,6 +150,8 @@ __all__ = [
     "Token",
     "OIDCProvider",
     "KeyCloakProvider",
+    "DEFAULT_OIDC_MAPPINGS",
+    "DEFAULT_KEYCLOAK_MAPPINGS",
     "RepositoryModel",
     "RestApiRepository",
     "SqlAlchemyRepository",
@@ -151,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/cli.py

@@ -20,18 +20,18 @@ def main(sections: list[Section] = Provide[Container.sections]) -> None:
 
     # Create the main parser
     parser = argparse.ArgumentParser(
-        description='Alpha command line interface.',
+        description="Alpha command line interface.",
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
     )
     subparsers = parser.add_subparsers(
-        title='Use one of the sub categories to run commands on',
-        dest='section',
+        title="Use one of the sub categories to run commands on",
+        dest="section",
     )
 
     # Parser dict to store in all parsers to match later on when finding a
     # handler.
-    section_parsers = {}
-    command_parsers = {}
+    section_parsers: dict[str, argparse.ArgumentParser] = {}
+    command_parsers: dict[str, dict[str, argparse.ArgumentParser]] = {}
 
     # Create all sections
     for section in sections:
@@ -43,7 +43,7 @@ def main(sections: list[Section] = Provide[Container.sections]) -> None:
             formatter_class=argparse.ArgumentDefaultsHelpFormatter,
         )
         section_subparser = section_parsers[section.name].add_subparsers(
-            dest='command'
+            dest="command"
         )
 
         # Create all commands per section
@@ -88,8 +88,8 @@ def main(sections: list[Section] = Provide[Container.sections]) -> None:
     # Get all arguments and remove the section and command so they can be
     # 'kwarged' into the Handler set_arguments function.
     handler_args = vars(args)
-    del handler_args['section']
-    del handler_args['command']
+    del handler_args["section"]
+    del handler_args["command"]
 
     # Find the right handler
     for section in sections:
@@ -102,7 +102,7 @@ def main(sections: list[Section] = Provide[Container.sections]) -> None:
                 command.handler.handle_command()
                 return
 
-    print('No handler found, you should never read this')
+    print("No handler found, you should never read this")
     return
 
 
@@ -118,53 +118,57 @@ def _guess_current_package_name() -> str:
     """
 
     cwd = os.getcwd()
-    pyproject_path = os.path.join(cwd, 'pyproject.toml')
+    pyproject_path = os.path.join(cwd, "pyproject.toml")
 
     # look for pyproject.toml file in subfolders
     if not os.path.isfile(pyproject_path):
         for entry in os.scandir(cwd):
             if not entry.is_dir():
                 continue
-            possible_path = os.path.join(entry.path, 'pyproject.toml')
+            possible_path = os.path.join(entry.path, "pyproject.toml")
             if os.path.isfile(possible_path):
                 pyproject_path = possible_path
                 break
 
     if os.path.isfile(pyproject_path):
         try:
-            with open(pyproject_path, 'rb') as f:
+            with open(pyproject_path, "rb") as f:
                 pyproject_data = tomllib.load(f)
                 name = None
                 try:
-                    if 'project' in pyproject_data:
-                        name = pyproject_data['project']['name']
-                    elif 'tool' in pyproject_data and 'poetry' in pyproject_data['tool']:
-                        name = pyproject_data['tool']['poetry']['name']
+                    if "project" in pyproject_data:
+                        name = pyproject_data["project"]["name"]
+                    elif (
+                        "tool" in pyproject_data
+                        and "poetry" in pyproject_data["tool"]
+                    ):
+                        name = pyproject_data["tool"]["poetry"]["name"]
                     if name is not None:
-                        return name.replace('-', '_')
+                        return name.replace("-", "_")
                 except KeyError:
-                    print('Could not find project name in pyproject.toml')
+                    print("Could not find project name in pyproject.toml")
         except Exception:
             pass
     else:
-        print('Could not find pyproject.toml')
+        print("Could not find pyproject.toml")
 
     # Fallback to use the current folder name
-    print('Guessing package name from folder')
+    print("Guessing package name from folder")
     return os.path.basename(cwd)
 
+
 def init() -> None:
     """Init the container and wire it to the main function."""
     container = Container()
     guessed_name = _guess_current_package_name()
     if guessed_name:
-        container.config.api_package_name.from_value(f'{guessed_name}_api')
+        container.config.api_package_name.from_value(f"{guessed_name}_api")
         container.config.service_package_name.from_value(guessed_name)
         container.config.container_import.from_value(
-            f'from {guessed_name}.containers.container import Container'
+            f"from {guessed_name}.containers.container import Container"
         )
         container.config.init_container_from.from_value(guessed_name)
-        container.config.init_container_function.from_value('init_container')
+        container.config.init_container_function.from_value("init_container")
     container.wire(modules=[sys.modules[__name__]])
 
     main()

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",
 ]