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

{alpha_python-0.5.1 → alpha_python-0.6.0}/PKG-INFO

@@ -1,16 +1,29 @@
 Metadata-Version: 2.4
 Name: alpha-python
-Version: 0.5.1
+Version: 0.6.0
 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
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/breijling/alpha
+Project-URL: Issues, https://github.com/breijling/alpha/issues
+Project-URL: Documentation, https://alpha-python.readthedocs.io/en/latest/
+Project-URL: Changelog, https://alpha-python.readthedocs.io/en/latest/changelog/
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: attrs>=25.4.0
 Requires-Dist: gunicorn>=23.0.0
 Requires-Dist: jsonpatch>=1.33
 Requires-Dist: numpy>=2.3.5
-Requires-Dist: pandas>=2.3.3
+Requires-Dist: pandas>=1.13
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: pyjwt>=2.10.1
 Requires-Dist: six>=1.17.0
@@ -18,8 +31,10 @@ Requires-Dist: sqlalchemy>=2.0.44
 Requires-Dist: requests>=2.28.1
 Requires-Dist: dependency-injector[yaml]!=4.48.3,<5.0.0,>=4.42.0
 Requires-Dist: argon2-cffi>=25.1.0
+Requires-Dist: httpx
+Requires-Dist: cryptography
 Provides-Extra: api-generator
-Requires-Dist: openapi-generator-cli==7.14.0; (python_version >= "3.11" and python_version < "4.0") and extra == "api-generator"
+Requires-Dist: openapi-generator-cli==7.14.0; extra == "api-generator"
 Requires-Dist: jdk4py; extra == "api-generator"
 Provides-Extra: flask
 Requires-Dist: connexion[swagger-ui]<3,>=2.14.2; extra == "flask"
@@ -40,7 +55,7 @@ Provides-Extra: ldap
 Requires-Dist: ldap3>=2.9.1; extra == "ldap"
 Dynamic: license-file
 
-# alpha
+# 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.
 
@@ -53,7 +68,9 @@ Alpha is intended to be the first dependency you need to add to your Python appl
 
 ## Documentation
 
-TODO: Add documentation link when available.
+[![Documentation Status](https://readthedocs.org/projects/alpha-python/badge/?version=latest)](https://alpha-python.readthedocs.io/en/latest/)
+
+Full documentation is available at [alpha-python.readthedocs.io](https://alpha-python.readthedocs.io/).
 
 ## Installation
 

{alpha_python-0.5.1 → alpha_python-0.6.0}/README.md

@@ -1,4 +1,4 @@
-# alpha
+# 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.
 
@@ -11,7 +11,9 @@ Alpha is intended to be the first dependency you need to add to your Python appl
 
 ## Documentation
 
-TODO: Add documentation link when available.
+[![Documentation Status](https://readthedocs.org/projects/alpha-python/badge/?version=latest)](https://alpha-python.readthedocs.io/en/latest/)
+
+Full documentation is available at [alpha-python.readthedocs.io](https://alpha-python.readthedocs.io/).
 
 ## Installation
 

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

@@ -1,18 +1,30 @@
 [project]
 name = "alpha-python"
-version = "0.5.1"
+version = "0.6.0"
 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 = [
     { name = "Bart Reijling", email = "bart@reijling.eu" }
 ]
-requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+license = "MIT"
+license-files = ['LICENSE']
+requires-python = ">=3.11, <3.15"
 dependencies = [
     "attrs>=25.4.0",
     "gunicorn>=23.0.0",
     "jsonpatch>=1.33",
     "numpy>=2.3.5",
-    "pandas>=2.3.3",
+    "pandas>=1.13",
     "pydantic>=2.12.5",
     "pyjwt>=2.10.1",
     "six>=1.17.0",
@@ -20,8 +32,16 @@ dependencies = [
     "requests>=2.28.1",
     "dependency-injector[yaml]>=4.42.0,<5.0.0,!=4.48.3",
     "argon2-cffi>=25.1.0",
+    "httpx",
+    "cryptography",
 ]
 
+[project.urls]
+Homepage = "https://github.com/breijling/alpha"
+Issues = "https://github.com/breijling/alpha/issues"
+Documentation = "https://alpha-python.readthedocs.io/en/latest/"
+Changelog = "https://alpha-python.readthedocs.io/en/latest/changelog/"
+
 [project.scripts]
 alpha = "alpha.cli:init"
 
@@ -60,11 +80,18 @@ dev = [
     "ipykernel>=7.2.0",
     "flask<2",
     "httpx>=0.28.1",
+    "tox>=4.53.0",
 ]
+# docs = [
+#     "mkdocs-material>=9.5",
+#     "mkdocstrings[python]>=0.29",
+#     "mkdocs-autorefs>=1.0",
+#     "mkdocs-mermaid2-plugin>=1.2.0"
+# ]
 
 [project.optional-dependencies]
 api-generator = [
-    "openapi-generator-cli==7.14.0 ; python_version >= '3.11' and python_version < '4.0'",
+    "openapi-generator-cli==7.14.0",
     "jdk4py"
 ]
 flask = [
@@ -97,6 +124,33 @@ testpaths = [
     "tests"
 ]
 
+[tool.tox]
+legacy_tox_ini = """
+[tox]
+min_version = 4.0
+env_list = py311,py312,py313,py314
+isolated_build = true
+
+[testenv]
+description = Run full test suite on {basepython}
+package = editable
+extras = flask,postgresql,mysql,ldap,api-generator
+deps =
+    pytest>=9.0.1
+    pytest-cov>=7.0.0
+    uv
+commands =
+    pytest {posargs}
+pass_env =
+    GITHUB_ACTIONS
+    TEST_PSQL_HOST
+    TEST_PSQL_PORT
+    TEST_PSQL_USERNAME
+    TEST_PSQL_PASSWORD
+    TEST_PSQL_DATABASE
+"""
+
+
 [tool.coverage.run]
 source = ["src"]
 omit = [
@@ -108,7 +162,7 @@ omit = [
 [tool.black]
 line-length = 79
 skip-string-normalization = true
-target-version = ['py310', 'py311', 'py312', 'py313']
+target-version = ['py311', 'py312', 'py313', 'py314']
 
 [tool.isort]
 py_version = 311

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

@@ -0,0 +1,21 @@
+from alpha.domain.models.user import User
+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",
+]