fastgen-cli 0.4.0__py3-none-any.whl

fastgen/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

fastgen/cli.py

@@ -0,0 +1,80 @@
+"""fastgen CLI entrypoint."""
+
+# ruff: noqa: B008  (Typer's idiomatic Option/Argument-in-default pattern)
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.table import Table
+
+from . import __version__
+from .generators.core import generate_core
+from .generators.module import generate_module
+from .generators.registry import list_registered, register_module
+from .writers import console, report
+
+app = typer.Typer(
+    name="fastgen",
+    help="FastAPI feature-based module manager (nest-cli style).",
+    no_args_is_help=True,
+)
+make_app = typer.Typer(help="Scaffold modules and core infrastructure.", no_args_is_help=True)
+app.add_typer(make_app, name="make")
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    version: bool = typer.Option(False, "--version", "-V", help="Show version and exit."),
+) -> None:
+    if version:
+        typer.echo(f"fastgen {__version__}")
+        raise typer.Exit()
+
+
+@make_app.command("module")
+def make_module(
+    feature: str = typer.Argument(..., help="Feature name, e.g. user"),
+    directory: Path = typer.Option(Path.cwd(), "--dir", "-d", help="Target project root."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview files without writing."),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing files."),
+) -> None:
+    """Scaffold a feature module and register it.
+
+    Generates a minimal module skeleton (schemas / service / router /
+    __init__) that outlines the module's shape; fill in the entity fields and
+    business logic yourself. The shared app/core/ database scaffolding and the
+    module registry are created automatically.
+    """
+    files = generate_module(feature, directory, force=force, dry_run=dry_run)
+    files += generate_core(directory, dry_run=dry_run)
+    files.append(register_module(directory, feature, dry_run=dry_run))
+    report(files)
+    skipped = [f for f in files if f.status == "skipped"]
+    if skipped and not force:
+        typer.secho(
+            f"{len(skipped)} file(s) already exist. Re-run with --force to overwrite.",
+            fg=typer.colors.YELLOW,
+        )
+
+
+@app.command("list")
+def list_modules(
+    directory: Path = typer.Option(Path.cwd(), "--dir", "-d", help="Target project root."),
+) -> None:
+    """List registered modules and their boundaries."""
+    rows = list_registered(directory)
+    table = Table(title="Registered modules")
+    table.add_column("module", style="cyan")
+    table.add_column("path", style="magenta")
+    table.add_column("description")
+    for name, import_path, doc in rows:
+        table.add_row(name, import_path, doc)
+    console.print(table)
+    if not rows:
+        typer.secho("No modules registered yet. Run `fastgen make module <name>`.", fg="yellow")
+
+
+if __name__ == "__main__":
+    app()

fastgen/generators/base.py

@@ -0,0 +1,45 @@
+"""Jinja2 rendering helpers shared by all generators."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader, StrictUndefined
+
+from ..writers import GeneratedFile, write_file
+
+TEMPLATES_DIR = Path(__file__).resolve().parent.parent / "templates"
+
+
+def _env(template_dir: str) -> Environment:
+    return Environment(
+        loader=FileSystemLoader(TEMPLATES_DIR / template_dir),
+        trim_blocks=True,
+        lstrip_blocks=True,
+        undefined=StrictUndefined,
+    )
+
+
+def render_template(template_dir: str, name: str, context: dict) -> str:
+    """Render a single ``*.j2`` file without writing anything."""
+    return _env(template_dir).get_template(name).render(**context)
+
+
+def render_tree(
+    template_dir: str,
+    context: dict,
+    dest_dir: Path,
+    *,
+    force: bool = False,
+    dry_run: bool = False,
+) -> list[GeneratedFile]:
+    """Render every ``*.j2`` file in ``template_dir`` into ``dest_dir``."""
+    src = TEMPLATES_DIR / template_dir
+    env = _env(template_dir)
+    files: list[GeneratedFile] = []
+    for tmpl in sorted(src.rglob("*.j2")):
+        rel = tmpl.relative_to(src)
+        rendered = env.get_template(str(rel)).render(**context)
+        target = dest_dir / rel.with_suffix("")
+        files.append(write_file(target, rendered, force=force, dry_run=dry_run))
+    return files

fastgen/generators/core.py

@@ -0,0 +1,43 @@
+"""Core scaffolding generator: app/core/ (config.py + database.py).
+
+Files are only generated when they are missing or empty; existing code is
+never overwritten (``force`` does not apply here).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..writers import GeneratedFile, write_file
+from .base import render_template
+
+CORE_TEMPLATE = "core"
+
+
+def _has_code(path: Path) -> bool:
+    return path.exists() and bool(path.read_text(encoding="utf-8").strip())
+
+
+def generate_core(
+    project_root: Path,
+    *,
+    dry_run: bool = False,
+) -> list[GeneratedFile]:
+    core_dir = project_root / "app" / "core"
+    files: list[GeneratedFile] = []
+
+    init_py = core_dir / "__init__.py"
+    if not init_py.exists():
+        files.append(write_file(init_py, "", dry_run=dry_run))
+
+    config_py = core_dir / "config.py"
+    if not _has_code(config_py):
+        content = render_template(CORE_TEMPLATE, "config.py.j2", {})
+        files.append(write_file(config_py, content, force=True, dry_run=dry_run))
+
+    database_py = core_dir / "database.py"
+    if not _has_code(database_py):
+        content = render_template(CORE_TEMPLATE, "database.py.j2", {})
+        files.append(write_file(database_py, content, force=True, dry_run=dry_run))
+
+    return files

fastgen/generators/module.py

@@ -0,0 +1,40 @@
+"""Feature-module generator: schemas.py + service.py + router.py + __init__.py.
+
+The skeleton only sketches the module's shape (entity, business layer, API
+boundary, shared session dependency) so AI agents can reason about it; real
+business code is filled in by the developer.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..naming import to_kebab, to_pascal, to_plural, to_snake
+from ..writers import GeneratedFile
+from .base import render_tree
+
+MODULE_TEMPLATE = "module"
+
+
+def module_context(feature: str) -> dict[str, str]:
+    snake = to_snake(feature)
+    return {
+        "pascal": to_pascal(feature),
+        "snake": snake,
+        "kebab": to_kebab(feature),
+        "plural": to_plural(snake),
+    }
+
+
+def generate_module(
+    feature: str,
+    project_root: Path,
+    *,
+    force: bool = False,
+    dry_run: bool = False,
+) -> list[GeneratedFile]:
+    snake = to_snake(feature)
+    module_dir = project_root / "app" / "modules" / snake
+    return render_tree(
+        MODULE_TEMPLATE, module_context(feature), module_dir, force=force, dry_run=dry_run
+    )

fastgen/generators/registry.py

@@ -0,0 +1,91 @@
+"""Module registry: an auto-maintained ``app/modules/__init__.py``.
+
+The registry maps each module name to its import path so AI agents (and the
+``fastgen list`` command) can discover the project's module structure at a
+glance without scanning the filesystem.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from ..naming import to_snake
+from ..writers import GeneratedFile, write_file
+
+REGISTRY_HEADER = (
+    '"""Module registry - auto-generated by fastgen. Do not edit by hand."""'
+)
+
+_MODULES_VAR = "modules"
+
+
+def registry_path(project_root: Path) -> Path:
+    return project_root / "app" / "modules" / "__init__.py"
+
+
+def read_registry(project_root: Path) -> dict[str, str]:
+    """Read the ``modules`` mapping from ``app/modules/__init__.py``."""
+    path = registry_path(project_root)
+    if not path.exists():
+        return {}
+    tree = ast.parse(path.read_text(encoding="utf-8"))
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            targets = node.targets
+        elif isinstance(node, ast.AnnAssign):
+            targets = (node.target,) if node.value is not None else ()
+        else:
+            continue
+        if any(isinstance(t, ast.Name) and t.id == _MODULES_VAR for t in targets):
+            value = ast.literal_eval(node.value)
+            return {name: path for name, path in value.items()}
+    return {}
+
+
+def registry_content(modules: dict[str, str]) -> str:
+    body = "\n".join(f'    "{name}": "{path}",' for name, path in sorted(modules.items()))
+    return (
+        f"{REGISTRY_HEADER}\n\n"
+        f"{_MODULES_VAR}: dict[str, str] = {{\n{body}\n}}\n\n"
+        '__all__ = ["' + _MODULES_VAR + '"]\n'
+    )
+
+
+def register_module(
+    project_root: Path,
+    feature: str,
+    *,
+    dry_run: bool = False,
+) -> GeneratedFile:
+    """Add ``feature`` to the registry and rewrite ``app/modules/__init__.py``."""
+    name = to_snake(feature)
+    modules = read_registry(project_root)
+    modules[name] = f"app.modules.{name}"
+    content = registry_content(modules)
+    path = registry_path(project_root)
+    if path.exists() and path.read_text(encoding="utf-8").rstrip("\n") == content.rstrip("\n"):
+        return GeneratedFile(path=path, content=content, status="skipped")
+    return write_file(path, content, force=True, dry_run=dry_run)
+
+
+def list_registered(project_root: Path) -> list[tuple[str, str, str]]:
+    """Return (name, import path, one-line docstring) for every module."""
+    modules = read_registry(project_root)
+    rows: list[tuple[str, str, str]] = []
+    for name, import_path in modules.items():
+        doc = _module_doc(project_root / "app" / "modules" / name / "__init__.py")
+        rows.append((name, import_path, doc))
+    return rows
+
+
+def _module_doc(init_file: Path) -> str:
+    if not init_file.exists():
+        return ""
+    try:
+        tree = ast.parse(init_file.read_text(encoding="utf-8"))
+    except SyntaxError:
+        return ""
+    doc = ast.get_docstring(tree) or ""
+    first_line = doc.strip().splitlines()
+    return first_line[0] if first_line else ""

fastgen/naming.py

@@ -0,0 +1,41 @@
+"""Name transformation helpers (snake_case / PascalCase / kebab-case + pluralization)."""
+
+from __future__ import annotations
+
+import re
+
+_WORD_SPLIT_RE = re.compile(r"[_\-\s]+")
+
+
+def _split(name: str) -> list[str]:
+    parts: list[str] = []
+    for chunk in _WORD_SPLIT_RE.split(name):
+        if not chunk:
+            continue
+        parts.extend(re.findall(r"[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+|\d+", chunk))
+    return parts
+
+
+def to_snake(name: str) -> str:
+    return "_".join(p.lower() for p in _split(name))
+
+
+def to_pascal(name: str) -> str:
+    return "".join(p.capitalize() for p in _split(name))
+
+
+def to_kebab(name: str) -> str:
+    return "-".join(p.lower() for p in _split(name))
+
+
+def to_plural(word: str) -> str:
+    """Simple English pluralization."""
+    if word.endswith(("s", "x", "z", "ch", "sh")):
+        return f"{word}es"
+    if word.endswith("y") and len(word) > 1 and word[-2] not in "aeiou":
+        return f"{word[:-1]}ies"
+    if word.endswith("f"):
+        return f"{word[:-1]}ves"
+    if word.endswith("fe"):
+        return f"{word[:-2]}ves"
+    return f"{word}s"

fastgen/templates/core/config.py.j2

@@ -0,0 +1,12 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings, loaded from environment / .env."""
+
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    database_url: str = "sqlite+aiosqlite:///./app.db"
+
+
+settings = Settings()

fastgen/templates/core/database.py.j2

@@ -0,0 +1,24 @@
+from collections.abc import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import (
+    AsyncAttrs,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.orm import DeclarativeBase
+
+from app.core.config import settings
+
+
+class Base(AsyncAttrs, DeclarativeBase):
+    """Declarative base shared by all ORM models."""
+
+
+engine = create_async_engine(settings.database_url, echo=False)
+async_session = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session() as session:
+        yield session

fastgen/templates/module/__init__.py.j2

@@ -0,0 +1,4 @@
+"""{{ pascal }} module."""
+from .router import router
+
+__all__ = ["router"]

fastgen/templates/module/router.py.j2

@@ -0,0 +1,10 @@
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.database import get_session
+
+SessionDep = Annotated[AsyncSession, Depends(get_session)]
+
+router = APIRouter(prefix="/{{ plural }}", tags=["{{ plural }}"])

fastgen/templates/module/schemas.py.j2

@@ -0,0 +1,5 @@
+from pydantic import BaseModel
+
+
+class {{ pascal }}(BaseModel):
+    pass

fastgen/templates/module/service.py.j2

@@ -0,0 +1,2 @@
+class {{ pascal }}Service:
+    """Business logic layer for {{ kebab }}."""

fastgen/writers.py

@@ -0,0 +1,43 @@
+"""File writing helpers with dry-run and overwrite protection."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from rich.console import Console
+
+console = Console()
+
+
+@dataclass
+class GeneratedFile:
+    path: Path
+    content: str
+    status: str = field(default="created")
+
+
+def write_file(
+    path: Path, content: str, *, force: bool = False, dry_run: bool = False
+) -> GeneratedFile:
+    if dry_run:
+        return GeneratedFile(path=path, content=content, status="dry-run")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists() and not force:
+        return GeneratedFile(path=path, content=content, status="skipped")
+    path.write_text(content if content.endswith("\n") else content + "\n")
+    return GeneratedFile(path=path, content=content, status="created")
+
+
+def report(files: list[GeneratedFile], *, dry_run: bool = False) -> None:
+    prefix = "[yellow][dry-run][/yellow] " if dry_run else ""
+    for f in files:
+        status_style = {
+            "created": "green",
+            "skipped": "yellow",
+            "dry-run": "cyan",
+        }[f.status]
+        if f.status == "skipped":
+            console.print(f"{prefix}[{status_style}][skipped][/] {f.path}")
+        else:
+            console.print(f"{prefix}[{status_style}][{f.status}][/] {f.path}")

fastgen_cli-0.4.0.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: fastgen-cli
+Version: 0.4.0
+Summary: FastAPI feature-based module manager (nest-cli style for FastAPI)
+Author-email: YIbaikaishui <162815827+YIbaikaishui@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,code-generator,fastapi,nest-cli,scaffold
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: jinja2>=3.1
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# fastgen
+
+A `nest cli`-style module manager for FastAPI: it scaffolds a minimal,
+zero-config module skeleton (entity, service, router, shared session
+dependency) and keeps a module registry so AI agents and developers can see
+the project structure at a glance. Fill in the business logic yourself.
+
+## Install
+
+```bash
+pip install fastgen-cli
+# or
+uv add fastgen-cli
+```
+
+## Usage
+
+```bash
+fastgen --help
+
+# Scaffold a feature module and register it
+fastgen make module user
+
+# List registered modules and their boundaries
+fastgen list
+```
+
+Both commands support `--dir <root>` (project root, defaults to cwd),
+`--dry-run` (preview without writing) and `--force` (overwrite existing
+skeleton files).
+
+Running `fastgen make module <feature>` generates:
+
+```
+app/
+├── core/                        # auto-created on first use
+│   ├── config.py                # pydantic-settings Settings (DATABASE_URL in .env)
+│   └── database.py              # Base (AsyncAttrs), async engine, get_session dependency
+└── modules/
+    ├── __init__.py              # module registry (auto-maintained, do not edit)
+    └── user/
+        ├── __init__.py          # re-exports router
+        ├── schemas.py           # Pydantic entity skeleton: class User(BaseModel): pass
+        ├── service.py           # business layer boundary: class UserService
+        └── router.py            # APIRouter + SessionDep (Annotated[AsyncSession, Depends(get_session)])
+```
+
+Existing code is never overwritten: `app/core/config.py` / `database.py` are
+only generated when missing or empty.
+
+## Conventions (fixed)
+
+- Modules live in `app/modules/<feature>/`, one business unit per folder.
+- The router exposes `prefix="/<plural>"` and tags; the shared session
+  dependency is imported from `app.core.database`.
+- `app/modules/__init__.py` is a fastgen-maintained registry
+  (`modules: dict[str, str]`) mapping module name to import path; `fastgen list`
+  reads it (and each module's docstring) to show the whole project.
+
+## Roadmap
+
+- Phase 1: `make module` (schemas + service skeleton) ✅
+- Phase 2: module registry + `fastgen list` ✅
+- Phase 3: `make resource` (full CRUD router), Alembic migration hints

fastgen_cli-0.4.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+fastgen/__init__.py,sha256=42STGor_9nKYXumfeV5tiyD_M8VdcddX7CEexmibPBk,22
+fastgen/cli.py,sha256=-G3i7J6HgSyreftG43Yoel-xH270D45A2bXJRlhQcAw,2821
+fastgen/naming.py,sha256=yPriPDE1rgtqrZm1cEhfVB-dm3C0FX-YWn64aJz88SI,1105
+fastgen/writers.py,sha256=kawNNLuA0AnRCDL0Rt8xxdGhG3OwzXeMQik2DwzKH8c,1348
+fastgen/generators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastgen/generators/base.py,sha256=mql3DZdz-AsywBCXzgQTtL5nGxNORBQI0eld-EYjmSY,1376
+fastgen/generators/core.py,sha256=quUG_-71zAb6s4jDy6ccE5NWWbJ4k8mi--Pt3VNpOtI,1274
+fastgen/generators/module.py,sha256=249apegLDxVoSh9d_wmkknWTQ1A9_K6RJEf_lwaTz0c,1096
+fastgen/generators/registry.py,sha256=_ER5EYA0FW4a170dHDiSc_cg3ixaeHdNODBptx47E14,3086
+fastgen/templates/core/config.py.j2,sha256=_mznhIq2ELNyNpuo9L8FOjE4sxNLBXfnnERiJVsIuzY,311
+fastgen/templates/core/database.py.j2,sha256=3YWUKP424lDWVJCQhQqLzLAZ4glBmwZlb5aJ8s2mRIY,627
+fastgen/templates/module/__init__.py.j2,sha256=40K6rOER2Wo-rE31JRikdXf4hMpFn0dnx9K1imWXDTg,76
+fastgen/templates/module/router.py.j2,sha256=l31yT7EYg7nlwcWWXC630aW6nGiCND29dUVZTae5Mdw,287
+fastgen/templates/module/schemas.py.j2,sha256=9CuJoFm18VD9gXKJ6rxNAEUm8Ivjn69CqLreSX_9vcE,73
+fastgen/templates/module/service.py.j2,sha256=JgiKlvBGI6A2KsOEfYsNrTxpQ6ZUB03SpG8FqREmVWw,75
+fastgen_cli-0.4.0.dist-info/METADATA,sha256=FbjJQ7FDIUvwjTSNHPUGeCuFOzLp1tFuCxxLnY4vO0Y,3050
+fastgen_cli-0.4.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+fastgen_cli-0.4.0.dist-info/entry_points.txt,sha256=Y_2HaNCGPIGsXOt83jVeCAsXF3sDUsiANHbs_Lya_xI,44
+fastgen_cli-0.4.0.dist-info/licenses/LICENSE,sha256=fHNgnZDcmGAp7TgjvoB_62S0vvqUsT3YNwu3uV5-BXg,1069
+fastgen_cli-0.4.0.dist-info/RECORD,,

fastgen_cli-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fastgen_cli-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fastgen = fastgen.cli:app

fastgen_cli-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YIbaikaishui
+
+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.