appkit-commons 0.10.0__py3-none-any.whl

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/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/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/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/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/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/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/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/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/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