alpha-python 0.7.3__tar.gz → 0.7.5__tar.gz

{alpha_python-0.7.3 → alpha_python-0.7.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpha-python
-Version: 0.7.3
+Version: 0.7.5
 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>
 License-Expression: MIT

{alpha_python-0.7.3 → alpha_python-0.7.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "alpha-python"
-version = "0.7.3"
+version = "0.7.5"
 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 = [

{alpha_python-0.7.3 → alpha_python-0.7.5}/src/alpha/adapters/rest_api_unit_of_work.py

@@ -1,9 +1,10 @@
 """Contains the REST API Unit of Work implementation."""
 
-from typing import Any, TypeVar
+from typing import Any, TypeVar, cast
 
 import requests
 
+from alpha.interfaces.http_client import HTTPClient
 from alpha.repositories.models.repository_model import RepositoryModel
 
 
@@ -22,7 +23,7 @@ class RestApiUnitOfWork:
     def __init__(
         self,
         repos: list[RepositoryModel[Any]],
-        session: requests.sessions.Session | None = None,
+        session: HTTPClient | None = None,
     ) -> None:
         """Initialize the Unit of Work with repositories.
 
@@ -44,11 +45,12 @@ class RestApiUnitOfWork:
 
     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.
+
+        Initializes an `HTTPClient` 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
         -------
@@ -56,7 +58,9 @@ class RestApiUnitOfWork:
             The configured :class:`RestApiUnitOfWork` instance to be used
             within the context manager.
         """
-        self._session = self._session or requests.sessions.Session()
+        self._session = cast(
+            HTTPClient, self._session or requests.sessions.Session()
+        )
 
         for repo in self._repositories:
             name: str = repo.name
@@ -100,12 +104,12 @@ class RestApiUnitOfWork:
         raise NotImplementedError("RestApiUnitOfWork does not support refresh")
 
     @property
-    def session(self) -> requests.sessions.Session | None:
+    def session(self) -> HTTPClient | None:
         """Get the current session.
 
         Returns
         -------
-        requests.sessions.Session | None
+        HTTPClient | None
             The current session used for API interactions.
         """
         return self._session

{alpha_python-0.7.3 → alpha_python-0.7.5}/src/alpha/adapters/sqla_unit_of_work.py

@@ -78,14 +78,22 @@ class SqlAlchemyUnitOfWork:
 
         return self
 
-    def __exit__(self, *args: Any) -> None:
-        """Finalize the Unit of Work context."""
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Finalize the Unit of Work context.
+
+        Roll back only when leaving the context because of an exception.
+        Rolling back after a successful commit can expire ORM state and may
+        trigger DetachedInstanceError once the session is closed/detached.
+        """
         if not self._session:
             raise exceptions.DatabaseSessionError(
                 "No active database session is defined"
             )
+
+        if exc_type is not None:
+            self._session.rollback()
+
         self._session.close()
-        self.rollback()
         self._session = None  # type: ignore
 
     def commit(self) -> None:

{alpha_python-0.7.3 → alpha_python-0.7.5}/src/alpha/domain/models/group.py

@@ -1,6 +1,6 @@
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from typing import Any, Sequence, cast
+from typing import Any, cast
 from uuid import UUID
 
 from alpha.domain.models.base_model import BaseDomainModel, DomainModel
@@ -36,7 +36,7 @@ class Group(LifeCycleBase, BaseDomainModel):
     id: UUID | int | str | None = None
     name: str | None = None
     description: str | None = None
-    permissions: Sequence[str] | None = None
+    permissions: list[str] = field(default_factory=list)  # type: ignore
     is_active: bool = True
 
     def to_dict(self) -> dict[str, Any]:

{alpha_python-0.7.3 → alpha_python-0.7.5}/src/alpha/domain/models/user.py

@@ -1,6 +1,6 @@
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from typing import Any, Self, Sequence, cast
+from typing import Any, Self, cast
 from uuid import UUID
 
 from alpha.domain.models.base_model import BaseDomainModel, DomainModel
@@ -67,8 +67,8 @@ class User(LifeCycleBase, BaseDomainModel):
     email: str | None = None
     phone: str | None = None
     display_name: str | None = None
-    permissions: Sequence[str] | None = None
-    groups: Sequence[str | Group] | None = None
+    permissions: list[str] = field(default_factory=list)  # type: ignore
+    groups: list[str | Group] = field(default_factory=list)  # type: ignore
     is_active: bool = True
     admin: bool = False
 

{alpha_python-0.7.3 → alpha_python-0.7.5}/src/alpha/factories/request_factory.py

@@ -25,6 +25,8 @@ from alpha.interfaces.factories import (
 )
 from alpha.interfaces.openapi_model import OpenAPIModel
 from alpha.interfaces.pydantic_instance import PydanticInstance
+from alpha.providers.models.identity import Identity
+from alpha.utils.request_headers import Headers
 
 
 class RequestFactory:
@@ -184,6 +186,8 @@ class RequestFactory:
         DataclassInstance
         | AttrsInstance
         | PydanticInstance
+        | Identity
+        | Headers
         | None
         | OpenAPIModel
     ):
@@ -202,6 +206,9 @@ class RequestFactory:
         -------
         DataclassInstance | AttrsInstance | PydanticInstance | None
             Dataclass, attrs, or pydantic instance
+        Identity | Headers
+            If the value is an instance of Identity or Headers, it will be
+            returned as is.
         OpenAPIModel
             If the `use_model_class_factory` parameter is set to False, the
             value will be returned as an OpenAPIModel instance.
@@ -211,6 +218,9 @@ class RequestFactory:
         TypeError
             The value is not an instance of the OpenAPI (Base)Model
         """
+        if isinstance(value, (Identity, Headers)):
+            return value
+
         if not isinstance(value, OpenAPIModel):
             raise TypeError(f"Unable to map {type(value)} on dataclass model")
 

{alpha_python-0.7.3 → alpha_python-0.7.5}/src/alpha/handlers/templates/python-flask/controller.mustache

@@ -198,6 +198,7 @@ def {{operationId}}(
     auth_token = headers.auth_token if headers.has_auth_token else None
     refresh_token = headers.refresh_token
     api_key = headers.api_key
+    cookies = headers.cookies
 
     {{#vendorExtensions.x-alpha-factory}}
     factory = {{vendorExtensions.x-alpha-factory}}

{alpha_python-0.7.3 → alpha_python-0.7.5}/src/alpha/interfaces/api_repository.py

@@ -11,6 +11,27 @@ from alpha.infra.models.json_patch import JsonPatch
 class ApiRepository(Protocol[DomainModel]):
     """Repository contract for remote API resources."""
 
+    def request(
+        self,
+        method: str,
+        url: str,
+        **kwargs: Any,
+    ) -> Any | None:
+        """Make a custom API request.
+
+        Parameters
+        ----------
+        method
+            The HTTP method to use for the request (e.g., 'GET', 'POST',
+            'PATCH', 'PUT', 'DELETE').
+        url
+            The URL to which the request should be made.
+        **kwargs
+            Additional parameters to include in the API request, such as
+            headers, authentication tokens, or other request options.
+        """
+        ...
+
     @overload
     def add(
         self,

{alpha_python-0.7.3 → alpha_python-0.7.5}/src/alpha/interfaces/sql_repository.py

@@ -3,7 +3,14 @@ SQLAlchemy ORM repository operations.
 """
 
 from enum import Enum
-from typing import Any, Literal, Protocol, overload, runtime_checkable
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    Protocol,
+    overload,
+    runtime_checkable,
+)
 from uuid import UUID
 
 from sqlalchemy.orm import Session
@@ -12,7 +19,11 @@ from sqlalchemy.orm.attributes import InstrumentedAttribute
 from alpha.domain.models.base_model import BaseDomainModel, DomainModel
 from alpha.infra.models.json_patch import JsonPatch
 from alpha.interfaces.patchable import Patchable
-from alpha.interfaces.updatable import Updatable
+
+if TYPE_CHECKING:
+    from alpha.interfaces.updatable import Updatable
+else:
+    Updatable = Any
 
 
 @runtime_checkable

{alpha_python-0.7.3 → alpha_python-0.7.5}/src/alpha/mixins/user_lifecycle.py

@@ -1,6 +1,6 @@
 """Contains the UserLifecycleMixin class"""
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 from uuid import UUID
 
 from alpha.exceptions import BadRequestException, NotFoundException
@@ -11,6 +11,8 @@ from alpha.providers.models.identity import Identity
 
 if TYPE_CHECKING:
     from alpha.domain.models.user import User
+else:
+    User = Any
 
 
 class UserLifecycleMixin:
@@ -20,15 +22,13 @@ class UserLifecycleMixin:
 
     uow: UnitOfWork
     _users_repository_name: str
-    _user_model: type["User"]
+    _user_model: type[User]
     _password_support: bool
     _password_factory: PasswordFactory
     _user_username_attribute: str
     _user_password_attribute: str
 
-    def add_user(
-        self, user: "User", identity: Identity | None = None
-    ) -> "User":
+    def add_user(self, user: User, identity: Identity | None = None) -> User:
         """Adds a new user object to the repository
 
         Parameters
@@ -79,7 +79,7 @@ class UserLifecycleMixin:
             self.uow.commit()
             return user
 
-    def get_user(self, user_id: str | int | UUID) -> "User":
+    def get_user(self, user_id: str | int | UUID) -> User:
         """Get an user object by id from the repository
 
         Parameters
@@ -110,7 +110,7 @@ class UserLifecycleMixin:
 
             return user
 
-    def get_users(self) -> list["User"]:
+    def get_users(self) -> list[User]:
         """Gets all user objects from the repository
 
         Returns
@@ -119,7 +119,7 @@ class UserLifecycleMixin:
             A collection of all the user objects
         """
         with self.uow:
-            users: SqlRepository["User"] = getattr(
+            users: SqlRepository[User] = getattr(
                 self.uow, self._users_repository_name
             )
             result = users.select()
@@ -136,7 +136,7 @@ class UserLifecycleMixin:
         """
         user = self.get_user(user_id=user_id)
         with self.uow:
-            users: SqlRepository["User"] = getattr(
+            users: SqlRepository[User] = getattr(
                 self.uow, self._users_repository_name
             )
 
@@ -146,9 +146,9 @@ class UserLifecycleMixin:
     def update_user(
         self,
         user_id: str | int | UUID,
-        user: "User",
+        user: User,
         identity: Identity | None = None,
-    ) -> "User":
+    ) -> User:
         """Updates an existing user object in the repository
 
         Parameters

{alpha_python-0.7.3 → alpha_python-0.7.5}/src/alpha/providers/ldap_provider.py

@@ -45,6 +45,7 @@ class LDAPProvider(JWTProviderMixin):
         populate_groups: bool = True,
         populate_permissions: bool = False,
         populate_claims: bool = True,
+        flatten_claims: bool = True,
         auto_connect: bool = True,
         change_password_supported: bool = False,
         additional_connector_params: dict[str, Any] | None = None,
@@ -71,6 +72,9 @@ class LDAPProvider(JWTProviderMixin):
             Whether to populate permissions in the Identity, by default False
         populate_claims
             Whether to populate claims in the Identity, by default True
+        flatten_claims
+            Whether to flatten single-value claims in the Identity, by default
+            True
         auto_connect
             Whether to automatically connect using the connector, by default
             True
@@ -89,6 +93,7 @@ class LDAPProvider(JWTProviderMixin):
         self._populate_groups = populate_groups
         self._populate_permissions = populate_permissions
         self._populate_claims = populate_claims
+        self._flatten_claims = flatten_claims
         self._auto_connect = auto_connect
         self._change_password_supported = change_password_supported
         self._additional_connector_params = additional_connector_params or {
@@ -297,6 +302,7 @@ class LDAPProvider(JWTProviderMixin):
             populate_claims=self._populate_claims,
             populate_groups=self._populate_groups,
             populate_permissions=self._populate_permissions,
+            flatten_claims=self._flatten_claims,
         )
         return identity
 
@@ -324,6 +330,7 @@ class ADProvider(LDAPProvider):
         populate_groups: bool = True,
         populate_permissions: bool = False,
         populate_claims: bool = True,
+        flatten_claims: bool = True,
         auto_connect: bool = True,
         change_password_supported: bool = False,
     ) -> None:
@@ -356,6 +363,9 @@ class ADProvider(LDAPProvider):
         populate_claims
             Whether to populate claims on the :class:`Identity`, by default
             True.
+        flatten_claims
+            Whether to flatten single-value claims in the Identity, by default
+            True
         auto_connect
             Whether to automatically open the LDAP connection on first use, by
             default True.
@@ -373,6 +383,7 @@ class ADProvider(LDAPProvider):
             populate_groups=populate_groups,
             populate_permissions=populate_permissions,
             populate_claims=populate_claims,
+            flatten_claims=flatten_claims,
             auto_connect=auto_connect,
             change_password_supported=change_password_supported,
         )

{alpha_python-0.7.3 → alpha_python-0.7.5}/src/alpha/providers/models/identity.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Mapping, Any, Self, Sequence, TYPE_CHECKING
+from typing import Mapping, Any, Self, Sequence, TYPE_CHECKING, cast
 from datetime import datetime, timezone
 
 from alpha.domain.models.group import Group
@@ -9,6 +9,8 @@ from alpha.domain.models.group import Group
 
 if TYPE_CHECKING:
     from alpha.domain.models.user import User
+else:
+    User = Any
 
 DEFAULT_LDAP_MAPPINGS = {
     "subject": "uid",
@@ -158,7 +160,8 @@ class Identity:
         populate_groups: bool = True,
         populate_permissions: bool = False,
         populate_claims: bool = True,
-    ) -> "Identity":
+        flatten_claims: bool = False,
+    ) -> Identity:
         """Instantiate an Identity from an LDAP entry dictionary.
 
         Parameters
@@ -176,6 +179,9 @@ class Identity:
         populate_claims
             Whether to populate the claims dictionary from the LDAP entry, by
             default True
+        flatten_claims
+            Whether to replace claim lists containing a single value with that
+            value, by default False
 
         Returns
         -------
@@ -186,6 +192,12 @@ class Identity:
         if not username:
             username = cls._get_key(entry, mappings["subject"])
 
+        claims = (
+            cls._remove_password_from_claims(entry) if populate_claims else {}
+        )
+        if populate_claims and flatten_claims:
+            claims = cls.flatten_single_value_claims(claims)
+
         return cls(
             subject=cls._get_key(entry, mappings["subject"], ""),
             username=username,
@@ -202,16 +214,12 @@ class Identity:
                 if populate_permissions
                 else []
             ),
-            claims=(
-                cls._remove_password_from_claims(entry)
-                if populate_claims
-                else {}
-            ),
+            claims=claims,
             issued_at=datetime.now(tz=timezone.utc),
         )
 
     @classmethod
-    def from_dict(cls, data: Mapping[str, Any]) -> "Identity":
+    def from_dict(cls, data: Mapping[str, Any]) -> Identity:
         """Instantiate an Identity from a generic dictionary.
 
         Parameters
@@ -252,7 +260,7 @@ class Identity:
         )
 
     @classmethod
-    def from_user(cls, user: User) -> "Identity":
+    def from_user(cls, user: User) -> Identity:
         """Instantiate an Identity from a User instance.
 
         Parameters
@@ -428,6 +436,37 @@ class Identity:
         }
         return filtered_claims
 
+    @staticmethod
+    def flatten_single_value_claims(
+        claims: Mapping[str, Any],
+    ) -> Mapping[str, Any]:
+        """Replace single-value claim lists with their contained value.
+
+        Password-related claims (keys containing "password", case-insensitive)
+        are removed before flattening.
+
+        Parameters
+        ----------
+        claims
+            Original claims dictionary.
+
+        Returns
+        -------
+        Mapping[str, Any]
+            A new claims dictionary with password-related keys removed and
+            single-value lists replaced by their contained value.
+        """
+        claims = Identity._remove_password_from_claims(claims)
+
+        return {
+            key: (
+                value[0]
+                if isinstance(value, list) and len(cast(list[Any], value)) == 1
+                else value
+            )
+            for key, value in claims.items()
+        }
+
     @staticmethod
     def _extract_groups(
         entry: Mapping[str, Any],

{alpha_python-0.7.3 → alpha_python-0.7.5}/src/alpha/providers/oidc_provider.py

@@ -57,6 +57,7 @@ class OIDCProvider(JWTProviderMixin):
         populate_groups: bool = True,
         populate_permissions: bool = False,
         populate_claims: bool = False,
+        flatten_claims: bool = True,
         change_password_supported: bool = False,
     ) -> None:
         """Initialize OIDCProvider.
@@ -90,6 +91,7 @@ class OIDCProvider(JWTProviderMixin):
         self._populate_groups = populate_groups
         self._populate_permissions = populate_permissions
         self._populate_claims = populate_claims
+        self._flatten_claims = flatten_claims
         self._change_password_supported = change_password_supported
 
     def authenticate(self, credentials: PasswordCredentials) -> Identity:
@@ -237,6 +239,9 @@ class OIDCProvider(JWTProviderMixin):
 
         audience = self._extract_audience(claims)
 
+        if self._populate_claims and self._flatten_claims:
+            claims = Identity.flatten_single_value_claims(claims)
+
         identity = Identity(
             subject=str(subject),
             username=username,
@@ -244,7 +249,7 @@ class OIDCProvider(JWTProviderMixin):
             display_name=self._get_claim(claims, "display_name"),
             groups=groups,
             permissions=permissions,
-            claims=dict(claims) if self._populate_claims else {},
+            claims=claims if self._populate_claims else {},
             issued_at=issued_at,
             audience=audience,
             role=self._get_claim(claims, "role"),
@@ -403,6 +408,7 @@ class KeyCloakProvider(OIDCProvider):
         populate_groups: bool = True,
         populate_permissions: bool = False,
         populate_claims: bool = False,
+        flatten_claims: bool = True,
         change_password_supported: bool = False,
     ) -> None:
         """Initialize KeyCloakProvider.
@@ -427,6 +433,9 @@ class KeyCloakProvider(OIDCProvider):
             Whether to populate permissions on the Identity.
         populate_claims
             Whether to include raw claims on the Identity.
+        flatten_claims
+            Whether to flatten single-value claims when populating raw claims
+            on the Identity.
         change_password_supported
             Whether this provider supports changing passwords.
         """
@@ -437,5 +446,6 @@ class KeyCloakProvider(OIDCProvider):
             populate_groups=populate_groups,
             populate_permissions=populate_permissions,
             populate_claims=populate_claims,
+            flatten_claims=flatten_claims,
             change_password_supported=change_password_supported,
         )

{alpha_python-0.7.3 → alpha_python-0.7.5}/src/alpha/repositories/refresh/database_repository.py

@@ -1,5 +1,5 @@
 from alpha import exceptions
-from alpha.infra.connectors.sql_alchemy import SqlAlchemyDatabase
+from alpha.interfaces.sql_database import SqlDatabase
 from alpha.providers.models.token import Token
 
 
@@ -15,7 +15,7 @@ class DatabaseRefreshRepository:
 
     def __init__(
         self,
-        database_connector: SqlAlchemyDatabase,
+        database_connector: SqlDatabase,
         token_model: type[Token] = Token,
         token_max_age_seconds: int = 7 * 24 * 3600,
         token_length: int = 32,

{alpha_python-0.7.3 → alpha_python-0.7.5}/src/alpha/utils/request_headers.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass
-from http import cookies
+from http.cookies import SimpleCookie
 from typing import Mapping, Self
 
 
@@ -16,12 +16,28 @@ class Headers:
 
     This class is designed to be immutable and uses slots for memory
     efficiency.
+
+    Attributes
+    ----------
+    auth_token
+        The authentication token, typically a JWT, extracted from the
+        "Authorization" header or from cookies.
+    auth_token_type
+        The type of the authentication token, typically "Bearer".
+    refresh_token
+        The refresh token, extracted from the "X-Refresh-Token" header or from
+        cookies.
+    api_key
+        The API key, extracted from the "X-API-Key" header or from cookies.
+    cookies
+        A mapping of cookie names to their values, if any cookies are present.
     """
 
     auth_token: str | None = None
     auth_token_type: str | None = None
     refresh_token: str | None = None
     api_key: str | None = None
+    _cookie_jar: SimpleCookie | None = None
 
     @classmethod
     def from_headers(
@@ -73,8 +89,9 @@ class Headers:
         api_key = headers.get("X-API-Key")
         cookies_header = headers.get("Cookie")
 
+        cookie_jar: SimpleCookie | None = None
         if cookies_header is not None:
-            cookie_jar = cookies.SimpleCookie(cookies_header)
+            cookie_jar = SimpleCookie(cookies_header)
 
             if not auth_token and auth_token_cookie_name in cookie_jar:
                 auth_token = cookie_jar[auth_token_cookie_name].value
@@ -89,6 +106,7 @@ class Headers:
             auth_token_type=auth_token_type,
             refresh_token=refresh_token,
             api_key=api_key,
+            _cookie_jar=cookie_jar,
         )
 
     @property
@@ -107,6 +125,20 @@ class Headers:
     def has_api_key(self) -> bool:
         return True if self.api_key else False
 
+    @property
+    def cookies(self) -> dict[str, str]:
+        """Return a dictionary of cookies extracted from the request headers.
+
+        Returns
+        -------
+        dict[str, str]
+            A dictionary mapping cookie names to their values. If no cookies
+            are present, an empty dictionary is returned.
+        """
+        if self._cookie_jar is None:
+            return {}
+        return self._cookie_jar_to_dict(self._cookie_jar)
+
     def __repr__(self) -> str:
         return (
             f"Headers(auth_token={'***' if self.auth_token else None}, "
@@ -114,3 +146,19 @@ class Headers:
             f"refresh_token={'***' if self.refresh_token else None}, "
             f"api_key={'***' if self.api_key else None})"
         )
+
+    @staticmethod
+    def _cookie_jar_to_dict(cookie_jar: SimpleCookie) -> dict[str, str]:
+        """Convert a SimpleCookie object to a dictionary.
+
+        Parameters
+        ----------
+        cookie_jar
+            A SimpleCookie object containing the cookies.
+
+        Returns
+        -------
+        dict[str, str]
+            A dictionary mapping cookie names to their values.
+        """
+        return {key: morsel.value for key, morsel in cookie_jar.items()}