@malamute/ai-rules 1.0.0 → 1.3.0

package/configs/flask/rules/extensions.md

@@ -0,0 +1,278 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Flask Extensions Patterns
+
+## Extension Initialization
+
+```python
+# GOOD - Lazy initialization (extensions.py)
+from flask_sqlalchemy import SQLAlchemy
+from flask_migrate import Migrate
+from flask_jwt_extended import JWTManager
+from flask_cors import CORS
+from flask_mail import Mail
+
+db = SQLAlchemy()
+migrate = Migrate()
+jwt = JWTManager()
+cors = CORS()
+mail = Mail()
+
+# In factory (app/__init__.py)
+def create_app(config_name: str = "development") -> Flask:
+    app = Flask(__name__)
+    app.config.from_object(config[config_name])
+
+    # Initialize extensions
+    db.init_app(app)
+    migrate.init_app(app, db)
+    jwt.init_app(app)
+    cors.init_app(app)
+    mail.init_app(app)
+
+    return app
+
+# BAD - Eager initialization
+from flask import Flask
+from flask_sqlalchemy import SQLAlchemy
+
+app = Flask(__name__)
+db = SQLAlchemy(app)  # Can't use different configs!
+```
+
+## Flask-SQLAlchemy
+
+```python
+from app.extensions import db
+from sqlalchemy.orm import Mapped, mapped_column
+
+class User(db.Model):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(unique=True, index=True)
+    name: Mapped[str] = mapped_column(db.String(100))
+    is_active: Mapped[bool] = mapped_column(default=True)
+
+    # Relationships
+    orders: Mapped[list["Order"]] = db.relationship(back_populates="user")
+
+# Usage in routes
+@users_bp.route("/")
+def list_users():
+    users = db.session.scalars(db.select(User).where(User.is_active)).all()
+    return jsonify(UserSchema(many=True).dump(users))
+```
+
+## Flask-Migrate
+
+```python
+# migrations/env.py is auto-generated
+# Commands:
+# flask db init        - Initialize migrations
+# flask db migrate -m "Add users table"
+# flask db upgrade     - Apply migrations
+# flask db downgrade   - Rollback last migration
+# flask db current     - Show current revision
+# flask db history     - Show migration history
+```
+
+## Flask-JWT-Extended
+
+```python
+from flask_jwt_extended import (
+    create_access_token,
+    create_refresh_token,
+    jwt_required,
+    current_user,
+    get_jwt_identity,
+)
+
+# Configure in factory
+app.config["JWT_SECRET_KEY"] = os.environ["JWT_SECRET_KEY"]
+app.config["JWT_ACCESS_TOKEN_EXPIRES"] = timedelta(hours=1)
+app.config["JWT_REFRESH_TOKEN_EXPIRES"] = timedelta(days=30)
+
+# User loader callback
+@jwt.user_lookup_loader
+def user_lookup_callback(_jwt_header, jwt_data):
+    identity = jwt_data["sub"]
+    return User.query.get(identity)
+
+# Login endpoint
+@auth_bp.route("/login", methods=["POST"])
+def login():
+    data = LoginSchema().load(request.get_json())
+    user = User.query.filter_by(email=data["email"]).first()
+
+    if not user or not user.check_password(data["password"]):
+        return jsonify({"error": "Invalid credentials"}), 401
+
+    access_token = create_access_token(identity=user.id)
+    refresh_token = create_refresh_token(identity=user.id)
+
+    return jsonify({
+        "access_token": access_token,
+        "refresh_token": refresh_token,
+    })
+
+# Protected endpoint
+@users_bp.route("/me")
+@jwt_required()
+def get_current_user():
+    return jsonify(UserSchema().dump(current_user))
+
+# Refresh token
+@auth_bp.route("/refresh", methods=["POST"])
+@jwt_required(refresh=True)
+def refresh():
+    identity = get_jwt_identity()
+    access_token = create_access_token(identity=identity)
+    return jsonify({"access_token": access_token})
+```
+
+## Flask-CORS
+
+```python
+from flask_cors import CORS
+
+# Global CORS
+cors.init_app(app, resources={
+    r"/api/*": {
+        "origins": ["https://example.com"],
+        "methods": ["GET", "POST", "PUT", "DELETE"],
+        "allow_headers": ["Authorization", "Content-Type"],
+    }
+})
+
+# Blueprint-specific CORS
+CORS(users_bp, origins=["https://admin.example.com"])
+
+# Route-specific
+from flask_cors import cross_origin
+
+@app.route("/public")
+@cross_origin(origins="*")
+def public_endpoint():
+    return jsonify({"public": True})
+```
+
+## Flask-Mail
+
+```python
+from flask_mail import Message
+from app.extensions import mail
+
+def send_welcome_email(user: User):
+    msg = Message(
+        subject="Welcome!",
+        sender="noreply@example.com",
+        recipients=[user.email],
+    )
+    msg.body = f"Hello {user.name}, welcome to our platform!"
+    msg.html = render_template("emails/welcome.html", user=user)
+
+    mail.send(msg)
+
+# Async email sending
+from threading import Thread
+
+def send_async_email(app, msg):
+    with app.app_context():
+        mail.send(msg)
+
+def send_email_async(msg):
+    Thread(target=send_async_email, args=(current_app._get_current_object(), msg)).start()
+```
+
+## Flask-Caching
+
+```python
+from flask_caching import Cache
+
+cache = Cache()
+
+# Configuration
+app.config["CACHE_TYPE"] = "redis"
+app.config["CACHE_REDIS_URL"] = os.environ["REDIS_URL"]
+app.config["CACHE_DEFAULT_TIMEOUT"] = 300
+
+cache.init_app(app)
+
+# Usage
+@users_bp.route("/<int:user_id>")
+@cache.cached(timeout=60, key_prefix="user")
+def get_user(user_id: int):
+    user = User.query.get_or_404(user_id)
+    return jsonify(UserSchema().dump(user))
+
+# Memoize (cache with arguments)
+@cache.memoize(timeout=300)
+def get_user_stats(user_id: int) -> dict:
+    return calculate_stats(user_id)
+
+# Clear cache
+cache.delete("user")
+cache.delete_memoized(get_user_stats, user_id)
+```
+
+## Flask-Limiter
+
+```python
+from flask_limiter import Limiter
+from flask_limiter.util import get_remote_address
+
+limiter = Limiter(
+    key_func=get_remote_address,
+    default_limits=["100 per hour"],
+    storage_uri="redis://localhost:6379",
+)
+
+limiter.init_app(app)
+
+# Route-specific limits
+@auth_bp.route("/login", methods=["POST"])
+@limiter.limit("5 per minute")
+def login():
+    ...
+
+# Blueprint limits
+limiter.limit("50 per hour")(users_bp)
+
+# Exempt from limits
+@app.route("/health")
+@limiter.exempt
+def health():
+    return jsonify({"status": "ok"})
+```
+
+## Flask-Login (Session-Based)
+
+```python
+from flask_login import LoginManager, login_user, logout_user, login_required, current_user
+
+login_manager = LoginManager()
+login_manager.login_view = "auth.login"
+
+@login_manager.user_loader
+def load_user(user_id):
+    return User.query.get(int(user_id))
+
+# Login
+@auth_bp.route("/login", methods=["POST"])
+def login():
+    user = authenticate(request.form["email"], request.form["password"])
+    if user:
+        login_user(user, remember=True)
+        return redirect(url_for("main.index"))
+    return render_template("login.html", error="Invalid credentials")
+
+# Protected route
+@main_bp.route("/dashboard")
+@login_required
+def dashboard():
+    return render_template("dashboard.html", user=current_user)
+```

package/configs/flask/rules/flask.md

@@ -0,0 +1,171 @@
+# Flask Rules
+
+## Activation
+
+```yaml
+paths:
+  - "**/*.py"
+```
+
+## Application Factory
+
+```python
+# GOOD - Application factory pattern
+def create_app(config_name: str = "development") -> Flask:
+    app = Flask(__name__)
+    app.config.from_object(config[config_name])
+
+    db.init_app(app)
+    register_blueprints(app)
+
+    return app
+
+# BAD - Global app instance
+app = Flask(__name__)  # Hard to test, can't have multiple configs
+```
+
+## Blueprints
+
+```python
+# GOOD - Organized blueprints
+from flask import Blueprint
+
+users_bp = Blueprint("users", __name__)
+
+@users_bp.route("/", methods=["GET"])
+def list_users():
+    ...
+
+# Register in factory
+app.register_blueprint(users_bp, url_prefix="/api/v1/users")
+
+# BAD - All routes in one file
+@app.route("/api/v1/users")
+@app.route("/api/v1/posts")
+@app.route("/api/v1/comments")  # Messy, hard to maintain
+```
+
+## Request Handling
+
+```python
+# GOOD - Validate input with schemas
+from marshmallow import ValidationError
+
+@users_bp.route("/", methods=["POST"])
+def create_user():
+    try:
+        data = UserCreateSchema().load(request.get_json())
+    except ValidationError as e:
+        return jsonify({"errors": e.messages}), 400
+
+    user = user_service.create(data)
+    return jsonify(UserResponseSchema().dump(user)), 201
+
+# BAD - Direct access without validation
+@users_bp.route("/", methods=["POST"])
+def create_user():
+    data = request.get_json()
+    user = User(email=data["email"])  # No validation!
+    db.session.add(user)
+    db.session.commit()
+    return jsonify(user.to_dict())
+```
+
+## Context Management
+
+```python
+# GOOD - Use application context
+with app.app_context():
+    db.create_all()
+
+# GOOD - Use test request context
+with app.test_request_context():
+    url = url_for("users.get_user", user_id=1)
+
+# BAD - Access outside context
+db.create_all()  # RuntimeError: No application context
+```
+
+## Configuration
+
+```python
+# GOOD - Class-based config
+class Config:
+    SECRET_KEY = os.environ.get("SECRET_KEY", "dev-key")
+    SQLALCHEMY_TRACK_MODIFICATIONS = False
+
+class DevelopmentConfig(Config):
+    DEBUG = True
+    SQLALCHEMY_DATABASE_URI = "sqlite:///dev.db"
+
+class ProductionConfig(Config):
+    DEBUG = False
+    SQLALCHEMY_DATABASE_URI = os.environ["DATABASE_URL"]
+
+config = {
+    "development": DevelopmentConfig,
+    "production": ProductionConfig,
+    "testing": TestingConfig,
+}
+
+# BAD - Hardcoded config
+app.config["SECRET_KEY"] = "hardcoded-secret"  # Never do this
+```
+
+## Testing
+
+```python
+# GOOD - Test client fixture
+import pytest
+
+@pytest.fixture
+def app():
+    app = create_app("testing")
+    return app
+
+@pytest.fixture
+def client(app):
+    return app.test_client()
+
+@pytest.fixture
+def db_session(app):
+    with app.app_context():
+        db.create_all()
+        yield db.session
+        db.drop_all()
+
+def test_create_user(client):
+    response = client.post("/api/v1/users", json={
+        "email": "test@example.com",
+        "password": "password123",
+        "name": "Test User",
+    })
+    assert response.status_code == 201
+    assert response.json["email"] == "test@example.com"
+```
+
+## Extensions Pattern
+
+```python
+# GOOD - Lazy initialization
+# extensions.py
+from flask_sqlalchemy import SQLAlchemy
+from flask_migrate import Migrate
+
+db = SQLAlchemy()
+migrate = Migrate()
+
+# __init__.py
+def create_app():
+    app = Flask(__name__)
+    db.init_app(app)
+    migrate.init_app(app, db)
+    return app
+
+# BAD - Eager initialization
+from flask import Flask
+from flask_sqlalchemy import SQLAlchemy
+
+app = Flask(__name__)
+db = SQLAlchemy(app)  # Can't use different configs
+```

package/configs/flask/rules/marshmallow.md

@@ -0,0 +1,206 @@
+# Marshmallow Validation Rules
+
+## Activation
+
+```yaml
+paths:
+  - "**/*.py"
+```
+
+## Schema Definition
+
+```python
+# GOOD - Clear schema with validation
+from marshmallow import Schema, fields, validate, validates, ValidationError, post_load
+
+class UserCreateSchema(Schema):
+    email = fields.Email(required=True)
+    password = fields.Str(required=True, validate=validate.Length(min=8))
+    name = fields.Str(required=True, validate=validate.Length(min=1, max=100))
+    age = fields.Int(validate=validate.Range(min=0, max=150))
+
+class UserResponseSchema(Schema):
+    id = fields.Int(dump_only=True)
+    email = fields.Email()
+    name = fields.Str()
+    created_at = fields.DateTime(dump_only=True)
+
+# BAD - No validation
+class UserSchema(Schema):
+    email = fields.Str()  # Should be fields.Email
+    password = fields.Str()  # No length validation
+```
+
+## Custom Validation
+
+```python
+# GOOD - Field-level validation
+class UserSchema(Schema):
+    username = fields.Str(required=True)
+
+    @validates("username")
+    def validate_username(self, value):
+        if not value.isalnum():
+            raise ValidationError("Username must be alphanumeric")
+        if len(value) < 3:
+            raise ValidationError("Username must be at least 3 characters")
+
+# GOOD - Cross-field validation
+from marshmallow import validates_schema
+
+class PasswordChangeSchema(Schema):
+    password = fields.Str(required=True)
+    password_confirm = fields.Str(required=True)
+
+    @validates_schema
+    def validate_passwords_match(self, data, **kwargs):
+        if data.get("password") != data.get("password_confirm"):
+            raise ValidationError("Passwords must match", field_name="password_confirm")
+```
+
+## Load/Dump Hooks
+
+```python
+from marshmallow import pre_load, post_load, post_dump
+
+class UserSchema(Schema):
+    email = fields.Email(required=True)
+    name = fields.Str(required=True)
+
+    @pre_load
+    def normalize_email(self, data, **kwargs):
+        if "email" in data:
+            data["email"] = data["email"].lower().strip()
+        return data
+
+    @post_load
+    def make_user(self, data, **kwargs):
+        return User(**data)
+
+    @post_dump
+    def remove_nulls(self, data, **kwargs):
+        return {k: v for k, v in data.items() if v is not None}
+```
+
+## Nested Schemas
+
+```python
+# GOOD - Nested relationships
+class AddressSchema(Schema):
+    street = fields.Str(required=True)
+    city = fields.Str(required=True)
+    country = fields.Str(required=True)
+
+class UserSchema(Schema):
+    name = fields.Str(required=True)
+    address = fields.Nested(AddressSchema)
+    addresses = fields.List(fields.Nested(AddressSchema))
+
+# GOOD - Self-referential (e.g., comments with replies)
+class CommentSchema(Schema):
+    id = fields.Int(dump_only=True)
+    text = fields.Str(required=True)
+    replies = fields.List(fields.Nested("self", exclude=("replies",)))
+```
+
+## Partial Loading
+
+```python
+# GOOD - Partial updates
+class UserUpdateSchema(Schema):
+    email = fields.Email()
+    name = fields.Str(validate=validate.Length(min=1, max=100))
+
+@users_bp.route("/<int:user_id>", methods=["PATCH"])
+def update_user(user_id: int):
+    schema = UserUpdateSchema()
+    data = schema.load(request.get_json(), partial=True)
+    user = UserService.update(user_id, data)
+    return jsonify(UserResponseSchema().dump(user))
+```
+
+## Schema Inheritance
+
+```python
+# GOOD - Base schema with common fields
+class BaseSchema(Schema):
+    class Meta:
+        strict = True
+
+class TimestampMixin:
+    created_at = fields.DateTime(dump_only=True)
+    updated_at = fields.DateTime(dump_only=True)
+
+class UserSchema(BaseSchema, TimestampMixin):
+    id = fields.Int(dump_only=True)
+    email = fields.Email(required=True)
+    name = fields.Str(required=True)
+```
+
+## Error Handling
+
+```python
+# GOOD - Centralized error handling
+from marshmallow import ValidationError
+from flask import jsonify
+
+@app.errorhandler(ValidationError)
+def handle_validation_error(error):
+    return jsonify({
+        "error": "Validation Error",
+        "details": error.messages,
+    }), 400
+
+# In routes
+@users_bp.route("/", methods=["POST"])
+def create_user():
+    schema = UserCreateSchema()
+    try:
+        data = schema.load(request.get_json())
+    except ValidationError as e:
+        return jsonify({"errors": e.messages}), 400
+
+    user = UserService.create(data)
+    return jsonify(UserResponseSchema().dump(user)), 201
+```
+
+## SQLAlchemy Integration
+
+```python
+# GOOD - With marshmallow-sqlalchemy
+from marshmallow_sqlalchemy import SQLAlchemyAutoSchema
+
+class UserSchema(SQLAlchemyAutoSchema):
+    class Meta:
+        model = User
+        include_relationships = True
+        load_instance = True
+        exclude = ("hashed_password",)
+
+# Manual approach (more control)
+class UserSchema(Schema):
+    class Meta:
+        load_instance = True
+
+    id = fields.Int(dump_only=True)
+    email = fields.Email(required=True)
+
+    @post_load
+    def make_user(self, data, **kwargs):
+        return User(**data)
+```
+
+## Many Parameter
+
+```python
+# GOOD - Serialize/deserialize collections
+schema = UserSchema()
+
+# Single object
+user_data = schema.dump(user)
+user = schema.load(data)
+
+# Multiple objects
+users_data = schema.dump(users, many=True)
+users = schema.load(data_list, many=True)
+```