py-aide 0.0.3__tar.gz

py_aide-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kakuru Douglas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_aide-0.0.3/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: py_aide
+Version: 0.0.3
+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: flask>=3.0.0
+Requires-Dist: flask-cors>=4.0.0
+Requires-Dist: flask-socketio>=5.3.6
+Requires-Dist: eventlet>=0.33.3
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: argon2-cffi>=23.1.0
+Requires-Dist: pydantic>=1.10.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.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"
+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 (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
+```bash
+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.
+
+```python
+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)
+
+```python
+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.
+
+```python
+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](LICENSE) file for more details.
+
+## 👥 Authors
+- **Kakuru Douglas** - [vicaniddouglas@gmail.com](mailto:vicaniddouglas@gmail.com)

py_aide-0.0.3/README.md

@@ -0,0 +1,83 @@
+# 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
+```bash
+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.
+
+```python
+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)
+
+```python
+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.
+
+```python
+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](LICENSE) file for more details.
+
+## 👥 Authors
+- **Kakuru Douglas** - [vicaniddouglas@gmail.com](mailto:vicaniddouglas@gmail.com)

py_aide-0.0.3/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "py_aide"
+version = "0.0.3"
+authors = [
+  { name="Kakuru Douglas", email="vicaniddouglas@gmail.com" },
+]
+description = "Modern Python 3.11+ Framework: Flask/FastAPI orchestration, and strict runtime enforcement."
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = ["framework", "flask", "fastapi", "runtime-enforcement", "threading", "websockets"]
+license = {text = "MIT"}
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+
+dependencies = [
+    "flask>=3.0.0",
+    "flask-cors>=4.0.0",
+    "flask-socketio>=5.3.6",
+    "eventlet>=0.33.3",
+    "fastapi>=0.100.0",
+    "cryptography>=41.0.0",
+    "argon2-cffi>=23.1.0",
+    "pydantic>=1.10.0",  # FastAPI uses pydantic
+]
+
+[project.urls]
+"Homepage" = "https://gitlab.com/vicaniddouglas/py_aide"
+"Bug Tracker" = "https://gitlab.com/vicaniddouglas/py_aide/-/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "black>=23.0.0",
+    "isort>=5.12.0",
+    "mypy>=1.5.0",
+]

py_aide-0.0.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

py_aide-0.0.3/src/py_aide/__init__.py

@@ -0,0 +1,41 @@
+"""
+py_aide - Main package
+This framework uses EVENTLET for WebSocket support.
+Eventlet monkey patching happens IMMEDIATELY when this package is imported.
+"""
+
+# ============================================================================
+# CRITICAL: Eventlet monkey patching - MUST be the first thing that runs
+# ============================================================================
+
+import sys
+
+try:
+    import eventlet
+    eventlet.monkey_patch()
+    print(f"[py_aide] Eventlet patched successfully (Python {sys.version_info.major}.{sys.version_info.minor})")
+except ImportError:
+    print("\n" + "="*70)
+    print("CRITICAL: Eventlet not installed")
+    print("="*70)
+    print("This framework REQUIRES eventlet for WebSocket support.")
+    print("Install it with: pip install eventlet")
+    print("If you don't need WebSockets, set enable_websocket=False")
+    print("="*70 + "\n")
+    raise  # Stop execution - don't proceed without eventlet
+
+from .response import Response, ok, error
+from . import structures
+from . import codes
+from . import database
+from . import enforcer
+from . import encryption
+from . import dates
+from . import servers
+from . import threading
+from . import images
+from . import tokens
+
+from .customTypes import Definition, Options
+from . import auth
+

py_aide-0.0.3/src/py_aide/auth/__init__.py

@@ -0,0 +1,2 @@
+from .legacy import hash_password, verify_password
+from .password import hash_password, verify_password, Argon2Config

py_aide-0.0.3/src/py_aide/auth/legacy.py

@@ -0,0 +1,95 @@
+import hashlib
+import secrets
+import base64
+import hmac
+import binascii
+
+from ..enforcer import enforce_requirements
+
+# --- Configuration Constants ---
+# Using 600,000 iterations (OWASP recommended baseline)
+# Using SHA-256 as the underlying pseudo-random function
+ALGORITHM = 'sha256'
+ITERATIONS = 600_000
+SALT_SIZE = 16  # 128-bit salt
+
+@enforce_requirements
+def hash_password(raw_password: str,/) -> str:
+    """
+    Transforms a plain-text password into a secure, portable hash string.
+    
+    Process:
+    1. Generates a unique 16-byte random salt.
+    2. Stretches the password using PBKDF2 with 600,000 rounds.
+    3. Encodes binary results to Base64 for safe database storage.
+    
+    Args:
+        raw_password: The plain-text string to hash.
+        
+    Returns:
+        A formatted string: pbkdf2$sha256$600000$base64_salt$base64_hash
+    """
+    # 1. Generate a cryptographically secure random salt
+    salt = secrets.token_bytes(SALT_SIZE)
+    
+    # 2. Derive the hash using PBKDF2
+    # Password must be encoded to bytes (UTF-8)
+    hash_bytes = hashlib.pbkdf2_hmac(
+        ALGORITHM,
+        raw_password.encode('utf-8'),
+        salt,
+        ITERATIONS
+    )
+    
+    # 3. Convert binary data to Base64 strings for storage
+    b64_salt = base64.b64encode(salt).decode('utf-8')
+    b64_hash = base64.b64encode(hash_bytes).decode('utf-8')
+    
+    # 4. Return a single "packaged" string
+    return f"pbkdf2::{ALGORITHM}::{ITERATIONS}::{b64_salt}::{b64_hash}"
+
+@enforce_requirements
+def verify_password(input_password: str, stored_hash: str,/) -> bool:
+    """
+    Validates a login attempt against a previously stored hash string.
+    
+    Process:
+    1. Parses the stored string to retrieve salt and iteration count.
+    2. Re-hashes the input_password using those exact parameters.
+    3. Uses a constant-time comparison to prevent timing attacks.
+    
+    Args:
+        input_password: The password provided during login.
+        stored_hash: The full string generated by hash_password().
+        
+    Returns:
+        True if the passwords match, False otherwise.
+    """
+    try:
+        # 1. Parse the packaged string
+        parts = stored_hash.split('::')
+        if len(parts) != 5:
+            return False
+        
+        _, algo, iterations, b64_salt, b64_hash = parts
+        
+        # 2. Convert metadata and salt back to original types
+        iterations = int(iterations)
+        salt = base64.b64decode(b64_salt)
+        original_hash = base64.b64decode(b64_hash)
+        
+        # 3. Re-hash the new attempt with the OLD salt and OLD iterations
+        new_hash = hashlib.pbkdf2_hmac(
+            algo,
+            input_password.encode('utf-8'),
+            salt,
+            iterations
+        )
+        
+        # 4. Constant-time comparison to protect against timing attacks
+        return hmac.compare_digest(new_hash, original_hash)
+        
+    except (ValueError, TypeError, binascii.Error):
+        # If the stored hash is corrupted or manipulated, return False
+        return False
+