vflask 0.1.0__py3-none-any.whl

vflask/__init__.py

@@ -0,0 +1,5 @@
+"""vflask package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

vflask/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI package for vflask."""
+
+from vflask.cli.main import cli
+
+__all__ = ["cli"]

vflask/cli/main.py

@@ -0,0 +1,55 @@
+"""Command line interface for vflask."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from vflask.core.scaffolder import ModuleScaffolder, ProjectScaffolder, parse_field_spec
+
+
+@click.group()
+def cli() -> None:
+    """Create typed Flask projects and modules."""
+
+
+@cli.command("new")
+@click.argument("project_name")
+@click.option("--path", "destination", default=".", show_default=True, help="Directory to generate the project into.")
+def new_project(project_name: str, destination: str) -> None:
+    """Create a new project scaffold."""
+    root = Path(destination)
+    project_dir = ProjectScaffolder.render_project(project_name, root)
+    click.echo(f"✅ Created project '{project_name}' in {project_dir}")
+
+
+@cli.group("module")
+def module_group() -> None:
+    """Module-related commands."""
+
+
+@module_group.command("create")
+@click.argument("module_name")
+@click.option("-f", "--field", "fields", multiple=True, help="Field definition as name:type[:flag]. Example: name:string:index")
+@click.option("-r", "--role", "roles", multiple=True, default=("admin",), show_default=True, help="Roles allowed to access the module.")
+@click.option("--project-root", default=".", show_default=True, help="Root of the generated project.")
+def create_module(module_name: str, fields: tuple[str, ...], roles: tuple[str, ...], project_root: str) -> None:
+    """Create a Flask module inside an existing project."""
+    project_dir = Path(project_root).resolve()
+    parsed_fields = [parse_field_spec(spec) for spec in fields]
+    ModuleScaffolder.create_module(project_dir, module_name, parsed_fields, list(roles))
+    click.echo(f"✅ Created module '{module_name}' in {project_dir / 'app' / 'modules'}")
+
+
+@cli.command("watch")
+@click.option("--project-root", default=".", show_default=True, help="Project root to watch.")
+def watch(project_root: str) -> None:
+    """Start the project watcher for module docs auto-generation."""
+    from vflask.core.watcher import start_watcher
+
+    start_watcher(Path(project_root).resolve())
+
+
+if __name__ == "__main__":
+    cli()

vflask/cli/watch.py

@@ -0,0 +1,15 @@
+"""Watch command entrypoint for vflask generated projects."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from vflask.core.watcher import start_watcher
+
+
+def main() -> None:
+    start_watcher(Path.cwd())
+
+
+if __name__ == "__main__":
+    main()

vflask/core/__init__.py

@@ -0,0 +1,7 @@
+"""Core generation logic for vflask."""
+
+from vflask.core.docgen import DocGenerator
+from vflask.core.scaffolder import ModuleScaffolder, ProjectScaffolder
+from vflask.core.watcher import start_watcher
+
+__all__ = ["DocGenerator", "ModuleScaffolder", "ProjectScaffolder", "start_watcher"]

vflask/core/docgen.py

@@ -0,0 +1,49 @@
+"""Documentation generation helpers for vflask modules."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader, StrictUndefined, select_autoescape
+
+TEMPLATE_ROOT = Path(__file__).resolve().parents[1] / "templates"
+
+
+class DocGenerator:
+    """Generate markdown documentation for module folders."""
+
+    def __init__(self, project_root: str | Path):
+        self.project_root = Path(project_root).expanduser().resolve()
+        self.env = Environment(
+            loader=FileSystemLoader(str(TEMPLATE_ROOT)),
+            autoescape=select_autoescape(["html", "xml", "md"]),
+            trim_blocks=True,
+            lstrip_blocks=True,
+            undefined=StrictUndefined,
+        )
+
+    def generate_for_module(self, module_dir: str | Path) -> Path:
+        module_path = Path(module_dir).expanduser().resolve()
+        module_name = module_path.name
+        class_name = "".join(part.capitalize() for part in re.split(r"[_-]+", module_name))
+        roles = ["admin"]
+        template = self.env.get_template("module/docs.md.j2")
+        content = template.render(
+            module={
+                "name": module_name,
+                "class_name": class_name,
+                "table_name": module_name,
+                "plural_class": class_name,
+                "singular": module_name.rstrip("s"),
+                "url_prefix": f"/api/v1/{module_name}",
+            },
+            fields=[],
+            roles=roles,
+        )
+        output = module_path / "docs.md"
+        output.write_text(content, encoding="utf-8")
+        return output
+
+
+__all__ = ["DocGenerator"]

vflask/core/scaffolder.py

@@ -0,0 +1,203 @@
+"""Scaffolding logic for creating typed Flask projects and modules."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+TEMPLATE_ROOT = Path(__file__).resolve().parents[1] / "templates"
+
+
+@dataclass(slots=True)
+class FieldSpec:
+    name: str
+    type: str
+    nullable: bool = False
+    unique: bool = False
+    index: bool = False
+    default: str | None = None
+
+    @property
+    def sqlalchemy_type(self) -> str:
+        mapping = {
+            "string": "db.String(255)",
+            "text": "db.Text",
+            "integer": "db.Integer",
+            "int": "db.Integer",
+            "float": "db.Float",
+            "decimal": "db.Numeric(10, 2)",
+            "boolean": "db.Boolean",
+            "bool": "db.Boolean",
+            "date": "db.Date",
+            "datetime": "db.DateTime",
+            "json": "db.JSON",
+            "uuid": "db.String(36)",
+        }
+        return mapping.get(self.type.lower(), "db.String(255)")
+
+
+def parse_field_spec(spec: str) -> dict[str, Any]:
+    if not spec or ":" not in spec:
+        raise ValueError(f"Invalid field definition: {spec!r}. Use name:type[:flag]")
+
+    name, type_name, *flags = spec.split(":")
+    name = name.strip()
+    type_name = (type_name or "string").strip().lower()
+    field = {
+        "name": name,
+        "type": type_name,
+        "nullable": True,
+        "unique": False,
+        "index": False,
+        "default": None,
+    }
+
+    for flag in flags:
+        cleaned = flag.strip().lower()
+        if not cleaned:
+            continue
+        if cleaned in {"required", "notnull", "nonnullable"}:
+            field["nullable"] = False
+        elif cleaned in {"unique"}:
+            field["unique"] = True
+        elif cleaned in {"index"}:
+            field["index"] = True
+        elif cleaned.startswith("default="):
+            field["default"] = cleaned.split("=", 1)[1]
+        elif cleaned in {"nullable"}:
+            field["nullable"] = True
+
+    if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name):
+        raise ValueError(f"Invalid field name: {name!r}")
+
+    return field
+
+
+class ProjectScaffolder:
+    """Scaffold a generated Flask project from Jinja2 templates."""
+
+    @staticmethod
+    def render_project(project_name: str, destination: str | Path = ".") -> Path:
+        root = Path(destination).expanduser().resolve()
+        name = project_name.strip()
+        if not name:
+            raise ValueError("Project name cannot be empty.")
+
+        project_dir = root if root.name == name else root / name
+        project_dir.mkdir(parents=True, exist_ok=True)
+
+        env = Environment(
+            loader=FileSystemLoader(str(TEMPLATE_ROOT)),
+            autoescape=select_autoescape(["html", "xml", "md"]),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+        files_to_render = {
+            "project/README.md.j2": project_dir / "README.md",
+            "project/app/cli.py.j2": project_dir / "app" / "cli.py",
+            "project/app/watcher.py.j2": project_dir / "app" / "watcher.py",
+            "project/scripts/start.sh.j2": project_dir / "scripts" / "start.sh",
+            "project/scripts/push.sh.j2": project_dir / "scripts" / "push.sh",
+            "project/scripts/help.sh.j2": project_dir / "scripts" / "help.sh",
+            "project/tests/conftest.py.j2": project_dir / "tests" / "conftest.py",
+            "project/tests/helpers.py.j2": project_dir / "tests" / "helpers.py",
+            "project/migrations/env.py.j2": project_dir / "migrations" / "env.py",
+        }
+
+        for template_name, output_path in files_to_render.items():
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            content = env.get_template(template_name).render(project_name=name)
+            output_path.write_text(content, encoding="utf-8")
+            if template_name.endswith(".sh.j2"):
+                os.chmod(output_path, 0o755)
+
+        generated_files = {
+            "requirements.txt": "click==8.1.7\nFlask==3.1.0\nFlask-SQLAlchemy==3.1.1\nFlask-Migrate==4.0.7\nFlask-JWT-Extended==4.7.1\nFlask-Cors==5.0.0\npsycopg[binary]==3.3.6\npython-dotenv==1.0.1\nwatchdog==4.0.1\nrich==13.0.0\ngunicorn==23.0.0\npytest==8.3.1\n",
+            ".env.example": "FLASK_APP=app:create_app\nFLASK_DEBUG=1\nSECRET_KEY=changeme\nDATABASE_URL=postgresql+psycopg://app:app@localhost:5432/app\nJWT_SECRET_KEY=super-secret\nREDIS_URL=redis://localhost:6379/0\nPORT=5000\n",
+            "docker-compose.yml": """services:\n  db:\n    image: postgres:16\n    environment:\n      POSTGRES_DB: app\n      POSTGRES_USER: app\n      POSTGRES_PASSWORD: app\n    ports:\n      - \"5432:5432\"\n    volumes:\n      - postgres_data:/var/lib/postgresql/data\n\n  redis:\n    image: redis:7-alpine\n    ports:\n      - \"6379:6379\"\n\nvolumes:\n  postgres_data:\n""",
+            "app/__init__.py": """from __future__ import annotations\n\nfrom flask import Flask\n\nfrom app.config import AppConfig\nfrom app.extensions import db, jwt, migrate\n\n\ndef create_app(config_object: type | None = None) -> Flask:\n    app = Flask(__name__)\n    app.config.from_object(config_object or AppConfig)\n\n    db.init_app(app)\n    jwt.init_app(app)\n    migrate.init_app(app, db)\n\n    from app.modules import register_modules\n\n    register_modules(app)\n\n    @app.get(\"/api/v1/health\")\n    def healthcheck() -> tuple[dict, int]:\n        return {\"status\": \"ok\"}, 200\n\n    return app\n""",
+            "app/config.py": """from __future__ import annotations\n\nimport os\n\n\nclass AppConfig:\n    SECRET_KEY = os.getenv(\"SECRET_KEY\", \"development-secret\")\n    SQLALCHEMY_DATABASE_URI = os.getenv(\"DATABASE_URL\", \"postgresql+psycopg://app:app@localhost:5432/app\")\n    SQLALCHEMY_TRACK_MODIFICATIONS = False\n    JWT_SECRET_KEY = os.getenv(\"JWT_SECRET_KEY\", \"jwt-secret\")\n    JSON_SORT_KEYS = False\n\n\nclass TestingConfig(AppConfig):\n    TESTING = True\n    SQLALCHEMY_DATABASE_URI = \"sqlite:///:memory:\"\n""",
+            "app/extensions.py": """from __future__ import annotations\n\nfrom flask_jwt_extended import JWTManager\nfrom flask_migrate import Migrate\nfrom flask_sqlalchemy import SQLAlchemy\n\ndb = SQLAlchemy()\nmigrate = Migrate()\njwt = JWTManager()\n""",
+            "app/base.py": """from __future__ import annotations\n\nfrom functools import wraps\nfrom typing import Any\n\nfrom flask import jsonify, request\nfrom flask_jwt_extended import get_jwt_identity, jwt_required\n\n\ndef api_ok(data: Any | None = None, msg: str = \"success\", status: int = 200):\n    return jsonify({\"status\": status, \"msg\": msg, \"data\": data}), status\n\n\ndef api_error(msg: str, status: int = 400):\n    return jsonify({\"status\": status, \"msg\": msg, \"data\": None}), status\n\n\ndef paginated_response(data: list[Any], total: int, page: int, limit: int):\n    return api_ok({\"items\": data, \"total\": total, \"page\": page, \"limit\": limit})\n\n\ndef auth_required(view):\n    @wraps(view)\n    @jwt_required()\n    def wrapper(*args, **kwargs):\n        return view(*args, **kwargs)\n\n    return wrapper\n\n\ndef role_required(*roles: str):\n    def decorator(view):\n        @wraps(view)\n        @jwt_required()\n        def wrapper(*args, **kwargs):\n            identity = get_jwt_identity()\n            if not identity:\n                return api_error(\"Authentication required\", 401)\n            if roles and identity not in roles:\n                return api_error(\"Forbidden\", 403)\n            return view(*args, **kwargs)\n\n        return wrapper\n\n    return decorator\n\n
+def get_user_id() -> int:\n    return int(get_jwt_identity())\n""",
+            "app/shared/__init__.py": """from app.shared.models import Role, User\n""",
+            "app/shared/mixins.py": """from __future__ import annotations\n\nfrom datetime import datetime\n\nfrom app.extensions import db\n\n\nclass TimestampMixin:\n    created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False)\n    updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)\n\n\nclass SoftDeleteMixin:\n    deleted_at = db.Column(db.DateTime, nullable=True, default=None)\n\n    def soft_delete(self) -> None:\n        self.deleted_at = datetime.utcnow()\n\n    def restore(self) -> None:\n        self.deleted_at = None\n""",
+            "app/shared/models.py": """from __future__ import annotations\n\nfrom datetime import datetime\n\nfrom werkzeug.security import check_password_hash, generate_password_hash\n\nfrom app.extensions import db\nfrom app.shared.mixins import SoftDeleteMixin, TimestampMixin\n\n\nclass Role(db.Model):\n    __tablename__ = \"roles\"\n\n    id = db.Column(db.Integer, primary_key=True)\n    name = db.Column(db.String(80), unique=True, nullable=False, index=True)\n    description = db.Column(db.String(255), nullable=True)\n\n\nuser_roles = db.Table(\n    \"user_roles\",\n    db.Column(\"user_id\", db.Integer, db.ForeignKey(\"users.id\"), primary_key=True),\n    db.Column(\"role_id\", db.Integer, db.ForeignKey(\"roles.id\"), primary_key=True),\n)\n\n\nclass User(SoftDeleteMixin, TimestampMixin, db.Model):\n    __tablename__ = \"users\"\n\n    id = db.Column(db.Integer, primary_key=True)\n    email = db.Column(db.String(255), unique=True, nullable=False, index=True)\n    password_hash = db.Column(db.String(255), nullable=False)\n    name = db.Column(db.String(120), nullable=False)\n    is_active = db.Column(db.Boolean, default=True, nullable=False)\n    roles = db.relationship(\"Role\", secondary=user_roles, backref=db.backref(\"users\", lazy=\"dynamic\"))\n\n    def set_password(self, password: str) -> None:\n        self.password_hash = generate_password_hash(password)\n\n    def check_password(self, password: str) -> bool:\n        return check_password_hash(self.password_hash, password)\n\n    def to_dict(self) -> dict:\n        return {\n            \"id\": self.id,\n            \"email\": self.email,\n            \"name\": self.name,\n            \"isActive\": self.is_active,\n            \"roles\": [role.name for role in self.roles],\n        }\n""",
+            "app/shared/rbac.py": """from __future__ import annotations\n\nfrom app.extensions import db\nfrom app.shared.models import Role, User\n\n\nclass RBACService:\n    @staticmethod\n    def seed_roles() -> None:\n        defaults = [\n            (\"admin\", \"Full access\"),\n            (\"editor\", \"Can edit records\"),\n            (\"viewer\", \"Read-only access\"),\n        ]\n        for name, description in defaults:\n            if not db.session.query(Role).filter_by(name=name).first():\n                db.session.add(Role(name=name, description=description))\n        db.session.commit()\n\n    @staticmethod\n    def assign_role(user: User, role_name: str) -> None:\n        role = db.session.query(Role).filter_by(name=role_name).first()\n        if role and role not in user.roles:\n            user.roles.append(role)\n            db.session.commit()\n\n    @staticmethod\n    def user_has_role(user: User, *required_roles: str) -> bool:\n        if not required_roles:\n            return True\n        if not user:\n            return False\n        names = {role.name for role in user.roles}\n        return bool(set(required_roles) & names)\n""",
+            "app/modules/__init__.py": """from __future__ import annotations\n\nfrom importlib import import_module\nfrom pathlib import Path\n\nfrom flask import Flask\n\n\ndef register_modules(app: Flask) -> None:\n    modules_dir = Path(__file__).resolve().parent\n    for child in sorted(modules_dir.iterdir()):\n        if child.is_dir() and (child / \"routes.py\").exists():\n            module = import_module(f\"app.modules.{child.name}.routes\")\n            if hasattr(module, \"register_routes\"):\n                module.register_routes(app)\n""",
+            "app/modules/.gitkeep": "",
+        }
+
+        for relative_path, content in generated_files.items():
+            file_path = project_dir / relative_path
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+            if relative_path.endswith(".gitkeep"):
+                file_path.touch(exist_ok=True)
+                continue
+            file_path.write_text(content, encoding="utf-8")
+
+        return project_dir
+
+
+class ModuleScaffolder:
+    """Create a module inside a generated Flask project."""
+
+    @staticmethod
+    def create_module(project_root: str | Path, module_name: str, fields: list[dict[str, Any]] | None = None, roles: list[str] | None = None) -> Path:
+        root = Path(project_root).expanduser().resolve()
+        module_key = re.sub(r"[^a-zA-Z0-9_]+", "_", module_name).strip("_").lower() or "module"
+        class_name = "".join(part.capitalize() for part in module_key.split("_"))
+        plural_name = module_key if module_key.endswith("s") else f"{module_key}s"
+        singular_name = module_key
+
+        module_dir = root / "app" / "modules" / plural_name
+        module_dir.mkdir(parents=True, exist_ok=True)
+
+        env = Environment(
+            loader=FileSystemLoader(str(TEMPLATE_ROOT)),
+            autoescape=select_autoescape(["html", "xml", "md"]),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+        context = {
+            "module": {
+                "name": module_key,
+                "plural_class": class_name if class_name.endswith("s") else class_name,
+                "class_name": class_name,
+                "table_name": plural_name,
+                "singular": singular_name,
+                "url_prefix": f"/api/v1/{plural_name}",
+            },
+            "fields": [
+                {
+                    **field,
+                    "sqlalchemy_type": FieldSpec(**field).sqlalchemy_type,
+                }
+                for field in (fields or [])
+            ],
+            "roles": list(roles or ["admin"]),
+        }
+
+        for template_name, out_name in {
+            "module/__init__.py.j2": "__init__.py",
+            "module/models.py.j2": "models.py",
+            "module/services.py.j2": "service.py",
+            "module/handlers.py.j2": "handlers.py",
+            "module/routes.py.j2": "routes.py",
+            "module/docs.md.j2": "docs.md",
+            "module/test_module.py.j2": "test_module.py",
+        }.items():
+            content = env.get_template(template_name).render(**context)
+            (module_dir / out_name).write_text(content, encoding="utf-8")
+
+        return module_dir
+
+
+__all__ = ["FieldSpec", "ProjectScaffolder", "ModuleScaffolder", "parse_field_spec"]

vflask/core/watcher.py

@@ -0,0 +1,68 @@
+"""Watch for generated module changes and regenerate docs."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from rich.console import Console
+from watchdog.events import FileSystemEvent, FileSystemEventHandler
+from watchdog.observers import Observer
+
+console = Console()
+
+
+class ModuleHandler(FileSystemEventHandler):
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+        self.debounce: dict[str, float] = {}
+
+    def on_modified(self, event: FileSystemEvent) -> None:
+        if event.is_directory:
+            return
+        path = Path(event.src_path)
+        if path.name != "handlers.py" or "__pycache__" in path.parts:
+            return
+
+        now = time.time()
+        key = str(path)
+        if key in self.debounce and now - self.debounce[key] < 0.5:
+            return
+        self.debounce[key] = now
+
+        console.print(f"  [yellow]📝[/] {path.relative_to(self.project_root)}")
+        self._regenerate_docs(path.parent)
+
+    def _regenerate_docs(self, module_dir: Path) -> None:
+        try:
+            from vflask.core.docgen import DocGenerator
+
+            docgen = DocGenerator(self.project_root)
+            docgen.generate_for_module(module_dir)
+            console.print(f"  [green]📚[/] {module_dir.name}/docs.md regenerated")
+        except Exception as exc:  # pragma: no cover
+            console.print(f"  [red]✗[/] Doc error: {exc}")
+
+
+def start_watcher(project_root: Path) -> None:
+    observer = Observer()
+    handler = ModuleHandler(Path(project_root).resolve())
+    modules_path = Path(project_root).resolve() / "app" / "modules"
+    if not modules_path.exists():
+        console.print(f"[yellow]No modules directory at {modules_path}; creating it.[/]")
+        modules_path.mkdir(parents=True, exist_ok=True)
+
+    observer.schedule(handler, str(modules_path), recursive=True)
+    observer.start()
+    console.print(f"[bold green]👁️  Watching {modules_path}[/]")
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        observer.stop()
+    finally:
+        observer.join()
+
+
+__all__ = ["ModuleHandler", "start_watcher"]

vflask/templates/module/__init__.py.j2

@@ -0,0 +1 @@
+"""{{ module.plural_class }} module."""

vflask/templates/module/docs.md.j2

@@ -0,0 +1,43 @@
+# {{ module.plural_class }} Module
+
+Auto-generated documentation for the `{{ module.table_name }}` module.
+
+## Model
+
+**{{ module.class_name }}**
+
+| Field | Type | Nullable | Unique | Index |
+|-------|------|----------|--------|-------|
+| id | Integer | No | Yes | Yes |
+{% for field in fields %}
+| {{ field.name }} | {{ field.type }} | {{ "Yes" if field.nullable else "No" }} | {{ "Yes" if field.unique else "No" }} | {{ "Yes" if field.index else "No" }} |
+{% endfor %}
+| created_at | DateTime | No | No | No |
+| updated_at | DateTime | No | No | No |
+| deleted_at | DateTime | Yes | No | No |
+
+## Endpoints
+
+| Method | Path | Auth | Roles | Description |
+|--------|------|------|-------|-------------|
+| POST | `{{ module.url_prefix }}/list` | ✅ | {{ roles|join(', ') }} | List {{ module.table_name }} |
+| POST | `{{ module.url_prefix }}/` | ✅ | {{ roles|join(', ') }} | Create {{ module.singular }} |
+| GET | `{{ module.url_prefix }}/<id>` | ✅ | Any | Get {{ module.singular }} |
+| PUT | `{{ module.url_prefix }}/<id>` | ✅ | {{ roles|join(', ') }} | Update {{ module.singular }} |
+| DELETE | `{{ module.url_prefix }}/<id>` | ✅ | {{ roles|join(', ') }} | Delete {{ module.singular }} |
+| POST | `{{ module.url_prefix }}/bulk-delete` | ✅ | {{ roles|join(', ') }} | Bulk delete |
+
+## Usage Examples
+
+```bash
+# List {{ module.table_name }}
+curl -X POST http://localhost:5000{{ module.url_prefix }}/list \\
+  -H "Authorization: Bearer $TOKEN" \\
+  -H "Content-Type: application/json" \\
+  -d '{"pagination": {"page": 1, "limit": 10}, "columns": [], "search": ""}'
+
+# Create {{ module.singular }}
+curl -X POST http://localhost:5000{{ module.url_prefix }}/ \\
+  -H "Authorization: Bearer $TOKEN" \\
+  -H "Content-Type: application/json" \\
+  -d '{ {% for field in fields %}"{{ field.name }}": ...{% if not loop.last %}, {% endif %}{% endfor %} }'

vflask/templates/module/handlers.py.j2

@@ -0,0 +1,73 @@
+"""{{ module.plural_class }} request handlers."""
+
+from __future__ import annotations
+
+from flask import request
+
+from app.base import api_error, api_ok, paginated_response
+from app.modules.{{ module.table_name }}.service import {{ module.class_name }}Service
+
+
+class {{ module.class_name }}Handler:
+    """Handle HTTP requests for {{ module.plural_class }}."""
+
+    def __init__(self) -> None:
+        self.service = {{ module.class_name }}Service()
+
+    def list(self) -> tuple:
+        """List {{ module.table_name }} with pagination and filters."""
+        req = request.get_json(silent=True) or {}
+        if "pagination" not in req:
+            return api_error("Invalid payload: pagination required")
+        try:
+            items, total = self.service.list_{{ module.table_name }}(req)
+        except ValueError as e:
+            return api_error(str(e))
+        except Exception as e:
+            return api_error(str(e), 500)
+        return paginated_response(
+            [i.to_dict() for i in items],
+            total,
+            req["pagination"]["page"],
+            req["pagination"]["limit"],
+        )
+
+    def create(self) -> tuple:
+        """Create a new {{ module.singular }}."""
+        body = request.get_json(silent=True) or {}
+        if not body:
+            return api_error("Invalid payload")
+        try:
+            item = self.service.create_{{ module.singular }}(body)
+        except Exception as e:
+            return api_error(str(e), 500)
+        return api_ok(item.to_dict(), msg="created", status=201)
+
+    def get(self, item_id: int) -> tuple:
+        """Get a single {{ module.singular }}."""
+        item = self.service.get_{{ module.singular }}(item_id)
+        if not item or item.deleted_at:
+            return api_error("{{ module.class_name }} not found", 404)
+        return api_ok(item.to_dict())
+
+    def update(self, item_id: int) -> tuple:
+        """Update a {{ module.singular }}."""
+        body = request.get_json(silent=True) or {}
+        item = self.service.update_{{ module.singular }}(item_id, body)
+        if not item:
+            return api_error("{{ module.class_name }} not found", 404)
+        return api_ok(item.to_dict(), msg="updated")
+
+    def delete(self, item_id: int) -> tuple:
+        """Soft delete a {{ module.singular }}."""
+        if not self.service.delete_{{ module.singular }}(item_id):
+            return api_error("{{ module.class_name }} not found", 404)
+        return api_ok(msg="deleted")
+
+    def bulk_delete(self) -> tuple:
+        """Soft delete multiple {{ module.table_name }}."""
+        body = request.get_json(silent=True) or {}
+        if "ids" not in body or not isinstance(body["ids"], list):
+            return api_error("Invalid payload: ids array required")
+        count = self.service.bulk_delete(body["ids"])
+        return api_ok({"deleted": count}, msg="bulk deleted successfully")

vflask/templates/module/models.py.j2

@@ -0,0 +1,32 @@
+"""{{ module.plural_class }} models."""
+
+from __future__ import annotations
+
+from app.extensions import db
+from app.shared.mixins import SoftDeleteMixin, TimestampMixin
+
+
+class {{ module.class_name }}(SoftDeleteMixin, TimestampMixin, db.Model):
+    """{{ module.class_name }} model."""
+    __tablename__ = "{{ module.table_name }}"
+
+    id = db.Column(db.Integer, primary_key=True)
+{% for field in fields %}
+    {{ field.name }} = db.Column({{ field.sqlalchemy_type }}{% if field.nullable %}, nullable=True{% else %}, nullable=False{% endif %}{% if field.unique %}, unique=True{% endif %}{% if field.index %}, index=True{% endif %}{% if field.default %}, default={{ field.default }}{% endif %})
+{% endfor %}
+{% if not fields %}
+    name = db.Column(db.String(255), nullable=False, index=True)
+{% endif %}
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+{% for field in fields %}
+            "{{ field.name }}": self.{{ field.name }},
+{% endfor %}
+{% if not fields %}
+            "name": self.name,
+{% endif %}
+            "createdAt": self.created_at.isoformat(),
+            "updatedAt": self.updated_at.isoformat(),
+        }

vflask/templates/module/routes.py.j2

@@ -0,0 +1,58 @@
+"""{{ module.plural_class }} routes."""
+
+from __future__ import annotations
+
+from flask import Blueprint
+
+from app.base import auth_required, role_required
+from app.modules.{{ module.table_name }}.handlers import {{ module.class_name }}Handler
+
+bp = Blueprint("{{ module.table_name }}", __name__, url_prefix="{{ module.url_prefix }}")
+handler = {{ module.class_name }}Handler()
+
+
+@bp.post("/list")
+@auth_required
+@role_required({% for role in roles %}"{{ role }}"{% if not loop.last %}, {% endif %}{% endfor %})
+def list_{{ module.table_name }}() -> tuple:
+    """List {{ module.table_name }}."""
+    return handler.list()
+
+
+@bp.post("/")
+@auth_required
+@role_required({% for role in roles %}"{{ role }}"{% if not loop.last %}, {% endif %}{% endfor %})
+def create_{{ module.singular }}() -> tuple:
+    """Create {{ module.singular }}."""
+    return handler.create()
+
+
+@bp.get("/<int:item_id>")
+@auth_required
+def get_{{ module.singular }}(item_id: int) -> tuple:
+    """Get {{ module.singular }} by ID."""
+    return handler.get(item_id)
+
+
+@bp.put("/<int:item_id>")
+@auth_required
+@role_required({% for role in roles %}"{{ role }}"{% if not loop.last %}, {% endif %}{% endfor %})
+def update_{{ module.singular }}(item_id: int) -> tuple:
+    """Update {{ module.singular }}."""
+    return handler.update(item_id)
+
+
+@bp.delete("/<int:item_id>")
+@auth_required
+@role_required({% for role in roles %}"{{ role }}"{% if not loop.last %}, {% endif %}{% endfor %})
+def delete_{{ module.singular }}(item_id: int) -> tuple:
+    """Delete {{ module.singular }}."""
+    return handler.delete(item_id)
+
+
+@bp.post("/bulk-delete")
+@auth_required
+@role_required({% for role in roles %}"{{ role }}"{% if not loop.last %}, {% endif %}{% endfor %})
+def bulk_delete_{{ module.table_name }}() -> tuple:
+    """Bulk delete {{ module.table_name }}."""
+    return handler.bulk_delete()