py-aide 0.4.0

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 (positional-only/keyword-only) at runtime.
• Unified Server Portal: Seamlessly orchestrate Flask and FastAPI applications with shared security gates and auto-discovery of routes.
• WebSocket Excellence: Built-in support for WebSockets (powered by Eventlet and Flask-SocketIO) with integrated security and metrics.
• Thread-Safe SQL: A thread-level multiton SQLite manager with automatic JSON serialization, transaction tracking, and schema management.
• Modern Security: First-class support for Bearer tokens, API keys, and Fernet-based encryption.
• Rich Utilities: Built-in handlers for images (base64/files), dates (aware/naive conversions), and custom data structures.

📦 Installation

pip install py_aide

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

⚙️ Core Philosophy: Strict Enforcement

At the heart of py_aide is the @enforce_requirements decorator. It's designed to prevent "sloppy" code by failing early if:

• A function is missing a docstring.
• A parameter or return value is missing a type hint.
• A function uses more than 8 arguments (promoting better decomposition).
• Calling conventions (/ or *) are not explicitly defined.

from py_aide.enforcer import enforce_requirements

@enforce_requirements
def create_user(name: str, age: int, /) -> dict:
    """Creates a new user dict."""
    return {"name": name, "age": age}

🌐 Unified Server Example (Flask)

from py_aide.servers.flask import ServicePortal, GateConfig

portal = ServicePortal()

@portal.endpoint("/api/greet", gate=GateConfig(auth_required=False))
def greet(name: str, /) -> dict:
    """Returns a greeting message."""
    return {"message": f"Hello, {name}!"}

if __name__ == "__main__":
    portal.run(port=5000)

🗄️ Database Management

py_aide provides a thread-local multiton pattern for SQLite, ensuring each thread has its own connection while sharing the same configuration.

from py_aide.database import Api

db_config = {
    'users': 'id INTEGER PRIMARY KEY, name TEXT, meta JSON'
}

with Api(db_path="data.db", tables=db_config) as db:
    db.insert(table="users", data=[(1, "Alice", {"role": "admin"})])
    result = db.fetch(table="users", columns=["name", "meta::role as role"])
    print(result.data) # [{'name': 'Alice', 'role': 'admin'}]

⚠️ Important Note: Eventlet Monkey Patching

By default, importing src.py_aide (or the top-level package) immediately performs eventlet.monkey_patch(). This is required for reliable WebSocket support and some threading features. If you need to avoid this side-effect, ensure you understand the dependencies of your modules.

📄 License

This project is licensed under the MIT License. See the LICENSE file for more details.

👥 Authors

• Kakuru Douglas - [e-mail]