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
- ASGI Middleware -
ForceHTTPSMiddleware(scheme fromX-Forwarded-Proto) andSecurityHeadersMiddleware(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 theappkit-secretsCLI 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 objectsload_configuration()- Load configuration from YAML and environmentsetup_logging()- Initialize logging systemget_secret()- Resolve a secret through the configuredSECRET_PROVIDERSecretProvider- Enum of provider names (local,azure,aws_ssm,macos,windows)
Database
DatabaseConfig- Database connection configurationcreate_session_manager()- Create database session managerBaseEntity- Base class for database entities
Security
hash_password()- Hash passwords with PBKDF2 or scryptverify_password()- Verify password against hashgenerate_token()- Generate secure random tokens
Registry
service_registry- Global service registry instanceServiceRegistry- 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
📚 Related Components
- appkit-user - User authentication and authorization
- appkit-assistant - AI assistant functionality
- appkit-mantine - UI components
- appkit-imagecreator - Image generation workflows
Metadata
Release files for appkit-commons 1.19.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| appkit_commons-1.19.1.tar.gz | 84.6 kB | Without provenance | Details for appkit_commons-1.19.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| appkit_commons-1.19.1-py3-none-any.whl | Python 3 | none | any | Details for appkit_commons-1.19.1-py3-none-any.whl |
Total release size: 141.2 kB
Release files / appkit_commons-1.19.1.tar.gz
| Download URL | appkit_commons-1.19.1.tar.gz |
|---|---|
| Size | 84.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5790dbd049bfbbc4fefd82e068dbd1c0b47788de05e9e4e8106e6d8661707e6b
|
|
BLAKE2b-256 checksum How to use checksums |
c2a995a7336b34aeb61fe33e9de044d02fcb0ade221c8f83e014010d7915ab31
|
| 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.1-py3-none-any.whl
| Download URL | appkit_commons-1.19.1-py3-none-any.whl |
|---|---|
| Size | 56.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d9e6b7c3c2cdb1e825635aa8467e099a773b9538438d19ea32d82b48bcbcbb7c
|
|
BLAKE2b-256 checksum How to use checksums |
90f191005911cf7d1787f1576235df7f3a187622900d41c0404f9daca230ad41
|
| 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.1
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.