fastapp-cli 0.1.0__py3-none-any.whl

fastapp_cli/__init__.py

@@ -0,0 +1,3 @@
+"""fastapp-cli: FastAPI 项目脚手架."""
+
+__version__ = "0.1.0"

fastapp_cli/create.py

@@ -0,0 +1,157 @@
+"""``fastapp create`` 命令实现.
+
+流程：校验 → 交互补全 → 渲染 → git init → 输出下一步指引。
+"""
+
+from __future__ import annotations
+
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+import typer
+
+from fastapp_cli import __version__
+from fastapp_cli import prompts
+from fastapp_cli.naming import validate_project_name
+from fastapp_cli.render import render_project
+
+FILE_COUNT_EXCLUDE = {".git"}
+
+
+def _git_user_name() -> str | None:
+    """读取 git 全局配置中的 user.name，失败返回 None."""
+    try:
+        result = subprocess.run(
+            ["git", "config", "user.name"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        name = result.stdout.strip()
+        return name or None
+    except (subprocess.CalledProcessError, FileNotFoundError, OSError):
+        return None
+
+
+def _count_files(out_dir: Path) -> int:
+    return sum(
+        1 for p in out_dir.rglob("*")
+        if p.is_file() and not any(part in FILE_COUNT_EXCLUDE for part in p.parts)
+    )
+
+
+def _git_init(project_dir: Path) -> bool:
+    """初始化 git 仓库，失败时告警但不阻塞."""
+    try:
+        subprocess.run(
+            ["git", "init", "-q"],
+            cwd=project_dir,
+            capture_output=True,
+            check=True,
+        )
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError, OSError) as exc:
+        typer.secho(f"⚠ git init 失败，已跳过：{exc}", fg=typer.colors.YELLOW)
+        return False
+
+
+def create(
+    project_name: str = typer.Argument(
+        ..., help="项目名：小写字母/数字/连字符，如 my-server（应用包固定位 app）"
+    ),
+    description: str = typer.Option(
+        None,
+        "--description",
+        help="项目描述（未提供时交互提问）",
+    ),
+    pm2: bool = typer.Option(
+        None,
+        "--pm2/--no-pm2",
+        help="是否生成 pm2.config.json（未指定时交互提问）",
+    ),
+    docker: bool = typer.Option(
+        None,
+        "--docker/--no-docker",
+        help="是否生成 Dockerfile（未指定时交互提问）",
+    ),
+    python_version: str = typer.Option(
+        "3.12",
+        "--python",
+        help="生成项目的目标 Python 版本",
+    ),
+    author: str = typer.Option(
+        None,
+        "--author",
+        help="作者署名（默认取 git config user.name）",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="目标目录已存在时覆盖重建",
+    ),
+    no_git: bool = typer.Option(
+        False,
+        "--no-git",
+        help="跳过 git init",
+    ),
+) -> None:
+    """生成一个完整、可直接运行的 FastAPI 项目."""
+    # 1. 校验
+    try:
+        name = validate_project_name(project_name)
+    except ValueError as exc:
+        typer.secho(f"✘ {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from exc
+
+    project_dir = Path.cwd() / name
+    if project_dir.exists():
+        if not force:
+            typer.secho(
+                f"✘ 目标目录已存在：{project_dir}（使用 --force 覆盖重建）",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(code=1)
+        typer.secho(f"⚠ 覆盖重建已存在目录：{project_dir}", fg=typer.colors.YELLOW)
+        import shutil
+
+        shutil.rmtree(project_dir)
+
+    # 2. 交互补全（flag 已提供则跳过）
+    desc = prompts.ask_description(description)
+    use_pm2 = prompts.ask_use_pm2(pm2)
+    use_docker = prompts.ask_use_docker(docker)
+    author_name = author or _git_user_name() or "fastapp-cli"
+
+    # 3. 渲染
+    ctx: dict[str, object] = {
+        "project_name": name,
+        "project_description": desc,
+        "python_version": python_version,
+        "author_name": author_name,
+        "use_pm2": use_pm2,
+        "use_docker": use_docker,
+        "year": datetime.now(timezone.utc).year,
+        "fastapp_cli_version": __version__,
+    }
+    try:
+        render_project(project_dir, ctx)
+    except RuntimeError as exc:
+        typer.secho(f"✘ 渲染失败：{exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from exc
+
+    # 4. git init
+    if not no_git:
+        if _git_init(project_dir):
+            typer.secho("✔ 已初始化 git 仓库", fg=typer.colors.GREEN)
+
+    # 5. 输出指引
+    typer.secho(
+        f"✔ 生成项目 {name}/（{_count_files(project_dir)} 个文件）",
+        fg=typer.colors.GREEN,
+    )
+    typer.echo("下一步：")
+    typer.echo(f"  cd {name} && uv sync")
+    typer.echo("  make dev        # 或 uv run uvicorn app.main:app --reload")
+    typer.echo("  访问 /api/v1/docs 查看接口文档")

fastapp_cli/main.py

@@ -0,0 +1,33 @@
+"""fastapp CLI 入口."""
+
+from __future__ import annotations
+
+import typer
+
+from fastapp_cli import __version__
+from fastapp_cli.create import create
+
+app = typer.Typer(
+    name="fastapp",
+    help="FastAPI 项目脚手架：一条命令生成完整可运行的 FastAPI 工程",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@app.callback()
+def _root() -> None:
+    """fastapp CLI."""
+
+
+@app.command()
+def version() -> None:
+    """显示版本号."""
+    typer.echo(f"fastapp-cli {__version__}")
+
+
+app.command()(create)
+
+
+if __name__ == "__main__":
+    app()

fastapp_cli/naming.py

@@ -0,0 +1,39 @@
+"""project_name 命名校验.
+
+应用包名固定位 ``app``，``project_name`` 仅用于目录名与 pyproject name：
+小写字母 / 数字 / 连字符，且不以连字符开头或结尾。
+"""
+
+from __future__ import annotations
+
+import re
+
+PROJECT_NAME_RE = re.compile(r"^[a-z][a-z0-9]*(-[a-z0-9]+)*$")
+
+MAX_LENGTH = 64
+
+
+def validate_project_name(name: str) -> str:
+    """校验 project_name，非法时抛出 ValueError.
+
+    规则：
+    - 非空，长度 <= 64
+    - 仅小写字母 / 数字 / 连字符
+    - 以小写字母开头，不以连字符开头或结尾，不含连续连字符
+
+    :param name: 项目名，如 ``my-server``
+    :return: 校验通过的项目名
+    :raises ValueError: 名称非法
+    """
+    name = (name or "").strip()
+    if not name:
+        raise ValueError("项目名不能为空")
+    if len(name) > MAX_LENGTH:
+        raise ValueError(f"项目名过长（最多 {MAX_LENGTH} 字符）：{name}")
+    if not PROJECT_NAME_RE.match(name):
+        raise ValueError(
+            f"项目名非法：{name!r}。"
+            "仅允许小写字母、数字与连字符，须以字母开头，"
+            "不能以连字符开头/结尾或包含连续连字符，示例：my-server"
+        )
+    return name

fastapp_cli/prompts.py

@@ -0,0 +1,35 @@
+"""混合模式交互提问.
+
+关键项（描述 / pm2 / Dockerfile）在未通过 flag 提供时交互提问；
+flag 已提供则跳过提问，实现零交互。
+"""
+
+from __future__ import annotations
+
+import typer
+
+DEFAULT_DESCRIPTION = "A FastAPI project created by fastapp-cli"
+
+
+def ask_description(provided: str | None) -> str:
+    """获取项目描述：flag 已提供则直接使用，否则交互提问."""
+    if provided:
+        return provided
+    return typer.prompt(
+        "项目描述",
+        default=DEFAULT_DESCRIPTION,
+    )
+
+
+def ask_use_pm2(provided: bool | None) -> bool:
+    """是否生成 pm2 配置：未指定时交互提问."""
+    if provided is not None:
+        return provided
+    return typer.confirm("是否包含 pm2 配置?", default=False)
+
+
+def ask_use_docker(provided: bool | None) -> bool:
+    """是否生成 Dockerfile：未指定时交互提问."""
+    if provided is not None:
+        return provided
+    return typer.confirm("是否包含 Dockerfile?", default=False)

fastapp_cli/render.py

@@ -0,0 +1,130 @@
+"""Jinja2 模板渲染引擎.
+
+- 模板随包发布，通过 ``importlib.resources`` 加载，离线可用；
+- ``.j2`` 后缀文件渲染并剥离后缀，其余文件原样拷贝；
+- 渲染完成后自检输出文件中无 ``{{`` / ``{%`` 残留，发现即报错。
+"""
+
+from __future__ import annotations
+
+import shutil
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import jinja2
+from jinja2 import Environment, FileSystemLoader
+
+TEMPLATES_PACKAGE = "fastapp_cli.templates"
+PROJECT_TEMPLATE_DIR = "project"
+
+RENDER_SUFFIX = ".j2"
+
+JINJA_ENV = Environment(
+    loader=FileSystemLoader("/"),  # 实际以绝对路径渲染单个文件，此处仅占位
+    keep_trailing_newline=True,
+    undefined=jinja2.StrictUndefined,
+)
+
+
+def template_root() -> Path:
+    """返回包内项目模板根目录（发布后随 wheel 分发）."""
+    traversable = resources.files(TEMPLATES_PACKAGE) / PROJECT_TEMPLATE_DIR
+    # as_file 支持压缩包场景；常规 wheel/开发目录下为真实路径
+    with resources.as_file(traversable) as path:
+        return Path(path)
+
+
+def render_string(template_text: str, ctx: dict[str, Any]) -> str:
+    """渲染单段模板文本."""
+    return JINJA_ENV.from_string(template_text).render(**ctx)
+
+
+def _iter_template_files(root: Path) -> list[Path]:
+    """递归收集模板文件（跳过目录与 .gitkeep 空占位保留处理）."""
+    return sorted(p for p in root.rglob("*") if p.is_file())
+
+
+def render_project(
+    out_dir: Path,
+    ctx: dict[str, Any],
+    *,
+    template_dir: Path | None = None,
+) -> list[Path]:
+    """渲染整个项目模板到目标目录.
+
+    :param out_dir: 输出目录（须不存在或已清空）
+    :param ctx: 模板变量
+    :param template_dir: 模板根目录，默认使用包内模板
+    :return: 实际写出的文件路径列表（相对 out_dir）
+    :raises RuntimeError: 渲染产物中存在 Jinja 残留标记
+    """
+    root = template_dir if template_dir is not None else template_root()
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    written: list[Path] = []
+    for src in _iter_template_files(root):
+        rel = src.relative_to(root)
+        dest = out_dir / rel
+
+        # .j2 后缀剥离：main.py.j2 -> main.py
+        if rel.suffix == RENDER_SUFFIX:
+            dest = dest.with_suffix("")
+
+        dest.parent.mkdir(parents=True, exist_ok=True)
+
+        if rel.suffix == RENDER_SUFFIX:
+            text = src.read_text(encoding="utf-8")
+            rendered = render_string(text, ctx)
+            # 条件文件：模板整体被 {% if %} 包裹，条件不满足时渲染结果为空 -> 跳过生成
+            if not rendered.strip():
+                continue
+            dest.write_text(rendered, encoding="utf-8")
+            _assert_no_jinja_residue(dest)
+            # shell 脚本一律保持可执行位
+            if dest.suffix == ".sh":
+                dest.chmod(dest.stat().st_mode | 0o111)
+        else:
+            shutil.copyfile(src, dest)
+            # 保持脚本可执行位
+            if src.stat().st_mode & 0o111:
+                dest.chmod(dest.stat().st_mode | 0o111)
+
+        written.append(dest)
+
+    _verify_tree(out_dir, len(written))
+    return written
+
+
+def _assert_no_jinja_residue(path: Path) -> None:
+    """自检渲染产物中不允许残留 Jinja 标记."""
+    text = path.read_text(encoding="utf-8")
+    for marker in ("{{", "{%"):
+        if marker in text:
+            line_no = next(
+                i + 1
+                for i, line in enumerate(text.splitlines())
+                if marker in line
+            )
+            raise RuntimeError(
+                f"渲染残留：{path} 第 {line_no} 行发现未渲染的 Jinja 标记 {marker!r}"
+            )
+
+
+def _verify_tree(out_dir: Path, expected_count: int) -> None:
+    """整体自检：目标文件数与实际写出数一致，且无 Jinja 残留."""
+    out_files = [p for p in out_dir.rglob("*") if p.is_file()]
+    if len(out_files) != expected_count:
+        raise RuntimeError(
+            f"渲染自检失败：预期写出 {expected_count} 个文件，"
+            f"实际 {len(out_files)} 个"
+        )
+    for path in out_files:
+        # 跳过 gitkeep 等空文件；仅扫描文本
+        try:
+            text = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            continue
+        for marker in ("{{", "{%"):
+            if marker in text:
+                raise RuntimeError(f"渲染残留：{path} 发现未渲染的 Jinja 标记 {marker!r}")

fastapp_cli/templates/__init__.py

@@ -0,0 +1 @@
+"""模板包资源定位标记."""

fastapp_cli/templates/project/.env.development.example.j2

@@ -0,0 +1,21 @@
+# 开发环境差异配置（示例）
+# 使用方式：
+#   cp .env.development.example .env.development
+# 启动时自动加载：APP_ENV=development bash scripts/start.sh
+
+APP_ENV=development
+DEBUG=true
+
+# 开发库
+MYSQL_SERVER=localhost
+MYSQL_PORT=3306
+MYSQL_USER=root
+MYSQL_PASSWORD=root
+MYSQL_DB={{ project_name | replace('-', '_') }}_dev
+
+# 打印 SQL 方便排查
+SQL_ECHO=true
+
+# 本地 Redis
+CELERY_BROKER_URL=redis://localhost:6379/0
+CELERY_RESULT_BACKEND=redis://localhost:6379/1

fastapp_cli/templates/project/.env.example.j2

@@ -0,0 +1,29 @@
+# ========== App ==========
+APP_NAME={{ project_name }}
+APP_ENV=development
+API_V1_PREFIX=/api/v1
+DEBUG=false
+
+# ========== Server ==========
+HOST=0.0.0.0
+PORT=8000
+
+# ========== MySQL ==========
+MYSQL_SERVER=localhost
+MYSQL_PORT=3306
+MYSQL_USER=root
+MYSQL_PASSWORD=
+MYSQL_DB={{ project_name | replace('-', '_') }}
+# 是否打印 SQL（开发环境使用）
+SQL_ECHO=false
+
+# ========== Celery（redis，缺席时应用启动自动降级 memory://） ==========
+CELERY_BROKER_URL=redis://localhost:6379/0
+CELERY_RESULT_BACKEND=redis://localhost:6379/1
+CELERY_TASK_DEFAULT_QUEUE=default
+
+# ========== Flower ==========
+FLOWER_HOST=0.0.0.0
+FLOWER_PORT=5555
+# 基本认证（可选），格式：user:password，多个用逗号分隔
+# FLOWER_BASIC_AUTH=admin:admin

fastapp_cli/templates/project/.env.j2

@@ -0,0 +1,27 @@
+# 本地默认配置（已 gitignore）。生产配置参考 .env.example / .env.production.example
+# ========== App ==========
+APP_NAME={{ project_name }}
+APP_ENV=development
+API_V1_PREFIX=/api/v1
+DEBUG=true
+
+# ========== Server ==========
+HOST=0.0.0.0
+PORT=8000
+
+# ========== MySQL（未配置时应用可启动，health 返回 database=down） ==========
+MYSQL_SERVER=localhost
+MYSQL_PORT=3306
+MYSQL_USER=root
+MYSQL_PASSWORD=
+MYSQL_DB={{ project_name | replace('-', '_') }}_dev
+SQL_ECHO=true
+
+# ========== Celery（本地无 redis 时启动自动降级 memory://） ==========
+CELERY_BROKER_URL=redis://localhost:6379/0
+CELERY_RESULT_BACKEND=redis://localhost:6379/1
+CELERY_TASK_DEFAULT_QUEUE=default
+
+# ========== Flower ==========
+FLOWER_HOST=0.0.0.0
+FLOWER_PORT=5555

fastapp_cli/templates/project/.gitignore

@@ -0,0 +1,178 @@
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.development
+.env.production
+.env.test
+.env.local
+!.env.example
+!.env.development.example
+!.env.production.example
+!.env.test.example
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+.env.dev
+.env.prod
+
+# Project specific
+logs/
+.DS_Store
+.ruff_cache/