Metadata-Version: 2.4
Name: py_aide
Version: 0.33.1
Summary: Modern Python 3.11+ Framework: Flask/FastAPI orchestration, and strict runtime enforcement.
Author-email: Kakuru Douglas <vicaniddouglas@gmail.com>
License: MIT
Project-URL: Homepage, https://gitlab.com/vicaniddouglas/py_aide
Project-URL: Bug Tracker, https://gitlab.com/vicaniddouglas/py_aide/-/issues
Keywords: framework,flask,fastapi,runtime-enforcement,threading,websockets
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=41.0.0
Requires-Dist: argon2-cffi>=23.1.0
Requires-Dist: pydantic>=1.10.0
Requires-Dist: httpx>=0.28.1
Provides-Extra: flask
Requires-Dist: flask>=3.0.0; extra == "flask"
Requires-Dist: flask-cors>=4.0.0; extra == "flask"
Requires-Dist: flask-socketio>=5.3.6; extra == "flask"
Requires-Dist: eventlet>=0.33.3; extra == "flask"
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == "fastapi"
Requires-Dist: uvicorn[standard]>=0.23.0; extra == "fastapi"
Requires-Dist: python-multipart>=0.0.6; extra == "fastapi"
Provides-Extra: postgres
Requires-Dist: psycopg>=3.1.0; extra == "postgres"
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == "redis"
Provides-Extra: sqlite
Requires-Dist: aiosqlite>=0.19.0; extra == "sqlite"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: respx>=0.23.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Provides-Extra: all
Requires-Dist: py_aide[fastapi,flask,postgres,redis,sqlite]; extra == "all"
Dynamic: license-file

# 🛡️ 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.
- **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**](https://gitlab.com/vicaniddouglas/py_aide/-/blob/main/docs/ENFORCER.md): Learn about the `@enforce_requirements` decorator and the validation engine.
- [**Global Utilities**](https://gitlab.com/vicaniddouglas/py_aide/-/blob/main/docs/UTILS.md): Discover helpers for dates, image processing, secure codes, and file system operations.

### 🌐 Server & API
- [**Service Portals**](https://gitlab.com/vicaniddouglas/py_aide/-/blob/main/docs/SERVERS.md): Documentation for Flask/FastAPI orchestration, security gates, and WebSockets.
- [**HTTP Client & Response**](https://gitlab.com/vicaniddouglas/py_aide/-/blob/main/docs/REQUESTS.md): Master the "Always Resolve" strategy and the unified `Response` protocol.

### 🧵 Persistence & Concurrency
- [**Database Orchestration**](https://gitlab.com/vicaniddouglas/py_aide/-/blob/main/docs/DATABASE.md): Deep dive into thread-safe SQLite and the powerful **JSON DSL**.
- [**Hybrid Cache**](https://gitlab.com/vicaniddouglas/py_aide/-/blob/main/docs/CACHE.md): Lightning-fast memory access with non-blocking disk persistence.
- [**Threading & Buffers**](https://gitlab.com/vicaniddouglas/py_aide/-/blob/main/docs/THREADING.md): Learn how to use persistent queues and non-blocking write buffers.
- [**Resilience & Circuits**](https://gitlab.com/vicaniddouglas/py_aide/-/blob/main/docs/CIRCUITS.md): Protecting your services with the Circuit Breaker pattern.

### 🔐 Security
- [**Security & Identity**](https://gitlab.com/vicaniddouglas/py_aide/-/blob/main/docs/SECURITY.md): 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.

```python
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}
```

---

## 📦 Installation
```bash
# 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** - [vicaniddouglas@gmail.com](mailto:vicaniddouglas@gmail.com)
