@malamute/ai-rules 1.0.0 → 1.3.0

package/configs/flask/rules/context.md

@@ -0,0 +1,238 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Flask Context Management
+
+## Application Context
+
+```python
+from flask import current_app, g
+
+# GOOD - use application context
+with app.app_context():
+    db.create_all()
+    current_app.logger.info("Database initialized")
+
+# In CLI commands
+@app.cli.command("init-db")
+def init_db():
+    # Already in app context
+    db.create_all()
+    click.echo("Database initialized")
+
+# BAD - access outside context
+db.create_all()  # RuntimeError: Working outside of application context
+```
+
+## Request Context
+
+```python
+from flask import request, session, g
+
+# Automatically pushed during requests
+@app.route("/")
+def index():
+    user_agent = request.headers.get("User-Agent")
+    user_id = session.get("user_id")
+    return f"UA: {user_agent}"
+
+# Test request context
+with app.test_request_context("/users?page=2"):
+    assert request.path == "/users"
+    assert request.args["page"] == "2"
+    url = url_for("users.list_users")
+```
+
+## The `g` Object
+
+```python
+from flask import g
+
+# GOOD - store per-request data in g
+@app.before_request
+def load_user():
+    user_id = session.get("user_id")
+    if user_id:
+        g.user = User.query.get(user_id)
+    else:
+        g.user = None
+
+@app.route("/profile")
+def profile():
+    if g.user is None:
+        return redirect(url_for("auth.login"))
+    return render_template("profile.html", user=g.user)
+
+# GOOD - lazy loading with g
+def get_db():
+    if "db" not in g:
+        g.db = connect_to_database()
+    return g.db
+
+@app.teardown_appcontext
+def close_db(exception):
+    db = g.pop("db", None)
+    if db is not None:
+        db.close()
+```
+
+## Request Hooks
+
+```python
+# Before first request (deprecated in Flask 2.3+)
+# Use app.before_request or lifespan pattern instead
+
+@app.before_request
+def before_every_request():
+    """Run before every request."""
+    g.start_time = time.time()
+    g.request_id = request.headers.get("X-Request-ID", str(uuid.uuid4()))
+
+@app.after_request
+def after_every_request(response):
+    """Run after every request (even on error)."""
+    duration = time.time() - g.start_time
+    response.headers["X-Request-ID"] = g.request_id
+    response.headers["X-Response-Time"] = f"{duration:.4f}s"
+    return response
+
+@app.teardown_request
+def teardown_request(exception):
+    """Run at the end of request, for cleanup."""
+    if exception:
+        app.logger.error(f"Request failed: {exception}")
+```
+
+## Blueprint-Specific Hooks
+
+```python
+users_bp = Blueprint("users", __name__)
+
+@users_bp.before_request
+def before_user_request():
+    """Only runs for requests to this blueprint."""
+    g.service = UserService(db.session)
+
+@users_bp.after_request
+def after_user_request(response):
+    """Only runs for requests to this blueprint."""
+    return response
+
+# App-wide hooks still run for blueprint requests
+```
+
+## Context Locals with werkzeug
+
+```python
+from werkzeug.local import LocalStack, LocalProxy
+
+# Custom context local
+_request_ctx_stack = LocalStack()
+
+def get_current_request_id():
+    ctx = _request_ctx_stack.top
+    if ctx is not None:
+        return ctx.request_id
+    return None
+
+request_id = LocalProxy(get_current_request_id)
+```
+
+## Async Context (Flask 2.0+)
+
+```python
+from flask import Flask
+import asyncio
+
+app = Flask(__name__)
+
+@app.route("/async")
+async def async_route():
+    # Can use async/await in routes
+    result = await some_async_operation()
+    return jsonify(result)
+
+# Context is preserved in async functions
+@app.route("/async-context")
+async def async_with_context():
+    # current_app, g, request all work
+    app.logger.info("Async route called")
+    g.async_data = await fetch_data()
+    return jsonify(g.async_data)
+```
+
+## Testing Contexts
+
+```python
+import pytest
+
+@pytest.fixture
+def app():
+    app = create_app("testing")
+    return app
+
+@pytest.fixture
+def client(app):
+    return app.test_client()
+
+@pytest.fixture
+def app_context(app):
+    with app.app_context():
+        yield
+
+@pytest.fixture
+def request_context(app):
+    with app.test_request_context():
+        yield
+
+def test_with_app_context(app_context):
+    # current_app is available
+    assert current_app.config["TESTING"]
+
+def test_with_request_context(request_context):
+    # request, g are available
+    g.user = User(name="Test")
+    assert g.user.name == "Test"
+```
+
+## Pushing Contexts Manually
+
+```python
+# For background tasks, CLI commands, etc.
+def background_task(app, user_id):
+    with app.app_context():
+        user = User.query.get(user_id)
+        send_email(user)
+
+# Thread-safe context pushing
+from threading import Thread
+
+def run_in_thread(app):
+    def wrapper():
+        with app.app_context():
+            do_work()
+
+    thread = Thread(target=wrapper)
+    thread.start()
+    return thread
+```
+
+## Context Processor
+
+```python
+@app.context_processor
+def inject_globals():
+    """Inject variables into all templates."""
+    return {
+        "current_year": datetime.now().year,
+        "app_name": current_app.config["APP_NAME"],
+        "user": g.get("user"),
+    }
+
+# In templates
+# {{ current_year }}
+# {{ app_name }}
+# {% if user %}Hello {{ user.name }}{% endif %}
+```

package/configs/flask/rules/error-handlers.md

@@ -0,0 +1,278 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Flask Error Handling
+
+## HTTP Error Handlers
+
+```python
+from flask import jsonify, render_template
+from werkzeug.exceptions import HTTPException
+
+# JSON API error handler
+@app.errorhandler(HTTPException)
+def handle_http_exception(error):
+    return jsonify({
+        "error": error.name,
+        "message": error.description,
+        "status_code": error.code,
+    }), error.code
+
+# Specific error handlers
+@app.errorhandler(404)
+def not_found(error):
+    if request.accept_mimetypes.accept_json:
+        return jsonify({"error": "Not found"}), 404
+    return render_template("errors/404.html"), 404
+
+@app.errorhandler(500)
+def internal_error(error):
+    db.session.rollback()  # Rollback failed transaction
+    return jsonify({"error": "Internal server error"}), 500
+
+@app.errorhandler(429)
+def rate_limit_exceeded(error):
+    return jsonify({
+        "error": "Rate limit exceeded",
+        "retry_after": error.description,
+    }), 429
+```
+
+## Custom Exception Classes
+
+```python
+class AppException(Exception):
+    """Base exception for application errors."""
+    status_code = 500
+    error_code = "INTERNAL_ERROR"
+    message = "An unexpected error occurred"
+
+    def __init__(self, message: str = None, payload: dict = None):
+        super().__init__()
+        self.message = message or self.message
+        self.payload = payload
+
+    def to_dict(self) -> dict:
+        rv = {
+            "error": self.error_code,
+            "message": self.message,
+        }
+        if self.payload:
+            rv["details"] = self.payload
+        return rv
+
+class NotFoundError(AppException):
+    status_code = 404
+    error_code = "NOT_FOUND"
+    message = "Resource not found"
+
+class ValidationError(AppException):
+    status_code = 400
+    error_code = "VALIDATION_ERROR"
+    message = "Validation failed"
+
+class UnauthorizedError(AppException):
+    status_code = 401
+    error_code = "UNAUTHORIZED"
+    message = "Authentication required"
+
+class ForbiddenError(AppException):
+    status_code = 403
+    error_code = "FORBIDDEN"
+    message = "Access denied"
+
+class ConflictError(AppException):
+    status_code = 409
+    error_code = "CONFLICT"
+    message = "Resource already exists"
+
+# Register handler
+@app.errorhandler(AppException)
+def handle_app_exception(error):
+    response = jsonify(error.to_dict())
+    response.status_code = error.status_code
+    return response
+
+# Usage
+@users_bp.route("/<int:user_id>")
+def get_user(user_id: int):
+    user = User.query.get(user_id)
+    if not user:
+        raise NotFoundError(f"User {user_id} not found")
+    return jsonify(UserSchema().dump(user))
+```
+
+## Marshmallow Validation Errors
+
+```python
+from marshmallow import ValidationError as MarshmallowValidationError
+
+@app.errorhandler(MarshmallowValidationError)
+def handle_validation_error(error):
+    return jsonify({
+        "error": "VALIDATION_ERROR",
+        "message": "Input validation failed",
+        "details": error.messages,
+    }), 400
+
+# Usage
+@users_bp.route("/", methods=["POST"])
+def create_user():
+    schema = UserCreateSchema()
+    data = schema.load(request.get_json())  # Raises ValidationError if invalid
+    user = UserService.create(data)
+    return jsonify(UserSchema().dump(user)), 201
+```
+
+## SQLAlchemy Errors
+
+```python
+from sqlalchemy.exc import IntegrityError, SQLAlchemyError
+
+@app.errorhandler(IntegrityError)
+def handle_integrity_error(error):
+    db.session.rollback()
+
+    # Parse constraint violation
+    if "unique constraint" in str(error.orig).lower():
+        return jsonify({
+            "error": "DUPLICATE_ENTRY",
+            "message": "A record with this value already exists",
+        }), 409
+
+    return jsonify({
+        "error": "DATABASE_ERROR",
+        "message": "Database constraint violation",
+    }), 400
+
+@app.errorhandler(SQLAlchemyError)
+def handle_db_error(error):
+    db.session.rollback()
+    app.logger.error(f"Database error: {error}")
+    return jsonify({
+        "error": "DATABASE_ERROR",
+        "message": "A database error occurred",
+    }), 500
+```
+
+## Logging Errors
+
+```python
+import logging
+import traceback
+
+@app.errorhandler(Exception)
+def handle_unexpected_error(error):
+    # Log full traceback
+    app.logger.error(
+        "Unhandled exception",
+        extra={
+            "error": str(error),
+            "traceback": traceback.format_exc(),
+            "path": request.path,
+            "method": request.method,
+            "user_id": g.get("user_id"),
+        },
+    )
+
+    # Return generic error to client
+    if app.debug:
+        return jsonify({
+            "error": "INTERNAL_ERROR",
+            "message": str(error),
+            "traceback": traceback.format_exc(),
+        }), 500
+
+    return jsonify({
+        "error": "INTERNAL_ERROR",
+        "message": "An unexpected error occurred",
+    }), 500
+```
+
+## Blueprint Error Handlers
+
+```python
+users_bp = Blueprint("users", __name__)
+
+# Only handles errors from this blueprint
+@users_bp.errorhandler(404)
+def user_not_found(error):
+    return jsonify({
+        "error": "USER_NOT_FOUND",
+        "message": "The requested user was not found",
+    }), 404
+
+# App-level handler is fallback
+@app.errorhandler(404)
+def generic_not_found(error):
+    return jsonify({
+        "error": "NOT_FOUND",
+        "message": "Resource not found",
+    }), 404
+```
+
+## Error Response Format
+
+```python
+from dataclasses import dataclass
+from typing import Any
+
+@dataclass
+class ErrorResponse:
+    error: str
+    message: str
+    status_code: int
+    details: dict[str, Any] | None = None
+    request_id: str | None = None
+
+    def to_dict(self) -> dict:
+        data = {
+            "error": self.error,
+            "message": self.message,
+        }
+        if self.details:
+            data["details"] = self.details
+        if self.request_id:
+            data["request_id"] = self.request_id
+        return data
+
+def error_response(
+    error: str,
+    message: str,
+    status_code: int,
+    details: dict = None,
+) -> tuple:
+    response = ErrorResponse(
+        error=error,
+        message=message,
+        status_code=status_code,
+        details=details,
+        request_id=g.get("request_id"),
+    )
+    return jsonify(response.to_dict()), status_code
+```
+
+## Abort with Custom Response
+
+```python
+from flask import abort
+
+@users_bp.route("/<int:user_id>")
+def get_user(user_id: int):
+    user = User.query.get(user_id)
+    if not user:
+        abort(404, description="User not found")
+    return jsonify(UserSchema().dump(user))
+
+# Or with custom response
+from werkzeug.exceptions import NotFound
+
+@users_bp.route("/<int:user_id>")
+def get_user(user_id: int):
+    user = User.query.get(user_id)
+    if not user:
+        raise NotFound(f"User with ID {user_id} not found")
+    return jsonify(UserSchema().dump(user))
+```