py-aide 0.48.1

Modern Python 3.11+ Framework: Flask/FastAPI orchestration, and strict runtime enforcement.

🛡️ py_aide

Modern Python 3.11+ Framework: Flask/FastAPI Orchestration & Strict Runtime Enforcement

py_aide is a robust, developer-centric framework designed to bring safety, structure, and consistency to Python web applications. It provides a unique "Strict Runtime Enforcement" layer that ensures your code remains clean, documented, and type-safe at execution time.

---

🚀 Key Features

• Strict Runtime Enforcement: A powerful decorator that enforces type hints, docstrings, and calling conventions at runtime.
• Timezone-Aware Date Utilities: Generate dynamic, accurate timestamps across global regions using an IDE-friendly Timezones Enum with strict UTC defaults.
• Unified Server Portal: Seamlessly orchestrate Flask and FastAPI applications with shared security gates.
• Circuit Breaker Resilience: Industrial-grade protection against cascading failures.
• Thread-Safe SQL: A thread-level multiton SQLite manager with automatic JSON serialization and a custom DSL.
• Modern Security: Argon2id password hashing with background rehashing and Fernet-based encryption.
• Enterprise HTTP Client: A standardized, "always resolve" HTTP client with built-in retries and interceptors.

---

📚 Documentation Roadmap

We recommend exploring the framework in this order:

⚙️ Core System

• Structural Enforcement: Learn about the @enforce_requirements decorator and the validation engine.
• Global Utilities: Discover helpers for dates, image processing, secure codes, and file system operations.

🌐 Server & API

• Service Portals: Documentation for Flask/FastAPI orchestration, security gates, and WebSockets.
• HTTP Client & Response: Master the "Always Resolve" strategy and the unified Response protocol.

🧵 Persistence & Concurrency

• Database Orchestration: Deep dive into thread-safe SQLite and the powerful JSON DSL.
• Hybrid Cache: Lightning-fast memory access with non-blocking disk persistence.
• Threading & Buffers: Learn how to use persistent queues and non-blocking write buffers.
• Resilience & Circuits: Protecting your services with the Circuit Breaker pattern.

🔐 Security

• Security & Identity: Hashing, Token management, and Encryption standards.

---

⚙️ Core Philosophy: Strict Enforcement

At the heart of py_aide is the @enforce_requirements decorator. It prevents "sloppy" code by failing early (at boot-time or runtime) if your contracts are violated.

from py_aide.enforcer import enforce_requirements
from py_aide.customTypes import Options

@enforce_requirements
def create_user(*, name: str, role: Options[str, ["admin", "user"]]) -> dict:
    """Creates a new user record with runtime type and choice validation."""
    return {"name": name, "role": role}

---

🌍 Global Timezone Utilities

py_aide prevents timezone-related bugs by defaulting to UTC while providing a robust, auto-completable Enum for localized timestamps.

from py_aide.dates import DateUtils, Timezones

# Generates a standard UTC timestamp by default
utc_time = DateUtils.current_timestamp()

# Generates localized East Africa Time safely without string typos
eat_time = DateUtils.current_timestamp(timezone=Timezones.EAT)

# Shift dates natively in specific timezones
tomorrow_tokyo = DateUtils.tomorrow(timezone=Timezones.JST)

---

📦 Installation

# Core only (Encryption, Tokens, Threading, Base Requests)
pip install py_aide

# With Flask Portal & WebSockets
pip install "py_aide[flask]"

# With FastAPI Portal & Uvicorn
pip install "py_aide[fastapi]"

# With Database/Cache drivers
pip install "py_aide[postgres,redis,sqlite]"

# Install everything
pip install "py_aide[all]"

Note: py_aide requires Python 3.11+ and is currently optimized for Linux environments.

---

📄 License

This project is licensed under the MIT License.

👥 Authors

• Kakuru Douglas - [e-mail]