appkit-commons

Shared utilities and infrastructure for AppKit components.

appkit-commons provides the foundational infrastructure used across all AppKit packages, including configuration management, database integration, logging, security utilities, and dependency injection. It serves as the common base layer that enables consistent behavior and shared functionality across the AppKit ecosystem.

✨ Features

Configuration Management - YAML-based configuration with environment variable overrides and secret handling
Database Integration - SQLAlchemy-based ORM with PostgreSQL support, connection pooling, and encryption
Logging Infrastructure - Structured logging with color output and configurable levels
Security Utilities - Password hashing with PBKDF2 and scrypt, secure random generation
Service Registry - Dependency injection container for managing application services
Secret Management - Support for local secrets and Azure Key Vault integration

🚀 Installation

As Part of AppKit Workspace

If you're using the full AppKit workspace:

git clone https://github.com/jenreh/appkit.git
cd appkit
uv sync

Standalone Installation

Install from PyPI:

pip install appkit-commons

Or with uv:

uv add appkit-commons

Optional Dependencies

For Azure Key Vault support:

pip install appkit-commons[azure]
# or
uv add appkit-commons[azure]

Dependencies

colorlog>=6.9.0 (colored logging)
cryptography>=46.0.2 (encryption utilities)
pydantic-settings>=2.10.1 (configuration management)
pyyaml==6.0.2 (YAML configuration)
sqlalchemy-utils==0.42.0 (database utilities)
sqlalchemy==2.0.41 (ORM)

🏁 Quick Start

Basic Configuration

Create a configuration class extending BaseConfig:

from appkit_commons.configuration import BaseConfig


class MyConfig(BaseConfig):
    app_name: str = "MyApp"
    debug: bool = False
    api_key: str = "secret:api_key"  # Will be resolved from secrets

Load configuration from YAML and environment:

from appkit_commons.configuration import load_configuration

config = load_configuration(MyConfig, "config.yaml")
print(f"App: {config.app_name}, Debug: {config.debug}")

Database Setup

Configure database connection:

from appkit_commons.database import DatabaseConfig, create_session_manager

db_config = DatabaseConfig(
    type="postgresql",
    host="localhost",
    port=5432,
    name="myapp",
    username="user",
    password="secret:db_password",
)

session_manager = create_session_manager(db_config)

# Use in your code
with session_manager.session() as session:
    # Your database operations
    pass

Logging Setup

Initialize logging with configuration:

from appkit_commons.configuration import setup_logging

# Setup with default configuration
setup_logging()

# Or with custom config
setup_logging(log_level="DEBUG", log_file="app.log")

📖 Usage

Configuration System

BaseConfig

All configuration classes should inherit from BaseConfig:

from appkit_commons.configuration import BaseConfig


class AppConfig(BaseConfig):
    model_config = {"env_prefix": "MYAPP_"}

    database_url: str = "postgresql://localhost/mydb"
    api_timeout: int = 30
    features: dict[str, bool] = {"new_ui": True}

Secret Resolution

Use secret: prefix for sensitive values:

class SecureConfig(BaseConfig):
    api_key: str = "secret:openai_api_key"  # Resolved from env or Key Vault
    db_password: str = "secret:database_password"

YAML Configuration

Configuration files support nested structures:

# config.yaml
app:
  name: "MyApp"
  database:
    host: "localhost"
    port: 5432
  features:
    - "authentication"
    - "file_upload"

Database Integration

Session Management

Use the session manager for database operations:

from appkit_commons.database import create_session_manager

manager = create_session_manager(db_config)

# Get a session
with manager.session() as session:
    # Perform operations
    result = session.execute(text("SELECT 1"))
    print(result.scalar())

Entity Base Classes

Extend from BaseEntity for common database fields:

from appkit_commons.database import BaseEntity
from sqlalchemy import Column, String


class User(BaseEntity):
    __tablename__ = "users"

    email = Column(String, unique=True, nullable=False)
    name = Column(String, nullable=False)

Security Utilities

Password Hashing

from appkit_commons.security import hash_password, verify_password

# Hash a password
hashed = hash_password("mypassword")

# Verify a password
is_valid = verify_password("mypassword", hashed)

Secure Random Generation

from appkit_commons.security import generate_token

token = generate_token(length=32)

Service Registry

Dependency Injection

from appkit_commons.registry import service_registry

# Register a service
service_registry.register(MyService())

# Retrieve a service
service = service_registry.get(MyService)

🔧 Configuration

Environment Variables

Configuration supports nested environment variables:

export MYAPP_APP__NAME="ProductionApp"
export MYAPP_DATABASE__HOST="prod-db.example.com"
export MYAPP_API__TIMEOUT="60"

Azure Key Vault

For production secrets, configure Azure Key Vault:

from appkit_commons.configuration import configure_azure_key_vault

configure_azure_key_vault(
    vault_url="https://myvault.vault.azure.net/",
    credential=None,  # Uses DefaultAzureCredential
)

Logging Configuration

Customize logging output:

from appkit_commons.configuration import setup_logging

setup_logging(
    level="INFO",
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    file="app.log",
    max_file_size="10 MB",
    backup_count=5,
)

📋 API Reference

Configuration

BaseConfig - Base class for all configuration objects
load_configuration() - Load configuration from YAML and environment
setup_logging() - Initialize logging system
configure_azure_key_vault() - Setup Azure Key Vault integration

Database

DatabaseConfig - Database connection configuration
create_session_manager() - Create database session manager
BaseEntity - Base class for database entities

Security

hash_password() - Hash passwords with PBKDF2 or scrypt
verify_password() - Verify password against hash
generate_token() - Generate secure random tokens

Registry

service_registry - Global service registry instance
ServiceRegistry - Dependency injection container

🔒 Security

[!IMPORTANT] Always use SecretStr for sensitive configuration values and the secret: prefix for automatic resolution from secure sources.

Passwords are hashed using industry-standard algorithms (PBKDF2/scrypt)
Database credentials support encryption at rest
Azure Key Vault integration for production secret management
Secure random generation for tokens and salts

🤝 Integration Examples

With AppKit Components

appkit-commons is automatically integrated into other AppKit packages:

# Configuration is inherited by appkit-user, appkit-assistant, etc.
from appkit_user.configuration import UserConfig

user_config = UserConfig()  # Extends BaseConfig automatically

Custom Application Setup

Complete application bootstrap:

from appkit_commons.configuration import load_configuration, setup_logging
from appkit_commons.database import create_session_manager
from appkit_commons.registry import service_registry

# Load config
config = load_configuration(MyAppConfig, "config.yaml")

# Setup logging
setup_logging(level=config.log_level)

# Setup database
db_manager = create_session_manager(config.database)
service_registry.register(db_manager)

# Your app logic here

📚 Related Components

appkit-user - User authentication and authorization
appkit-assistant - AI assistant functionality
appkit-mantine - UI components
appkit-imagecreator - Image generation workflows

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

appkit_commons-1.14.0.tar.gz (59.8 kB view details)

Uploaded Aug 26, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

appkit_commons-1.14.0-py3-none-any.whl (37.4 kB view details)

Uploaded Aug 26, 2026 Python 3

File details

Details for the file appkit_commons-1.14.0.tar.gz.

File metadata

Download URL: appkit_commons-1.14.0.tar.gz
Upload date: Aug 26, 2026
Size: 59.8 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.6 {"installer":{"name":"uv","version":"0.12.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for appkit_commons-1.14.0.tar.gz
Algorithm	Hash digest
SHA256	`ce2197829a16d5f116a51f912186dbe4e09d1713ed1481312376b92755beb658`
MD5	`ca3ac86c9b990e29c4d74f99c71a68bc`
BLAKE2b-256	`e8751fec67c55020d6769ddc652972eab8e093c8bda74cf7583d9f1b7fbc9d7f`

See more details on using hashes here.

File details

Details for the file appkit_commons-1.14.0-py3-none-any.whl.

File metadata

Download URL: appkit_commons-1.14.0-py3-none-any.whl
Upload date: Aug 26, 2026
Size: 37.4 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.6 {"installer":{"name":"uv","version":"0.12.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for appkit_commons-1.14.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`e586121faa89a8a8b4eaad0e9d3d49932ad1d62b76bee24599ce1e19181b33d2`
MD5	`6b91b6d6f27bd3974645f2e9e7882be3`
BLAKE2b-256	`6662e6987bf3949adbde95eec0ce70bb6b03350eb3046b06bf657f6ecfed7996`