appkit-commons 0.7.1__tar.gz → 0.13.0__tar.gz

appkit_commons-0.13.0/PKG-INFO

@@ -0,0 +1,406 @@
+Metadata-Version: 2.4
+Name: appkit-commons
+Version: 0.13.0
+Summary: Add your description here
+Project-URL: Homepage, https://github.com/jenreh/appkit
+Project-URL: Documentation, https://github.com/jenreh/appkit/tree/main/docs
+Project-URL: Repository, https://github.com/jenreh/appkit
+Project-URL: Issues, https://github.com/jenreh/appkit/issues
+Author: Jens Rehpöhler
+Keywords: components,mantine,reflex,ui,web
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: User Interfaces
+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
+Requires-Dist: starlette>=0.48.0
+Provides-Extra: azure
+Requires-Dist: azure-identity==1.25.1; extra == 'azure'
+Requires-Dist: azure-keyvault-secrets==4.10.0; extra == 'azure'
+Description-Content-Type: text/markdown
+
+# appkit-commons
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/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
+- **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:
+
+```bash
+git clone https://github.com/jenreh/appkit.git
+cd appkit
+uv sync
+```
+
+### Standalone Installation
+
+Install from PyPI:
+
+```bash
+pip install appkit-commons
+```
+
+Or with uv:
+
+```bash
+uv add appkit-commons
+```
+
+### Optional Dependencies
+
+For Azure Key Vault support:
+
+```bash
+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`:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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`:
+
+```python
+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:
+
+```python
+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:
+
+```yaml
+# 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:
+
+```python
+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:
+
+```python
+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
+
+```python
+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
+
+```python
+from appkit_commons.security import generate_token
+
+token = generate_token(length=32)
+```
+
+### Service Registry
+
+#### Dependency Injection
+
+Register and retrieve services:
+
+```python
+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:
+
+```bash
+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:
+
+```python
+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:
+
+```python
+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:
+
+```python
+# 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:
+
+```python
+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](./../appkit-user)** - User authentication and authorization
+- **[appkit-assistant](./../appkit-assistant)** - AI assistant functionality
+- **[appkit-mantine](./../appkit-mantine)** - UI components
+- **[appkit-imagecreator](./../appkit-imagecreator)** - Image generation workflows

appkit_commons-0.13.0/README.md

@@ -0,0 +1,377 @@
+# appkit-commons
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/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
+- **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:
+
+```bash
+git clone https://github.com/jenreh/appkit.git
+cd appkit
+uv sync
+```
+
+### Standalone Installation
+
+Install from PyPI:
+
+```bash
+pip install appkit-commons
+```
+
+Or with uv:
+
+```bash
+uv add appkit-commons
+```
+
+### Optional Dependencies
+
+For Azure Key Vault support:
+
+```bash
+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`:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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`:
+
+```python
+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:
+
+```python
+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:
+
+```yaml
+# 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:
+
+```python
+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:
+
+```python
+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
+
+```python
+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
+
+```python
+from appkit_commons.security import generate_token
+
+token = generate_token(length=32)
+```
+
+### Service Registry
+
+#### Dependency Injection
+
+Register and retrieve services:
+
+```python
+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:
+
+```bash
+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:
+
+```python
+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:
+
+```python
+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:
+
+```python
+# 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:
+
+```python
+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](./../appkit-user)** - User authentication and authorization
+- **[appkit-assistant](./../appkit-assistant)** - AI assistant functionality
+- **[appkit-mantine](./../appkit-mantine)** - UI components
+- **[appkit-imagecreator](./../appkit-imagecreator)** - Image generation workflows

appkit_commons-0.13.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "appkit-commons"
+version = "0.13.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [{ name = "Jens Rehpöhler" }]
+requires-python = ">=3.13"
+keywords = [
+    "reflex",
+    "mantine",
+    "ui",
+    "components",
+    "web",
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: User Interfaces",
+]
+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",
+    "starlette>=0.48.0",
+]
+
+[project.optional-dependencies]
+azure = [
+    "azure-identity==1.25.1",
+    "azure-keyvault-secrets==4.10.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jenreh/appkit"
+Documentation = "https://github.com/jenreh/appkit/tree/main/docs"
+Repository = "https://github.com/jenreh/appkit"
+Issues = "https://github.com/jenreh/appkit/issues"
+
+[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.13.0/src/appkit_commons/middleware.py

@@ -0,0 +1,19 @@
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+
+# Redirect HTTP to HTTPS when behind a proxy (Azure) that sets X-Forwarded-Proto
+class ForceHTTPSMiddleware:
+    def __init__(self, app: ASGIApp):
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send):
+        if scope["type"] in ("http", "websocket"):
+            # Read headers to find X-Forwarded-Proto
+            headers = dict(scope["headers"])
+            # If Azure says it was HTTPS, force the scope to HTTPS
+            if (
+                b"x-forwarded-proto" in headers
+                and headers[b"x-forwarded-proto"] == b"https"
+            ):
+                scope["scheme"] = "https"
+        await self.app(scope, receive, send)

appkit_commons-0.7.1/PKG-INFO

@@ -1,15 +0,0 @@
-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

@@ -1,32 +0,0 @@
-[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"