appkit-commons 0.7.1__tar.gz

appkit_commons-0.7.1/.gitignore

@@ -0,0 +1,114 @@
+__pycache__/
+__pypackages__/
+.cache
+.coverage
+.coverage.*
+.dmypy.json
+.DS_Store
+.eggs/
+.env
+.env.backup
+.env.docker
+.hypothesis/
+.idea/
+.installed.cfg
+.ipynb_checkpoints
+.mypy_cache/
+.nox/
+.pdm.toml
+.pybuilder/
+.pyre/
+.pytest_cache/
+.Python
+.python_packages
+.pytype/
+.ropeproject
+.scrapy
+.spyderproject
+.spyproject
+.states
+.tox/
+.venv
+.venv.mac
+.web
+.webassets-cache
+*.bak
+*.cover
+*.db
+*.egg
+*.egg-info/
+*.kv-env.*
+*.log
+*.manifest
+*.mo
+*.pot
+*.py,cover
+*.py[cod]
+*.sage.py
+*.so
+*.spec
+*.terraform.lock.hcl
+*.tfplan
+*.tfstate
+*.tfstate.*.backup
+*.tfstate.backup
+*.tfvars
+**/.terraform/*
+*$py.class
+/site
+/vectorstore/
+aila-storage/
+assets/external/
+build/
+celerybeat-schedule
+celerybeat.pid
+configuration/config.abaz009.yaml
+configuration/config.bubb001.yaml
+configuration/config.stie104.yaml
+configuration/config.voro047.yaml
+connector examples/sharepoint.json
+cover/
+coverage.xml
+cython_debug/
+db.sqlite3
+db.sqlite3-journal
+develop-eggs/
+dist/
+dmypy.json
+docs/_build/
+Documents/
+downloads/
+eggs/
+env.bak/
+env/
+ENV/
+htmlcov/
+instance/
+ipython_config.py
+knowledge/migrate.py
+lib/
+lib64/
+local_settings.py
+local.settings.json
+MANIFEST
+nosetests.xml
+out
+parts/
+pip-delete-this-directory.txt
+pip-log.txt
+Pipfile
+profile_default/
+sdist/
+share/python-wheels/
+sketchpad/
+sketchpad/
+stores/
+target/
+tests/mcp_test.py
+tmp.txt
+uploaded_files/
+uploads/
+var/
+venv.bak/
+venv/
+wheels/

appkit_commons-0.7.1/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: appkit-commons
+Version: 0.7.1
+Summary: Add your description here
+Author: Jens Rehpöhler
+Requires-Python: >=3.13
+Requires-Dist: colorlog>=6.9.0
+Requires-Dist: cryptography>=46.0.2
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Dist: pyyaml==6.0.2
+Requires-Dist: sqlalchemy-utils==0.42.0
+Requires-Dist: sqlalchemy==2.0.41
+Provides-Extra: azure
+Requires-Dist: azure-identity==1.23.1; extra == 'azure'
+Requires-Dist: azure-keyvault-secrets==4.10.0; extra == 'azure'

appkit_commons-0.7.1/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "appkit-commons"
+version = "0.7.1"
+description = "Add your description here"
+readme = "README.md"
+authors = [{ name = "Jens Rehpöhler" }]
+requires-python = ">=3.13"
+dependencies = [
+    "colorlog>=6.9.0",
+    "cryptography>=46.0.2",
+    "pydantic-settings>=2.10.1",
+    "pyyaml==6.0.2",
+    "sqlalchemy-utils==0.42.0",
+    "sqlalchemy==2.0.41",
+]
+
+[project.optional-dependencies]
+azure = [
+    "azure-identity==1.23.1",
+    "azure-keyvault-secrets==4.10.0",
+]
+
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/appkit_commons"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

appkit_commons-0.7.1/src/appkit_commons/__init__.py

@@ -0,0 +1,11 @@
+from pathlib import Path
+from typing import Final
+
+from dotenv import load_dotenv
+
+# init first to prevent circular dependencies
+BASE_PATH: Final[Path] = Path.cwd()
+CONFIGURATION_PATH: Final[Path] = BASE_PATH / "configuration"
+
+# initialize logging and .env before everything else
+load_dotenv()

appkit_commons-0.7.1/src/appkit_commons/configuration/__init__.py

@@ -0,0 +1,54 @@
+import importlib
+from typing import Any
+
+from appkit_commons.configuration.base import BaseConfig
+from appkit_commons.configuration.secret_provider import (
+    SecretNotFoundError,
+    SecretProvider,
+    get_secret,
+)
+from appkit_commons.configuration.yaml import (
+    YamlConfigReader,
+    YamlConfigSettingsSource,
+)
+# Remove this direct import that causes the circular dependency
+# from appkit_commons.configuration.logging import init_logging
+
+__all__ = [
+    "ApplicationConfig",
+    "BaseConfig",
+    "Configuration",
+    "DatabaseConfig",
+    "Protocol",
+    "SecretNotFoundError",
+    "SecretProvider",
+    "ServerConfig",
+    "WorkerConfig",
+    "YamlConfigReader",
+    "YamlConfigSettingsSource",
+    "get_secret",
+    "init_logging",
+]
+
+# Keep backward compatibility if someone used the wrong name
+__ALL__ = __all__
+
+_lazy_map: dict[str, str] = {
+    "Configuration": "appkit_commons.configuration.configuration",
+    "ApplicationConfig": "appkit_commons.configuration.configuration",
+    "DatabaseConfig": "appkit_commons.configuration.configuration",
+    "ServerConfig": "appkit_commons.configuration.configuration",
+    "WorkerConfig": "appkit_commons.configuration.configuration",
+    "Protocol": "appkit_commons.configuration.configuration",
+    "init_logging": "appkit_commons.configuration.logging",
+}
+
+
+def __getattr__(name: str) -> Any:
+    module_path = _lazy_map.get(name)
+    if module_path is None:
+        raise AttributeError(
+            f"module 'appkit_commons.configuration' has no attribute {name!r}"
+        )
+    module = importlib.import_module(module_path)
+    return getattr(module, name)

appkit_commons-0.7.1/src/appkit_commons/configuration/base.py

@@ -0,0 +1,70 @@
+import logging
+import os
+from collections.abc import Callable
+from typing import Any
+
+from pydantic import model_validator
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+)
+
+from appkit_commons.configuration.secret_provider import SECRET, get_secret
+from appkit_commons.configuration.yaml import YamlConfigSettingsSource
+
+logger = logging.getLogger(__name__)
+
+
+def _starts_with_secret(s: str) -> bool:
+    return s.lower().startswith(SECRET)
+
+
+def _replace_value_if_secret(
+    key: str, value: Any, secret_function: Callable[[str], str]
+) -> Any:
+    if not isinstance(value, str):
+        return value
+
+    value = str(value)
+    if not _starts_with_secret(value):
+        return value
+
+    # remove SECRET from value
+    # 1. secret:mysecret -> mysecret
+    secret_len = len(SECRET)
+    value = value[secret_len:]
+    key = value if len(value) > 0 else key
+    return secret_function(key)
+
+
+class BaseConfig(BaseSettings):
+    model_config = SettingsConfigDict(extra="ignore", env_nested_delimiter="__")
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        profiles: list[str] = [
+            profile.strip() for profile in os.getenv("PROFILES", "").split(",")
+        ]
+
+        return (
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            file_secret_settings,
+            YamlConfigSettingsSource(settings_cls, profiles=profiles),
+        )
+
+    @model_validator(mode="before")
+    @classmethod
+    def secret_update(cls, values: dict[str, Any]) -> dict[str, Any]:
+        return {
+            k: _replace_value_if_secret(k, v, get_secret) for k, v in values.items()
+        }

appkit_commons-0.7.1/src/appkit_commons/configuration/configuration.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Generic, TypeVar
+
+from pydantic import Field
+
+from appkit_commons.configuration.base import BaseConfig
+from appkit_commons.database.configuration import DatabaseConfig
+
+
+class ConfigurationError(ValueError):
+    pass
+
+
+class Environment(StrEnum):
+    development = "dev"
+    production = ""
+    testing = "test"
+    staging = "stage"
+    docker = "container"
+    local = "local"
+    ci = "ci"
+
+
+class WorkerConfig(StrEnum):
+    multiprocessing = "multiprocessing"
+    webconcurrency = "webconcurrency"
+
+
+class Protocol(StrEnum):
+    http = "http"
+    https = "https"
+
+
+class ServerConfig(BaseConfig):
+    host: str
+    port: int
+    docker_port: int
+    protocol: Protocol = Protocol.http
+    reload: bool = False
+    workers: int | WorkerConfig = WorkerConfig.webconcurrency
+
+
+class ReflexConfig(BaseConfig):
+    deploy_url: str
+    frontend_port: int = 80
+    backend_port: int = 3030
+    workers: int = 3
+    default_timeout: int = 300  # seconds
+    backend_timeout: int = 180  # seconds
+    single_port: bool = False
+
+
+class ApplicationConfig(BaseConfig):
+    version: str
+    name: str
+    logging: str
+    environment: Environment | None = Environment.local
+    database: DatabaseConfig | None = Field(..., alias="database")
+
+
+T = TypeVar("T", bound=ApplicationConfig)
+
+
+class Configuration(BaseConfig, Generic[T]):  # noqa: UP046
+    profile: str
+    server: ServerConfig | None = Field(default=None, alias="server")
+    reflex: ReflexConfig | None = Field(default=None, alias="reflex")
+    app: T

appkit_commons-0.7.1/src/appkit_commons/configuration/logging.py

@@ -0,0 +1,25 @@
+import logging.config
+from pathlib import Path
+
+import yaml
+
+from appkit_commons import CONFIGURATION_PATH
+from appkit_commons.configuration.configuration import Configuration
+
+logger = logging.getLogger(__name__)
+
+
+def init_logging(configuration: Configuration) -> None:
+    # check if profile based logging configuration exists
+    log_configuration = configuration.app.logging
+    if CONFIGURATION_PATH.joinpath(log_configuration).exists():
+        logger.info(
+            "Using logging configuration: \x1b[31;1m%s\x1b[0m", log_configuration
+        )
+        with Path.open(
+            CONFIGURATION_PATH / log_configuration, "rt", encoding="utf-8"
+        ) as f:
+            config = yaml.safe_load(f.read())
+        logging.config.dictConfig(config)
+    else:
+        logger.info("Using logging configuration: \x1b[31;1mlogging.conf\x1b[0m")

appkit_commons-0.7.1/src/appkit_commons/configuration/secret_provider.py

@@ -0,0 +1,95 @@
+import os
+from enum import StrEnum
+from functools import lru_cache
+from typing import Final
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+SECRET_PROVIDER: Final[str] = os.getenv("SECRET_PROVIDER", "local").lower()
+SECRET: Final[str] = "secret:"  # noqa: S105
+
+
+class SecretNotFoundError(Exception):
+    pass
+
+
+class SecretProvider(StrEnum):
+    AZURE = "azure"
+    LOCAL = "local"
+
+
+@lru_cache(maxsize=1)
+def _get_azure_client():
+    try:
+        from azure.identity import (  # type: ignore # noqa: PLC0415
+            DefaultAzureCredential,
+        )
+        from azure.keyvault.secrets import SecretClient  # type: ignore # noqa: PLC0415
+    except ImportError as exc:
+        raise ImportError(
+            "Optional Azure dependencies are required to use SecretProvider.AZURE. "
+            "Install 'azure-identity' and 'azure-keyvault-secrets'."
+        ) from exc
+
+    vault_url = os.environ.get("AZURE_KEY_VAULT_URL")
+    if not vault_url:
+        raise RuntimeError(
+            "Environment variable 'AZURE_KEY_VAULT_URL' must be set to use "
+            "SecretProvider.AZURE"
+        )
+    credential = DefaultAzureCredential()
+    return SecretClient(vault_url=vault_url, credential=credential)
+
+
+def _get_secret_from_azure(key: str) -> str:
+    client = _get_azure_client()
+    secret = client.get_secret(key.lower())
+    if not secret.value:
+        raise SecretNotFoundError(f"Secret '{key}' not found in Azure Key Vault")
+    return secret.value
+
+
+def _get_secret_from_env(key: str) -> str:
+    """
+    Get secret from environment variables.
+
+    This function supports multiple naming conventions:
+    - Direct key lookup: key -> env[key]
+    - Uppercase transformation: key -> env[key.upper()]
+    - Dash-to-underscore: avui-db-user -> AVUI_DB_USER
+    """
+    # Try direct lookup first
+    value = os.getenv(key)
+    if value:
+        return value
+
+    # Try uppercase
+    value = os.getenv(key.upper())
+    if value:
+        return value
+
+    # Try dash-to-underscore + uppercase transformation
+    transformed_key = key.replace("-", "_").upper()
+    value = os.getenv(transformed_key)
+    if value:
+        return value
+
+    # Try dash-to-underscore + lowercase transformation
+    value = os.getenv(transformed_key.lower())
+    if value:
+        return value
+
+    error_msg = (
+        f"Secret '{key}' not found in environment variables. "
+        f"Tried: {key}, {key.upper()}, {transformed_key}, {transformed_key.lower()}"
+    )
+    raise SecretNotFoundError(error_msg)
+
+
+def get_secret(key: str) -> str:
+    if SECRET_PROVIDER == SecretProvider.AZURE:
+        return _get_secret_from_azure(key)
+    return _get_secret_from_env(key)

appkit_commons-0.7.1/src/appkit_commons/configuration/yaml.py

@@ -0,0 +1,160 @@
+import logging
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic_settings import BaseSettings, InitSettingsSource
+
+PROJECT_ROOT = Path.cwd()
+DEFAULT_PATH: Path = PROJECT_ROOT / "configuration"
+DEFAULT_CONFIG_YAML: Path = Path("config.yaml")
+
+logger = logging.getLogger(__name__)
+
+
+class YamlConfigReader:
+    def __init__(
+        self,
+        yaml_file_path: Path = DEFAULT_PATH,
+        yaml_file: Path = DEFAULT_CONFIG_YAML,
+        yaml_file_encoding: str = "utf-8",
+    ):
+        self.yaml_file_path = yaml_file_path
+        self.yaml_file = yaml_file
+        self.yaml_file_encoding = yaml_file_encoding
+        self.yaml_file_prefix = yaml_file.stem
+        self.yaml_file_suffix = yaml_file.suffix
+
+    @classmethod
+    def __merge(cls, master: dict, updates: dict) -> dict:
+        """
+        Deep merge two dictionaries
+        """
+        # Safety check for None values
+        if updates is None:
+            return master
+        if master is None:
+            return updates if updates is not None else {}
+
+        for key in updates:  # noqa
+            if (
+                key in master
+                and isinstance(master[key], dict)
+                and isinstance(updates[key], dict)
+            ):
+                cls.__merge(master[key], updates[key])
+            else:
+                master[key] = updates[key]
+
+        return master
+
+    @classmethod
+    @lru_cache
+    def read_file(cls, file_path: Path, encoding: str = "utf-8") -> Any:
+        try:
+            with Path.open(file_path, "r", encoding=encoding) as file:
+                result = yaml.safe_load(file)
+                # Handle case where YAML file is empty or contains only comments
+                return result if result is not None else {}
+        except yaml.YAMLError as ex:
+            raise ex
+        except FileNotFoundError:
+            logger.warning("Configuration file '%s' not found.", file_path)
+            return {}
+
+    def read_and_merge_files(self, profiles: list[str] | None) -> dict[str, Any]:
+        base_config: dict = self.read_file(
+            self.yaml_file_path / self.yaml_file, self.yaml_file_encoding
+        )
+
+        if profiles is None:
+            return base_config
+
+        # Load profiles
+        merged_config = base_config
+        for environment in profiles:
+            merge_config = (
+                self.yaml_file_path
+                / f"{self.yaml_file_prefix}.{environment}{self.yaml_file_suffix}"
+            )
+            updates: dict = self.read_file(merge_config, self.yaml_file_encoding)
+            merged_config = self.__merge(master=merged_config, updates=updates)
+
+        return merged_config
+
+
+class YamlConfigSettingsSource(InitSettingsSource):
+    """This class is designed to load variables from a YAML file with inheritance.
+
+    The YAML file is loaded from the path specified in the `yaml_file_path` attribute.
+    By default, the configuration file should be named "config.yaml" and located in the
+    specified path. The default directory where `config.yaml` files are stored is
+    `configuration` in the project root.
+
+    To extend or override the configuration, you can set e.g. a `PROFILES` environment
+    variable. Additional YAML files should follow the naming convention
+    `config.{profile}.yaml` and be stored in the same directory as the default
+    configuration.
+
+    **Important Note:** The order in which profiles are specified in the `profiles` list
+    matters. Profile files will be loaded and merged in the order
+    they are listed. E.g. if `profiles` is set to `dev,prod`, the `dev` profile will be
+    loaded first after the default config, and the `prod` profile will be loaded second,
+    with the `prod` profile overriding any values from the `default`and `dev` profile.
+
+    When setting the `yaml_file` attribute, the class will search for profiles by
+    splitting the file name and using the first part as the prefix. For instance, if
+    `yaml_file` is set to `my_config.yaml`, the class will look for profiles in files
+    named `my_config.{profile}.yaml`.
+
+    Usage:
+    ```python
+    class BaseConfig(BaseSettings):
+        model_config = SettingsConfigDict(extra="ignore", env_nested_delimiter="__")
+
+        @classmethod
+        def settings_customise_sources(
+            cls,
+            settings_cls: Type[BaseSettings],
+            init_settings: PydanticBaseSettingsSource,
+            env_settings: PydanticBaseSettingsSource,
+            dotenv_settings: PydanticBaseSettingsSource,
+            file_secret_settings: PydanticBaseSettingsSource,
+        ) -> Tuple[PydanticBaseSettingsSource, ...]:
+            profiles: List[str] = [
+                profile.strip() for profile in os.getenv("PROFILES", "").split(",")
+            ]
+
+            return (
+                init_settings,
+                env_settings,
+                dotenv_settings,
+                file_secret_settings,
+                YamlConfigSettingsSource(settings_cls, profiles=profiles),
+            )
+    ```
+    """
+
+    def __init__(
+        self,
+        settings_cls: type[BaseSettings],
+        profiles: list[str] | None = None,
+        yaml_file_path: Path = DEFAULT_PATH,
+        yaml_file: Path = DEFAULT_CONFIG_YAML,
+        yaml_file_encoding: str = "utf-8",
+    ):
+        reader = YamlConfigReader(
+            yaml_file_path=yaml_file_path,
+            yaml_file=yaml_file,
+            yaml_file_encoding=yaml_file_encoding,
+        )
+        self.yaml_data = reader.read_and_merge_files(profiles=profiles)
+        # Filter out YAML entries with no matching Pydantic field
+        valid_yaml_data = {
+            k: v for k, v in self.yaml_data.items() if k in settings_cls.__fields__
+        }
+        super().__init__(settings_cls, valid_yaml_data)
+
+    def __repr__(self) -> str:
+        return f"YamlConfigSettingsSource(yaml_data={self.yaml_data!r})"

appkit_commons-0.7.1/src/appkit_commons/database/configuration.py

@@ -0,0 +1,46 @@
+from urllib.parse import quote
+
+from pydantic import SecretStr, computed_field
+from pydantic_settings import SettingsConfigDict
+
+from appkit_commons.configuration.base import BaseConfig
+
+
+class DatabaseConfig(BaseConfig):
+    model_config = SettingsConfigDict(env_prefix="app_database_", env_file=".env")
+
+    type: str = "postgresql"
+    username: str = "postgres"
+    password: SecretStr = SecretStr("postgres")
+    host: str = "localhost"
+    port: int = 5432
+    name: str = "postgres"
+    encryption_key: SecretStr = SecretStr("")
+    pool_size: int = 10
+    max_overflow: int = 30
+    echo: bool = False
+    testing: bool = False
+    # SSL mode: disable, allow, prefer, require, verify-ca, verify-full
+    ssl_mode: str = "disable"
+
+    @computed_field(repr=False)  # type: ignore
+    @property
+    def url(self) -> str:
+        if self.type == "sqlite":
+            return f"sqlite:///{self.name}"
+
+        if self.type == "postgresql":
+            # URL encode the password to handle special characters
+            encoded_password = quote(self.password.get_secret_value(), safe="")
+            base_url = (
+                f"postgresql+psycopg://{self.username}:{encoded_password}"
+                f"@{self.host}:{self.port}/{self.name}"
+            )
+
+            # Add SSL parameters if specified
+            if self.ssl_mode != "disable":
+                base_url += f"?sslmode={self.ssl_mode}"
+
+            return base_url
+
+        raise ValueError(f"Unsupported database type: {self.type}")

appkit_commons-0.7.1/src/appkit_commons/database/entities.py

@@ -0,0 +1,63 @@
+import datetime
+
+from cryptography.fernet import Fernet
+from sqlalchemy import (
+    DateTime,
+    Dialect,
+    String,
+    TypeDecorator,
+)
+from sqlalchemy.orm import (
+    DeclarativeBase,
+    Mapped,
+    mapped_column,
+)
+from sqlalchemy.sql import func
+
+from appkit_commons.database.configuration import DatabaseConfig
+from appkit_commons.registry import service_registry
+
+
+def get_cipher_key() -> str:
+    """Get cipher key from database config, with lazy initialization."""
+    return service_registry().get(DatabaseConfig).encryption_key.get_secret_value()
+
+
+class EncryptedString(TypeDecorator):
+    impl = String
+    cache_ok = True  # Added to allow caching of the custom type
+
+    def __init__(self, *args: any, **kwargs: any):
+        super().__init__(*args, **kwargs)
+        self.cipher_key = get_cipher_key()
+        self.cipher = Fernet(self.cipher_key)
+
+    def process_bind_param(self, value: any, dialect: Dialect) -> str | None:  # noqa: ARG002
+        if value is not None:
+            return self.cipher.encrypt(value.encode()).decode()
+        return value
+
+    def process_result_value(self, value: any, dialect: Dialect) -> str | None:  # noqa: ARG002
+        if value is not None:
+            return self.cipher.decrypt(value.encode()).decode()
+        return value
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Entity:  # mixin class with default columns
+    id: Mapped[int] = mapped_column(primary_key=True, index=True, autoincrement=True)
+
+    created: Mapped[datetime.datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        nullable=False,
+    )
+    updated: Mapped[datetime.datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )

appkit_commons-0.7.1/src/appkit_commons/database/session.py

@@ -0,0 +1,78 @@
+import contextlib
+import logging
+from collections.abc import AsyncGenerator, Iterator
+from functools import lru_cache
+from typing import Any
+
+from sqlalchemy import Engine
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import Session
+
+from appkit_commons.database.configuration import DatabaseConfig
+from appkit_commons.database.sessionmanager import (
+    AsyncSessionManager,
+    SessionManager,
+)
+from appkit_commons.registry import service_registry
+
+logger = logging.getLogger(__name__)
+
+
+def _get_db_config() -> DatabaseConfig:
+    """Get database configuration from registry."""
+    db_config = service_registry().get(DatabaseConfig)
+    if db_config is None:
+        logger.error("DatabaseConfig not found in registry")
+        raise RuntimeError("DatabaseConfig not initialized in registry")
+    return db_config
+
+
+def _get_engine_kwargs() -> dict[str, Any]:
+    """Get engine configuration kwargs."""
+    db_config = _get_db_config()
+
+    if db_config.type == "postgres":
+        return {
+            "pool_size": db_config.pool_size,
+            "max_overflow": db_config.max_overflow,
+            "echo": db_config.echo,
+        }
+
+    return {}
+
+
+# if app_config.testing:
+#     _engine_kwargs["poolclass"] = NullPool  # type: ignore
+#     _engine_kwargs["echo"] = app_config.database.echo
+#     _engine_kwargs.pop("pool_size")
+#     _engine_kwargs.pop("max_overflow")
+
+
+# Create a database engine
+@lru_cache(maxsize=1)
+def get_async_session_manager() -> AsyncSessionManager:
+    db_config = _get_db_config()
+    engine_kwargs = _get_engine_kwargs()
+    return AsyncSessionManager(db_config.url, **engine_kwargs)
+
+
+@lru_cache(maxsize=1)
+def get_session_manager() -> SessionManager:
+    db_config = _get_db_config()
+    engine_kwargs = _get_engine_kwargs()
+    return SessionManager(db_config.url, **engine_kwargs)
+
+
+@contextlib.asynccontextmanager
+async def get_asyncdb_session() -> AsyncGenerator[AsyncSession, None]:
+    async with get_async_session_manager().session() as session:
+        yield session
+
+
+def get_db_session() -> Iterator[Session]:
+    with get_session_manager().session() as session:
+        yield session
+
+
+def get_db_engine() -> Engine:
+    return get_session_manager().get_engine()  # type: ignore

appkit_commons-0.7.1/src/appkit_commons/database/sessionmanager.py

@@ -0,0 +1,52 @@
+import contextlib
+from collections.abc import AsyncIterator, Iterator
+from contextlib import contextmanager
+from typing import Any
+
+from sqlalchemy import create_engine
+from sqlalchemy.ext.asyncio import (
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.orm import Session, sessionmaker
+
+
+class AsyncSessionManager:
+    def __init__(self, host: str, engine_kwargs: dict[str, Any] | None = None):
+        self._engine = create_async_engine(host, **(engine_kwargs or {}))
+        self._sessionmaker = async_sessionmaker(bind=self._engine)
+
+    async def close(self) -> None:
+        if self._engine:
+            await self._engine.dispose()
+
+    @contextlib.asynccontextmanager
+    async def session(self) -> AsyncIterator[AsyncSession]:
+        async with self._sessionmaker() as session:
+            try:
+                yield session
+                await session.commit()
+            except Exception:
+                await session.rollback()
+                raise
+
+
+class SessionManager:
+    def __init__(self, host: str, engine_kwargs: dict[str, Any] | None = None):
+        self._engine = create_engine(host, **(engine_kwargs or {}))
+        self._sessionmaker = sessionmaker(bind=self._engine)
+
+    def close(self) -> None:
+        if self._engine:
+            self._engine.dispose()
+
+    @contextmanager
+    def session(self) -> Iterator[Session]:
+        with self._sessionmaker() as session:
+            try:
+                yield session
+                session.commit()
+            except Exception:
+                session.rollback()
+                raise

appkit_commons-0.7.1/src/appkit_commons/registry.py

@@ -0,0 +1,188 @@
+import logging
+from functools import lru_cache
+from typing import TYPE_CHECKING, Any, TypeVar, cast
+
+if TYPE_CHECKING:
+    from appkit_commons.configuration.configuration import (
+        ApplicationConfig,
+        Configuration,
+    )
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+ConfigT = TypeVar("ConfigT", bound="ApplicationConfig")
+
+
+class ServiceRegistry:
+    """Registry for storing and retrieving initialized instances by their class type."""
+
+    def __init__(self) -> None:
+        self._instances: dict[type[Any], Any] = {}
+
+    def _register_config_recursively(  # noqa: PLR0912
+        self, obj: Any, visited: set[int] | None = None
+    ) -> None:
+        """Recursively register configuration objects and their attributes."""
+        if visited is None:
+            visited = set()
+
+        # Avoid infinite recursion by tracking visited objects
+        obj_id = id(obj)
+        if obj_id in visited:
+            return
+        visited.add(obj_id)
+
+        # Use __dict__ to get instance attributes directly
+        if hasattr(obj, "__dict__"):
+            for attr_name, attr_value in obj.__dict__.items():
+                # Skip private attributes and None values
+                if attr_name.startswith("_") or attr_value is None:
+                    continue
+
+                try:
+                    # Check if this is a configuration object (not a basic type)
+                    if hasattr(attr_value, "__class__"):
+                        attr_class = attr_value.__class__
+
+                        # Skip built-in types, pydantic types, and already registered
+                        if (
+                            attr_class.__module__ != "builtins"
+                            and attr_class.__name__ not in ("SecretStr", "StrEnum")
+                            and not self.has(attr_class)
+                        ):
+                            self.register_as(attr_class, attr_value)
+                            logger.debug(
+                                "Registered service configuration: %s from attribute %s",  # noqa: E501
+                                attr_class.__name__,
+                                attr_name,
+                            )
+
+                            # Recursively register nested configurations
+                            self._register_config_recursively(attr_value, visited)
+
+                except Exception as e:
+                    logger.warning(
+                        "Failed to process attribute %s: %s", attr_name, str(e)
+                    )
+
+        # Also check class annotations to handle properties/descriptors
+        if hasattr(obj.__class__, "__annotations__"):
+            for attr_name in obj.__class__.__annotations__:
+                if attr_name.startswith("_"):
+                    continue
+
+                try:
+                    attr_value = getattr(obj, attr_name, None)
+                    if attr_value is not None and hasattr(attr_value, "__class__"):
+                        attr_class = attr_value.__class__
+
+                        if (
+                            attr_class.__module__ != "builtins"
+                            and attr_class.__name__ not in ("SecretStr", "StrEnum")
+                            and not self.has(attr_class)
+                        ):
+                            self.register_as(attr_class, attr_value)
+                            logger.debug(
+                                "Registered service configuration: %s from annotated attribute %s",  # noqa: E501
+                                attr_class.__name__,
+                                attr_name,
+                            )
+
+                            # Recursively register nested configurations
+                            self._register_config_recursively(attr_value, visited)
+
+                except Exception as e:
+                    logger.warning(
+                        "Failed to access annotated attribute %s: %s", attr_name, str(e)
+                    )
+
+    def configure(
+        self, app_config_class: type[ConfigT], env_file: str = ".env"
+    ) -> "Configuration[ConfigT]":
+        """Configure and register the application configuration."""
+        from appkit_commons.configuration.configuration import (  # noqa: PLC0415
+            Configuration,
+        )
+
+        logger.debug(
+            "Configuring application with config class: %s", app_config_class.__name__
+        )
+
+        # Create the configuration instance
+        configuration = Configuration[app_config_class](_env_file=env_file)
+
+        # Register the configuration instance
+        self.register_as(Configuration, configuration)
+        self._register_config_recursively(configuration)
+
+        logger.info("Application configuration initialized and registered")
+        logger.info("Total registered instances: %d", len(self._instances))
+        for registered_type in self.list_registered():
+            logger.debug("Registered: %s", registered_type.__name__)
+
+        return configuration
+
+    def register(self, instance: object) -> None:
+        """Register an initialized instance using its class type as the key."""
+        instance_type = type(instance)
+
+        if instance_type in self._instances:
+            logger.warning(
+                "Overwriting existing instance of type: %s", instance_type.__name__
+            )
+
+        self._instances[instance_type] = instance
+        logger.debug("Registered instance of type %s", instance_type.__name__)
+
+    def register_as(self, instance_type: type[T], instance: T) -> None:
+        """Register an initialized instance with a specific type as the key."""
+        if instance_type in self._instances:
+            logger.warning(
+                "Overwriting existing instance of type: %s", instance_type.__name__
+            )
+
+        self._instances[instance_type] = instance
+        logger.debug("Registered instance as type %s", instance_type.__name__)
+
+    def get(self, instance_type: type[T]) -> T:
+        """Retrieve an instance by its class type, returning None if not found."""
+        instance: type[T] | None = self._instances.get(instance_type)
+        if instance is None:
+            logger.error(
+                "Instance of type %s not found in registry", instance_type.__name__
+            )
+            raise KeyError(
+                f"Instance of type {instance_type.__name__} not found in registry"
+            )
+        return cast(T, instance)
+
+    def unregister(self, instance_type: type[T]) -> None:
+        """Remove an instance from the registry by its class type."""
+        if instance_type in self._instances:
+            del self._instances[instance_type]
+            logger.debug("Unregistered instance of type: %s", instance_type.__name__)
+        else:
+            logger.warning(
+                "Attempted to unregister non-existent type: %s", instance_type.__name__
+            )
+
+    def list_registered(self) -> list[type[Any]]:
+        """Get a list of all registered class types."""
+        return list(self._instances.keys())
+
+    def has(self, instance_type: type[T]) -> bool:
+        """Check if an instance is registered for the given class type."""
+        return instance_type in self._instances
+
+    def clear(self) -> None:
+        """Clear all registered instances."""
+        count = len(self._instances)
+        self._instances.clear()
+        logger.debug("Cleared %d instances from registry", count)
+
+
+@lru_cache(maxsize=1)
+def service_registry() -> ServiceRegistry:
+    logger.debug("Creating the service registry instance")
+    return ServiceRegistry()

appkit_commons-0.7.1/src/appkit_commons/security.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+
+SALT_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+DEFAULT_PBKDF2_ITERATIONS = 1_000_000
+
+
+def _gen_salt(length: int) -> str:
+    """Generate a random string of SALT_CHARS with specified ``length``."""
+    if length <= 0:
+        raise ValueError("Salt length must be at least 1.")
+
+    return "".join(secrets.choice(SALT_CHARS) for _ in range(length))
+
+
+def _hash_internal(method: str, salt: str, password: str) -> tuple[str, str]:
+    method, *args = method.split(":")
+    salt_bytes = salt.encode()
+    password_bytes = password.encode()
+
+    if method == "scrypt":
+        if not args:
+            n = 2**15
+            r = 8
+            p = 1
+        else:
+            try:
+                n, r, p = map(int, args)
+            except ValueError:
+                raise ValueError("'scrypt' takes 3 arguments.") from None
+
+        maxmem = 132 * n * r * p  # ideally 128, but some extra seems needed
+        return (
+            hashlib.scrypt(
+                password_bytes, salt=salt_bytes, n=n, r=r, p=p, maxmem=maxmem
+            ).hex(),
+            f"scrypt:{n}:{r}:{p}",
+        )
+    if method == "pbkdf2":
+        len_args = len(args)
+
+        if len_args == 0:
+            hash_name = "sha256"
+            iterations = DEFAULT_PBKDF2_ITERATIONS
+        elif len_args == 1:
+            hash_name = args[0]
+            iterations = DEFAULT_PBKDF2_ITERATIONS
+        elif len_args == 2:  # noqa: PLR2004
+            hash_name = args[0]
+            iterations = int(args[1])
+        else:
+            raise ValueError("'pbkdf2' takes 2 arguments.")
+
+        return (
+            hashlib.pbkdf2_hmac(
+                hash_name, password_bytes, salt_bytes, iterations
+            ).hex(),
+            f"pbkdf2:{hash_name}:{iterations}",
+        )
+    raise ValueError(f"Invalid hash method '{method}'.")
+
+
+def generate_password_hash(
+    password: str, method: str = "scrypt", salt_length: int = 16
+) -> str:
+    """Securely hash a password for storage. A password can be compared to a stored hash
+    using :func:`check_password_hash`.
+
+    The following methods are supported:
+
+    -   ``scrypt``, the default. The parameters are ``n``, ``r``, and ``p``, the default
+        is ``scrypt:32768:8:1``. See :func:`hashlib.scrypt`.
+    -   ``pbkdf2``, less secure. The parameters are ``hash_method`` and ``iterations``,
+        the default is ``pbkdf2:sha256:600000``. See :func:`hashlib.pbkdf2_hmac`.
+
+    Default parameters may be updated to reflect current guidelines, and methods may be
+    deprecated and removed if they are no longer considered secure. To migrate old
+    hashes, you may generate a new hash when checking an old hash, or you may contact
+    users with a link to reset their password.
+
+    :param password: The plaintext password.
+    :param method: The key derivation function and parameters.
+    :param salt_length: The number of characters to generate for the salt.
+
+    .. versionchanged:: 3.1
+        The default iterations for pbkdf2 was increased to 1,000,000.
+    """
+    salt = _gen_salt(salt_length)
+    h, actual_method = _hash_internal(method, salt, password)
+    return f"{actual_method}${salt}${h}"
+
+
+def check_password_hash(pwhash: str, password: str) -> bool:
+    """Securely check that the given stored password hash, previously generated using
+    :func:`generate_password_hash`, matches the given password.
+
+    Methods may be deprecated and removed if they are no longer considered secure. To
+    migrate old hashes, you may generate a new hash when checking an old hash, or you
+    may contact users with a link to reset their password.
+
+    :param pwhash: The hashed password.
+    :param password: The plaintext password.
+    """
+    try:
+        method, salt, hashval = pwhash.split("$", 2)
+    except ValueError:
+        return False
+
+    return hmac.compare_digest(_hash_internal(method, salt, password)[0], hashval)