alpha-python 0.4.0__tar.gz → 0.5.1__tar.gz

{alpha_python-0.4.0 → alpha_python-0.5.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 breijling
+Copyright (c) 2026 Bart Reijling
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{alpha_python-0.4.0/src/alpha_python.egg-info → alpha_python-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpha-python
-Version: 0.4.0
+Version: 0.5.1
 Summary: Alpha is intended to be the first dependency you need to add to your Python application. It is a Python library which contains standard building blocks that can be used in applications that are used as APIs and/or make use of database interaction.
 Author-email: Bart Reijling <bart@reijling.eu>
 Requires-Python: >=3.11
@@ -29,6 +29,7 @@ Requires-Dist: itsdangerous==1.1.0; extra == "flask"
 Requires-Dist: MarkupSafe<2.0.2; extra == "flask"
 Requires-Dist: Jinja2==2.11.2; extra == "flask"
 Requires-Dist: Flask<2,>=1.1.2; extra == "flask"
+Requires-Dist: Werkzeug<2.1.0,>=1.0.1; extra == "flask"
 Requires-Dist: flask-cors>=3.0.10; extra == "flask"
 Requires-Dist: Flask-Compress>=1.13; extra == "flask"
 Provides-Extra: mysql
@@ -41,4 +42,59 @@ Dynamic: license-file
 
 # alpha
 
-Alpha is intended to be the first dependency you need to add to your Python application. It is a Python library which contains standard building blocks that can be used in applications that are used as APIs and/or make use of database interaction. 
+Alpha is intended to be the first dependency you need to add to your Python application. It is a Python library which contains standard building blocks that can be used in applications that are used as APIs and/or make use of database interaction.
+
+## Badges
+
+[![PyPI version](https://badge.fury.io/py/alpha-python.svg)](https://badge.fury.io/py/alpha-python)
+[![Build Status](https://travis-ci.com/breijling/alpha.svg?branch=main)](https://travis-ci.com/breijling/alpha)
+[![Coverage Status](https://coveralls.io/repos/github/breijling/alpha/badge.svg?branch=main)](https://coveralls.io/github/breijling/alpha?branch=main)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
+
+## Documentation
+
+TODO: Add documentation link when available.
+
+## Installation
+
+The library is still in development, but you can already install it using pip:
+
+```shell
+pip install alpha-python
+```
+
+If you want to use the alpha cli for generating API code, you can install it using pip as well:
+
+```shell
+pip install alpha-python[api-generator]
+```
+
+If you want to add the library to your API project, you can add it to your pyproject.toml file:
+
+```shell
+# Poetry example
+poetry add alpha-python --extras "flask, postgresql"
+poetry add --dev alpha-python --extras "api-generator"
+
+# UV example
+uv add alpha-python --extra flask --extra postgresql
+uv add --dev alpha-python --extra api-generator
+```
+
+## Usage
+
+The library contains a lot of different components, but the most important ones are:
+
+- `alpha.encoder.JSONEncoder`: A JSON encoder that can be used to serialize complex objects to JSON.
+
+## Features
+
+
+
+## Contributing
+
+If you want to contribute to the development of this library, you can fork the repository and create a pull request with your changes.
+
+## License
+
+This library is licensed under the MIT License. See the LICENSE file for more information.

alpha_python-0.5.1/README.md

@@ -0,0 +1,58 @@
+# alpha
+
+Alpha is intended to be the first dependency you need to add to your Python application. It is a Python library which contains standard building blocks that can be used in applications that are used as APIs and/or make use of database interaction.
+
+## Badges
+
+[![PyPI version](https://badge.fury.io/py/alpha-python.svg)](https://badge.fury.io/py/alpha-python)
+[![Build Status](https://travis-ci.com/breijling/alpha.svg?branch=main)](https://travis-ci.com/breijling/alpha)
+[![Coverage Status](https://coveralls.io/repos/github/breijling/alpha/badge.svg?branch=main)](https://coveralls.io/github/breijling/alpha?branch=main)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
+
+## Documentation
+
+TODO: Add documentation link when available.
+
+## Installation
+
+The library is still in development, but you can already install it using pip:
+
+```shell
+pip install alpha-python
+```
+
+If you want to use the alpha cli for generating API code, you can install it using pip as well:
+
+```shell
+pip install alpha-python[api-generator]
+```
+
+If you want to add the library to your API project, you can add it to your pyproject.toml file:
+
+```shell
+# Poetry example
+poetry add alpha-python --extras "flask, postgresql"
+poetry add --dev alpha-python --extras "api-generator"
+
+# UV example
+uv add alpha-python --extra flask --extra postgresql
+uv add --dev alpha-python --extra api-generator
+```
+
+## Usage
+
+The library contains a lot of different components, but the most important ones are:
+
+- `alpha.encoder.JSONEncoder`: A JSON encoder that can be used to serialize complex objects to JSON.
+
+## Features
+
+
+
+## Contributing
+
+If you want to contribute to the development of this library, you can fork the repository and create a pull request with your changes.
+
+## License
+
+This library is licensed under the MIT License. See the LICENSE file for more information.

{alpha_python-0.4.0 → alpha_python-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "alpha-python"
-version = "0.4.0"
+version = "0.5.1"
 description = "Alpha is intended to be the first dependency you need to add to your Python application. It is a Python library which contains standard building blocks that can be used in applications that are used as APIs and/or make use of database interaction."
 readme = "README.md"
 authors = [
@@ -56,7 +56,10 @@ dev = [
     "psycopg2-binary>=2.9.11",
     "pymysql>=1.1.2",
     "ldap3>=2.9.1",
-    "cryptography>=46.0.3"
+    "cryptography>=46.0.3",
+    "ipykernel>=7.2.0",
+    "flask<2",
+    "httpx>=0.28.1",
 ]
 
 [project.optional-dependencies]
@@ -72,6 +75,7 @@ flask = [
     "MarkupSafe<2.0.2",
     "Jinja2==2.11.2",
     "Flask>=1.1.2,<2",
+    "Werkzeug>=1.0.1,<2.1.0",
     "flask-cors>=3.0.10",
     "Flask-Compress>=1.13",
 ]
@@ -116,5 +120,9 @@ force_grid_wrap = 0
 python_version = "3.11"
 exclude = ['^tests/']
 
+[[tool.mypy.overrides]]
+module = ["flask", "flask.*"]
+ignore_missing_imports = true
+
 [tool.ruff]
 line-length = 79

{alpha_python-0.4.0 → alpha_python-0.5.1}/src/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_python-0.4.0 → alpha_python-0.5.1}/src/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_python-0.5.1/src/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_python-0.4.0 → alpha_python-0.5.1}/src/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_python-0.5.1/src/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_python-0.5.1/src/alpha/domain/models/user.py

@@ -0,0 +1,130 @@
+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 | Role | None = None
+    email: str | None = None
+    phone: str | None = None
+    display_name: str | None = None
+    permissions: Sequence[str] | None = None
+    groups: Sequence[str | Group] | None = None
+    is_active: bool = True
+    admin: bool = False
+
+    @classmethod
+    def from_identity(cls, identity: Identity) -> Self:
+        """Create a User instance from an Identity instance.
+
+        Parameters
+        ----------
+        identity
+            Identity object to convert.
+
+        Returns
+        -------
+            User instance created from the Identity.
+        """
+        return cls(
+            id=identity.subject,
+            username=identity.username,
+            email=identity.email,
+            display_name=identity.display_name,
+        )
+
+    def update(self, obj: DomainModel) -> DomainModel:
+        """Update the User instance with data from another User instance.
+
+        Parameters
+        ----------
+        obj
+            User object to update from.
+        """
+        if not isinstance(obj, User):
+            raise TypeError("User.update expects a User instance.")
+
+        self.username = obj.username
+        self.email = obj.email
+        self.phone = obj.phone
+        self.display_name = obj.display_name
+        self.permissions = obj.permissions
+        self.groups = obj.groups
+        self.modified_at = datetime.now(tz=timezone.utc)
+        self.is_active = obj.is_active
+        self.admin = obj.admin
+        return cast(DomainModel, self)

{alpha_python-0.4.0 → alpha_python-0.5.1}/src/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."""