alpha-python 0.7.4__tar.gz → 0.7.6__tar.gz

{alpha_python-0.7.4 → alpha_python-0.7.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpha-python
-Version: 0.7.4
+Version: 0.7.6
 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
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Python: <3.15,>=3.11
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: attrs>=25.4.0

{alpha_python-0.7.4 → alpha_python-0.7.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "alpha-python"
-version = "0.7.4"
+version = "0.7.6"
 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 = [
@@ -18,7 +18,7 @@ classifiers = [
 ]
 license = "MIT"
 license-files = ['LICENSE']
-requires-python = ">=3.11, <3.15"
+requires-python = ">=3.11"
 dependencies = [
     "attrs>=25.4.0",
     "gunicorn>=23.0.0",

{alpha_python-0.7.4 → alpha_python-0.7.6}/src/alpha/__init__.py

@@ -7,6 +7,7 @@ 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.group import Group
+from alpha.domain.models.permission import Permission
 from alpha.domain.models.role import Role
 from alpha.domain.models.base_model import (
     BaseDomainModel,
@@ -123,6 +124,7 @@ __all__ = [
     "LifeCycleBase",
     "User",
     "Group",
+    "Permission",
     "Role",
     "OIDCConnector",
     "KeyCloakOIDCConnector",

{alpha_python-0.7.4 → alpha_python-0.7.6}/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.4 → alpha_python-0.7.6}/src/alpha/domain/__init__.py

@@ -1,5 +1,6 @@
 from alpha.domain.models.user import User
 from alpha.domain.models.group import Group
+from alpha.domain.models.permission import Permission
 from alpha.domain.models.role import Role
 from alpha.domain.models.base_model import (
     BaseDomainModel,
@@ -17,5 +18,6 @@ __all__ = [
     "LifeCycleBase",
     "User",
     "Group",
+    "Permission",
     "Role",
 ]

{alpha_python-0.7.4 → alpha_python-0.7.6}/src/alpha/domain/models/__init__.py

@@ -1,5 +1,6 @@
 from alpha.domain.models.user import User
 from alpha.domain.models.group import Group
+from alpha.domain.models.permission import Permission
 from alpha.domain.models.role import Role
 from alpha.domain.models.base_model import (
     BaseDomainModel,
@@ -17,5 +18,6 @@ __all__ = [
     "LifeCycleBase",
     "User",
     "Group",
+    "Permission",
     "Role",
 ]

{alpha_python-0.7.4 → alpha_python-0.7.6}/src/alpha/domain/models/group.py

@@ -39,6 +39,20 @@ class Group(LifeCycleBase, BaseDomainModel):
     permissions: list[str] = field(default_factory=list)  # type: ignore
     is_active: bool = True
 
+    def __str__(self) -> str:
+        """Return the name-based representation of the Group instance."""
+        return self.name or ""
+
+    def __repr__(self) -> str:
+        """Return the official string representation of the Group instance."""
+        return (
+            "Group("
+            f"id={self.id!r}, "
+            f"name={self.name!r}, "
+            f"description={self.description!r}"
+            ")"
+        )
+
     def to_dict(self) -> dict[str, Any]:
         """Convert the Group instance to a dictionary.
 
@@ -47,12 +61,38 @@ class Group(LifeCycleBase, BaseDomainModel):
         dict[str, Any]
             A dictionary representation of the Group instance.
         """
+        permissions = cast(
+            list[str | dict[str, Any]],
+            [
+                p.to_dict() if hasattr(p, "to_dict") else p  # type: ignore
+                for p in self.permissions
+            ],
+        )
+        created_at = (
+            self.created_at.isoformat()
+            if hasattr(self, "created_at") and self.created_at is not None
+            else None
+        )
+        modified_at = (
+            self.modified_at.isoformat()
+            if hasattr(self, "modified_at") and self.modified_at is not None
+            else None
+        )
+
         return {
             "id": self.id,
             "name": self.name,
             "description": self.description,
-            "permissions": self.permissions,
+            "permissions": permissions,
             "is_active": self.is_active,
+            "created_by": self.created_by
+            if hasattr(self, "created_by") and self.created_by is not None
+            else None,
+            "created_at": created_at,
+            "modified_by": self.modified_by
+            if hasattr(self, "modified_by") and self.modified_by is not None
+            else None,
+            "modified_at": modified_at,
         }
 
     def update(self, obj: DomainModel) -> DomainModel:

alpha_python-0.7.6/src/alpha/domain/models/permission.py

@@ -0,0 +1,110 @@
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, 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 Permission(LifeCycleBase, BaseDomainModel):
+    """Permission class representing a system permission. This class is used to
+    define and manage permissions. User and group permissions are handled
+    through this class.
+
+    Attributes
+    ----------
+    id
+        Unique identifier for the permission. Can be a UUID, integer, or
+        string.
+    name
+        Name of the permission.
+    description
+        Description for the purpose of the permission.
+    """
+
+    id: UUID | int | str | None = None
+    name: str
+    description: str = ""
+
+    def __str__(self) -> str:
+        """Return the name of the permission.
+
+        Returns
+        -------
+            self.name value
+        """
+        return self.name
+
+    def __repr__(self) -> str:
+        """Return the official string representation of the object.
+
+        Returns
+        -------
+            A string representing the Permission instance.
+        """
+        return (
+            f"Permission(name={self.name!r}, description={self.description!r})"
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the Permission instance to a dictionary.
+
+        Returns
+        -------
+        dict[str, Any]
+            A dictionary representation of the Permission instance.
+        """
+        created_at = (
+            self.created_at.isoformat()
+            if hasattr(self, "created_at") and self.created_at is not None
+            else None
+        )
+        modified_at = (
+            self.modified_at.isoformat()
+            if hasattr(self, "modified_at") and self.modified_at is not None
+            else None
+        )
+
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "created_by": self.created_by
+            if hasattr(self, "created_by") and self.created_by is not None
+            else None,
+            "created_at": created_at,
+            "modified_by": self.modified_by
+            if hasattr(self, "modified_by") and self.modified_by is not None
+            else None,
+            "modified_at": modified_at,
+        }
+
+    def update(self, obj: DomainModel) -> DomainModel:
+        """Update the Permission instance with data from another Permission
+        instance.
+
+        Parameters
+        ----------
+        obj
+            Permission object to update from.
+
+        Returns
+        -------
+        DomainModel
+            The updated instance of the Permission.
+
+        Raises
+        ------
+        TypeError
+            If the provided object is not a Permission instance.
+        """
+        if not isinstance(obj, Permission):
+            raise TypeError("Permission.update expects a Permission instance.")
+
+        self.name = obj.name
+        self.description = obj.description
+        self.modified_at = datetime.now(tz=timezone.utc)
+
+        return cast(DomainModel, self)

{alpha_python-0.7.4 → alpha_python-0.7.6}/src/alpha/domain/models/user.py

@@ -72,6 +72,32 @@ class User(LifeCycleBase, BaseDomainModel):
     is_active: bool = True
     admin: bool = False
 
+    def __str__(self) -> str:
+        """Return the username of the user.
+
+        Returns
+        -------
+            self.username value
+        """
+        return self.username or ""
+
+    def __repr__(self) -> str:
+        """Return the official string representation of the object.
+
+        Returns
+        -------
+            A string representing the User instance.
+        """
+        return (
+            "User("
+            f"id={self.id}, "
+            f"username={self.username!r}, "
+            f"display_name={self.display_name!r}, "
+            f"permissions={self.permissions!r}, "
+            f"groups={self.groups!r}"
+            ")"
+        )
+
     @classmethod
     def from_identity(cls, identity: Identity) -> Self:
         """Create a User instance from an Identity instance.
@@ -101,6 +127,35 @@ class User(LifeCycleBase, BaseDomainModel):
         dict[str, Any]
             A dictionary representation of the User instance.
         """
+        permissions = cast(
+            list[str | dict[str, Any]],
+            [
+                permission.to_dict()  # type: ignore
+                if hasattr(permission, "to_dict")
+                else permission
+                for permission in self.permissions
+            ],
+        )
+        groups = cast(
+            list[str | dict[str, Any]],
+            [
+                group.to_dict()  # type: ignore
+                if hasattr(group, "to_dict")
+                else group
+                for group in self.groups
+            ],
+        )
+        created_at = (
+            self.created_at.isoformat()
+            if hasattr(self, "created_at") and self.created_at is not None
+            else None
+        )
+        modified_at = (
+            self.modified_at.isoformat()
+            if hasattr(self, "modified_at") and self.modified_at is not None
+            else None
+        )
+
         return {
             "id": self.id,
             "username": self.username,
@@ -109,10 +164,18 @@ class User(LifeCycleBase, BaseDomainModel):
             "email": self.email,
             "phone": self.phone,
             "display_name": self.display_name,
-            "permissions": self.permissions,
-            "groups": self.groups,
+            "permissions": permissions,
+            "groups": groups,
             "is_active": self.is_active,
             "admin": self.admin,
+            "created_by": self.created_by
+            if hasattr(self, "created_by") and self.created_by is not None
+            else None,
+            "created_at": created_at,
+            "modified_by": self.modified_by
+            if hasattr(self, "modified_by") and self.modified_by is not None
+            else None,
+            "modified_at": modified_at,
         }
 
     def update(self, obj: DomainModel) -> DomainModel:
@@ -140,4 +203,5 @@ class User(LifeCycleBase, BaseDomainModel):
         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.7.4 → alpha_python-0.7.6}/src/alpha/mixins/jwt_provider.py

@@ -12,6 +12,7 @@ class JWTProviderMixin:
     """
 
     token_factory: TokenFactory | None = None
+    _identity_model: type[Identity] = Identity
 
     def validate(self, token: Token) -> Identity:
         """Validate a token and return the associated identity
@@ -43,7 +44,7 @@ class JWTProviderMixin:
                 "Token payload does not contain mandatory 'subject' field"
             )
 
-        return Identity.from_dict(payload)
+        return self._identity_model.from_dict(payload)
 
     def issue_token(self, identity: Identity) -> Token:
         """Issue a token for the given identity
@@ -57,6 +58,8 @@ class JWTProviderMixin:
         -------
             Token object
         """
+        identity = self._identity_model.from_dict(identity.to_dict())
+
         if not self.token_factory:
             raise exceptions.MissingDependencyException(
                 "Token factory is not configured"

{alpha_python-0.7.4 → alpha_python-0.7.6}/src/alpha/providers/database_provider.py

@@ -18,12 +18,14 @@ class DatabaseProvider(JWTProviderMixin):
 
     protocol = "database"
     token_factory: TokenFactory | None = None
+    _identity_model: type[Identity] = Identity
 
     def __init__(
         self,
         uow: UnitOfWork,
         token_factory: TokenFactory | None = None,
         password_factory: PasswordFactory | None = None,
+        identity_model: type[Identity] = Identity,
         user_name_attribute: str = "username",
         users_repository_name: str = "users",
     ) -> None:
@@ -42,6 +44,9 @@ class DatabaseProvider(JWTProviderMixin):
             Password factory instance to handle password hashing and
             verification, by default None. If None, a default PasswordFactory
             will be used.
+        identity_model
+            Identity model class to use for representing users, by default
+            Identity
         user_name_attribute
             Attribute name to identify the user, by default "username"
         users_repository_name
@@ -52,6 +57,7 @@ class DatabaseProvider(JWTProviderMixin):
         self._password_factory = password_factory or PasswordFactory()
         self._user_name_attribute = user_name_attribute
         self._users_repository_name = users_repository_name
+        self._identity_model = identity_model
 
     def authenticate(self, credentials: PasswordCredentials) -> Identity:
         """Authenticate a user using their credentials.
@@ -73,7 +79,7 @@ class DatabaseProvider(JWTProviderMixin):
                 credentials=credentials, user_repository=users
             )
 
-            return Identity.from_user(user)
+            return self._identity_model.from_user(user)
 
     def get_user(self, subject: str) -> Identity:
         """Retrieve a user by their subject identifier.
@@ -95,7 +101,7 @@ class DatabaseProvider(JWTProviderMixin):
                 username=subject, user_repository=users, attribute_name="id"
             )
 
-            return Identity.from_user(user)
+            return self._identity_model.from_user(user)
 
     def change_password(
         self, credentials: PasswordCredentials, new_password: str

{alpha_python-0.7.4 → alpha_python-0.7.6}/src/alpha/providers/ldap_provider.py

@@ -33,6 +33,7 @@ class LDAPProvider(JWTProviderMixin):
 
     protocol = "ldap"
     token_factory: TokenFactory | None = None
+    _identity_model: type[Identity] = Identity
 
     def __init__(
         self,
@@ -45,8 +46,10 @@ 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,
+        identity_model: type[Identity] = Identity,
         additional_connector_params: dict[str, Any] | None = None,
     ) -> None:
         """Initialize LDAPProvider.
@@ -71,11 +74,17 @@ 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
         change_password_supported
             Whether the provider supports changing passwords, by default False
+        identity_model
+            Identity model class to use for representing users, by default
+            Identity
         additional_connector_params
             Additional parameters to pass to the LDAP connection, by default
             {"receive_timeout": 5}
@@ -89,8 +98,10 @@ 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._identity_model = identity_model
         self._additional_connector_params = additional_connector_params or {
             "receive_timeout": 5
         }
@@ -291,12 +302,13 @@ class LDAPProvider(JWTProviderMixin):
             Identity object
         """
         entry_dict = cast(dict[str, Any], entry.entry_attributes_as_dict)  # type: ignore
-        identity = Identity.from_ldap_dict(
+        identity = self._identity_model.from_ldap_dict(
             entry=entry_dict,
             mappings=self._identity_mappings,
             populate_claims=self._populate_claims,
             populate_groups=self._populate_groups,
             populate_permissions=self._populate_permissions,
+            flatten_claims=self._flatten_claims,
         )
         return identity
 
@@ -324,6 +336,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 +369,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 +389,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.4 → alpha_python-0.7.6}/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
@@ -125,7 +125,7 @@ class Identity:
     username: str | None
     email: str | None
     display_name: str | None
-    groups: Sequence[str | Group]
+    groups: Sequence[str]
     permissions: Sequence[str]
     claims: Mapping[str, Any]
     issued_at: datetime
@@ -160,6 +160,7 @@ class Identity:
         populate_groups: bool = True,
         populate_permissions: bool = False,
         populate_claims: bool = True,
+        flatten_claims: bool = False,
     ) -> Identity:
         """Instantiate an Identity from an LDAP entry dictionary.
 
@@ -178,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
         -------
@@ -188,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,
@@ -204,11 +214,7 @@ 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),
         )
 
@@ -268,13 +274,16 @@ class Identity:
             An Identity instance populated with data from the User object.
         """
         subject = str(user.id) if user.id else user.username
+
         return cls(
             subject=subject,  # type: ignore
             username=user.username,
             email=user.email,
             display_name=user.display_name,
-            groups=user.groups or [],
-            permissions=user.permissions or [],
+            groups=[str(group) for group in user.groups or []],
+            permissions=[
+                str(permission) for permission in user.permissions or []
+            ],
             claims={},
             issued_at=datetime.now(tz=timezone.utc),
             role=user.role,  # type: ignore
@@ -318,10 +327,10 @@ class Identity:
             self.display_name = user.display_name
         for permission in user.permissions or []:
             self.permissions = self._append_on_sequence(
-                self.permissions, permission
+                self.permissions, str(permission)
             )
         for group in user.groups or []:
-            self.groups = self._append_on_sequence(self.groups, group)
+            self.groups = self._append_on_sequence(self.groups, str(group))
         self.role = user.role  # type: ignore
         self.admin = user.admin
 
@@ -337,7 +346,7 @@ class Identity:
         for group in groups:
             for permission in group.permissions or []:
                 self.permissions = self._append_on_sequence(
-                    self.permissions, permission
+                    self.permissions, str(permission)
                 )
 
     def to_dict(self) -> dict[str, Any]:
@@ -430,6 +439,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],