Skip to main content

appkit-commons

Python 3.13+ License: MIT

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
  • ASGI Middleware - ForceHTTPSMiddleware (scheme from X-Forwarded-Proto) and SecurityHeadersMiddleware (nosniff, referrer policy, frame-ancestors, HSTS on https)
  • Service Registry - Dependency injection container for managing application services
  • Secret Management - secret: values from env, Azure Key Vault, AWS SSM, the macOS Keychain or the Windows Credential Manager, plus the appkit-secrets CLI for the local stores

🚀 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

Extra Adds
azure Azure Key Vault provider (azure-identity, azure-keyvault-secrets)
aws AWS SSM Parameter Store provider (boto3[crt])
windows Windows Credential Manager provider (pywin32, Windows only)
cli The appkit-secrets command (typer)
uv add "appkit-commons[azure,cli]"

The macOS Keychain provider needs no extra; it uses the built-in security tool.

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

Register and retrieve services:

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"

Secret Providers

secret:<name> values are resolved by the provider in SECRET_PROVIDER. A .env file only needs the provider settings; the cloud providers use your existing az login or aws login session.

SECRET_PROVIDER Store Lookup name with SECRET_NAMESPACE=myapp Without namespace
local (default) Environment / .env name, NAME, NA_ME variants same
macos macOS Keychain account myapp, service name account appkit
windows Windows Credential Manager target myapp:name appkit:name
azure Azure Key Vault myapp-name (lowercased) name
aws_ssm AWS SSM Parameter Store /myapp/name name

Uncomment one block in .env:

# --- macos / windows
SECRET_PROVIDER=macos
SECRET_NAMESPACE=myapp

# --- azure, authenticate with `az login`
#SECRET_PROVIDER=azure
#SECRET_NAMESPACE=myapp
#AZURE_KEY_VAULT_URL=https://<your-vault>.vault.azure.net/

# --- aws_ssm, authenticate with `aws login --profile myapp-dev`
#SECRET_PROVIDER=aws_ssm
#SECRET_NAMESPACE=myapp/dev
#AWS_PROFILE=myapp-dev
#AWS_REGION=eu-central-1   # only needed if the profile sets no region

An unknown SECRET_PROVIDER value raises a ValueError.

appkit-secrets CLI

Manages secrets in the macOS Keychain or the Windows Credential Manager (install the cli extra). The provider defaults to SECRET_PROVIDER when it is macos/windows, otherwise to the current platform; the namespace comes from --namespace or SECRET_NAMESPACE.

appkit-secrets add mn-db-password            # prompts twice, hidden
printf '%s' "$VALUE" | appkit-secrets update mn-db-password --stdin
appkit-secrets list                          # names only
appkit-secrets delete mn-db-password --yes
eval "$(appkit-secrets env)"                 # export all as MN_DB_PASSWORD=... for SECRET_PROVIDER=local
PROFILES=local appkit-secrets check          # every secret: in configuration/ present? exit 1 if not
appkit-secrets check --all-profiles          # config.yaml and every config.*.yaml

Values are never passed on the command line and never printed, except by env.

Shell completion covers commands, --provider, --profiles, the stored names for update/delete/env, and for add the names your configuration needs that are not stored yet. Initialize it in your shell start-up file:

eval "$(appkit-secrets completion zsh)"      # ~/.zshrc, after compinit
eval "$(appkit-secrets completion bash)"     # ~/.bashrc
appkit-secrets completion fish | source      # ~/.config/fish/config.fish
appkit-secrets completion powershell | Out-String | Invoke-Expression   # $PROFILE

Without a shell argument the shell is taken from $SHELL. appkit-secrets --install-completion also works where the shell can be auto-detected.

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
  • get_secret() - Resolve a secret through the configured SECRET_PROVIDER
  • SecretProvider - Enum of provider names (local, azure, aws_ssm, macos, windows)

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

  • Passwords are hashed using industry-standard algorithms (PBKDF2/scrypt)
  • Database credentials support encryption at rest
  • Azure Key Vault and AWS SSM for production, macOS Keychain and Windows Credential Manager for local development
  • 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

Metadata

Release files for appkit-commons 1.19.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for appkit-commons 1.19.0
File Size Uploaded Provenance Actions
appkit_commons-1.19.0.tar.gz 84.6 kB Without provenance Details for appkit_commons-1.19.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for appkit-commons 1.19.0
File Interpreter ABI Platform Actions
appkit_commons-1.19.0-py3-none-any.whl Python 3 none any Details for appkit_commons-1.19.0-py3-none-any.whl

Total release size: 141.2 kB

Release files / appkit_commons-1.19.0.tar.gz

Download URL appkit_commons-1.19.0.tar.gz
Size 84.6 kB
Tags Source
SHA-256 checksum
How to use checksums
6dc83f303abf768449f70040354cdd3fc8b814383c7e1d0c50db818398d1b5c1
BLAKE2b-256 checksum
How to use checksums
02f6a5a47bb7c939d64945b6e2ef14ebc0287e9d794f1b69b06598c762a693df
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / appkit_commons-1.19.0-py3-none-any.whl

Download URL appkit_commons-1.19.0-py3-none-any.whl
Size 56.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
57c59c6d5030dbd6fd78386f00884d834ad53045b657fbf7ae691c739043a4a5
BLAKE2b-256 checksum
How to use checksums
43bad217b1ff9fde490230b103192f5e77b371c03bd9967206587049d3df0829
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for appkit-commons 1.19.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.19.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page