fastapi-minimal-template 0.1.0__py3-none-any.whl

fastapi_minimal_template/__init__.py

@@ -0,0 +1,3 @@
+"""Generate minimal FastAPI projects."""
+
+__version__ = "0.1.0"

fastapi_minimal_template/__main__.py

@@ -0,0 +1,4 @@
+from fastapi_minimal_template.cli import app
+
+if __name__ == "__main__":
+    app()

fastapi_minimal_template/cli.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from typer.core import TyperGroup
+
+from fastapi_minimal_template import __version__
+from fastapi_minimal_template.generator import GenerationError, generate_project
+
+
+class ShortcutGroup(TyperGroup):
+    """Treat an unknown first positional argument as `new PROJECT_NAME`."""
+
+    def parse_args(self, ctx: typer.Context, args: list[str]) -> list[str]:
+        if args and not args[0].startswith("-") and args[0] != "new":
+            args.insert(0, "new")
+        return super().parse_args(ctx, args)
+
+
+app = typer.Typer(
+    cls=ShortcutGroup,
+    help="Generate a minimal FastAPI project.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"fastapi-minimal-template {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+) -> None:
+    """Generate a minimal FastAPI project."""
+
+
+@app.command()
+def new(
+    project_name: str = typer.Argument(..., metavar="PROJECT_NAME"),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Replace an existing destination.",
+    ),
+    no_docker: bool = typer.Option(
+        False,
+        "--no-docker",
+        help="Do not generate Docker files.",
+    ),
+) -> None:
+    """Create a new FastAPI project."""
+    typer.echo(f"Creating FastAPI project: {project_name}\n")
+    try:
+        result = generate_project(
+            project_name,
+            base_dir=Path.cwd(),
+            force=force,
+            include_docker=not no_docker,
+        )
+    except (GenerationError, OSError) as error:
+        typer.echo(f"Error: {error}", err=True)
+        raise typer.Exit(code=1) from error
+
+    typer.echo("✓ Project directory created")
+    typer.echo("✓ Python files generated")
+    if result.docker_enabled:
+        typer.echo("✓ Dockerfile generated")
+        typer.echo("✓ Docker Compose configuration generated")
+    typer.echo("✓ Tests generated")
+    typer.echo("\nProject created successfully.\n")
+    typer.echo("Next steps:\n")
+    typer.echo(f"  cd {result.destination.name}")
+    typer.echo("  uv sync")
+    typer.echo("  uv run fastapi dev src/app/main.py")
+    typer.echo("\nAPI:          http://localhost:8000")
+    typer.echo("Swagger:      http://localhost:8000/docs")
+    typer.echo("Health check: http://localhost:8000/health")

fastapi_minimal_template/generator.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import re
+import shutil
+import tempfile
+import uuid
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+from typing import BinaryIO
+
+PLACEHOLDERS = (
+    "{{ project_name }}",
+    "{{ project_slug }}",
+    "{{ project_title }}",
+    "{{ python_package_name }}",
+)
+NAME_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
+TEXT_FILE_NAMES = {
+    ".dockerignore",
+    ".gitignore",
+    "Dockerfile",
+    "compose.yaml",
+}
+TEXT_SUFFIXES = {".md", ".py", ".template", ".toml", ".yaml", ".yml"}
+DOCKER_FILES = {"Dockerfile", "compose.yaml", ".dockerignore"}
+
+
+class GenerationError(ValueError):
+    """Raised when a project cannot be generated safely."""
+
+
+@dataclass(frozen=True)
+class ProjectNames:
+    original: str
+    slug: str
+    title: str
+    python_package: str
+
+    @property
+    def replacements(self) -> dict[str, str]:
+        return {
+            "{{ project_name }}": self.original,
+            "{{ project_slug }}": self.slug,
+            "{{ project_title }}": self.title,
+            "{{ python_package_name }}": self.python_package,
+        }
+
+
+@dataclass(frozen=True)
+class GenerationResult:
+    destination: Path
+    names: ProjectNames
+    docker_enabled: bool
+
+
+def normalize_project_name(project_name: str) -> ProjectNames:
+    """Validate a user-supplied name and calculate its derived forms."""
+    if not project_name or project_name in {".", ".."}:
+        raise GenerationError("Project name cannot be empty, '.' or '..'.")
+
+    candidate = Path(project_name)
+    if candidate.is_absolute() or "/" in project_name or "\\" in project_name:
+        raise GenerationError("Project name must not contain a path.")
+    if not NAME_PATTERN.fullmatch(project_name):
+        raise GenerationError(
+            "Project name may contain only letters, numbers, '-' and '_', "
+            "and must start with a letter or number."
+        )
+
+    words = [word for word in re.split(r"[-_]+", project_name) if word]
+    slug = "-".join(words).lower()
+    python_package = "_".join(words).lower()
+    if python_package[0].isdigit():
+        python_package = f"_{python_package}"
+
+    return ProjectNames(
+        original=project_name,
+        slug=slug,
+        title=" ".join(word.capitalize() for word in words),
+        python_package=python_package,
+    )
+
+
+def generate_project(
+    project_name: str,
+    *,
+    base_dir: Path | None = None,
+    force: bool = False,
+    include_docker: bool = True,
+) -> GenerationResult:
+    """Create a project atomically inside base_dir."""
+    names = normalize_project_name(project_name)
+    parent = (base_dir or Path.cwd()).resolve()
+    if not parent.is_dir():
+        raise GenerationError(f"Destination parent does not exist: {parent}")
+
+    destination = parent / names.original
+    if destination.exists() and not force:
+        raise GenerationError(
+            f"Destination already exists: {destination}. Use --force to replace it."
+        )
+
+    staging = Path(tempfile.mkdtemp(prefix=f".{names.slug}-", dir=parent))
+    try:
+        _copy_template(staging, names, include_docker=include_docker)
+        _install_staged_project(staging, destination, force=force)
+    except Exception:
+        if staging.exists():
+            shutil.rmtree(staging)
+        raise
+
+    return GenerationResult(
+        destination=destination,
+        names=names,
+        docker_enabled=include_docker,
+    )
+
+
+def _copy_template(
+    destination: Path,
+    names: ProjectNames,
+    *,
+    include_docker: bool,
+) -> None:
+    template_root = files("fastapi_minimal_template").joinpath("template")
+    _copy_directory(
+        template_root,
+        destination,
+        names.replacements,
+        include_docker=include_docker,
+        at_root=True,
+    )
+
+
+def _copy_directory(
+    source: object,
+    destination: Path,
+    replacements: dict[str, str],
+    *,
+    include_docker: bool,
+    at_root: bool = False,
+) -> None:
+    destination.mkdir(parents=True, exist_ok=True)
+    for item in source.iterdir():  # type: ignore[attr-defined]
+        if at_root and not include_docker and item.name in DOCKER_FILES:
+            continue
+
+        output_name = item.name.removesuffix(".template")
+        output_path = destination / output_name
+        if item.is_dir():
+            _copy_directory(
+                item,
+                output_path,
+                replacements,
+                include_docker=include_docker,
+            )
+        elif _is_text_file(item.name):
+            text = item.read_text(encoding="utf-8")
+            for placeholder, value in replacements.items():
+                text = text.replace(placeholder, value)
+            output_path.write_text(text, encoding="utf-8")
+        else:
+            with item.open("rb") as source_file, output_path.open("wb") as output_file:
+                _copy_binary(source_file, output_file)
+
+
+def _copy_binary(source: BinaryIO, destination: BinaryIO) -> None:
+    shutil.copyfileobj(source, destination)
+
+
+def _is_text_file(name: str) -> bool:
+    return name in TEXT_FILE_NAMES or Path(name).suffix in TEXT_SUFFIXES
+
+
+def _install_staged_project(
+    staging: Path,
+    destination: Path,
+    *,
+    force: bool,
+) -> None:
+    if not destination.exists():
+        staging.replace(destination)
+        return
+
+    if not force:
+        raise GenerationError(f"Destination already exists: {destination}")
+
+    backup = destination.with_name(f".{destination.name}.backup-{uuid.uuid4().hex}")
+    destination.replace(backup)
+    try:
+        staging.replace(destination)
+    except Exception:
+        backup.replace(destination)
+        raise
+    else:
+        if backup.is_dir():
+            shutil.rmtree(backup)
+        else:
+            backup.unlink()

fastapi_minimal_template/template/.dockerignore

@@ -0,0 +1,6 @@
+.git
+.venv
+__pycache__
+.pytest_cache
+.ruff_cache
+dist

fastapi_minimal_template/template/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/

fastapi_minimal_template/template/Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+COPY . .
+
+RUN uv sync --no-dev
+
+EXPOSE 8000
+
+CMD ["uv", "run", "--no-dev", "fastapi", "run", "src/app/main.py", "--port", "8000"]

fastapi_minimal_template/template/README.md.template

@@ -0,0 +1,45 @@
+# {{ project_title }}
+
+A minimal FastAPI application generated by `fastapi-minimal-template`.
+
+## Requirements
+
+- Python 3.12 or newer
+- [uv](https://docs.astral.sh/uv/)
+- Docker and Docker Compose (optional)
+
+## Run locally
+
+```bash
+uv sync
+uv run fastapi dev src/app/main.py
+```
+
+## Tests and code quality
+
+```bash
+uv run pytest
+uv run ruff check .
+uv run ruff format .
+```
+
+## Docker
+
+Build and run the image:
+
+```bash
+docker build -t {{ project_slug }} .
+docker run --rm -p 8000:8000 {{ project_slug }}
+```
+
+Or use Docker Compose:
+
+```bash
+docker compose up --build
+```
+
+## URLs
+
+- API: <http://localhost:8000>
+- Swagger: <http://localhost:8000/docs>
+- Health check: <http://localhost:8000/health>

fastapi_minimal_template/template/compose.yaml

@@ -0,0 +1,6 @@
+services:
+  api:
+    build:
+      context: .
+    ports:
+      - "8000:8000"

fastapi_minimal_template/template/pyproject.toml.template

@@ -0,0 +1,33 @@
+[project]
+name = "{{ project_slug }}"
+version = "0.1.0"
+description = "Minimal FastAPI application"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi[standard]>=0.115,<0.116",
+]
+
+[dependency-groups]
+dev = [
+    "httpx",
+    "pytest",
+    "ruff",
+]
+
+[tool.uv]
+constraint-dependencies = [
+    "anyio<4.10",
+    "pydantic<2.12",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

fastapi_minimal_template/template/src/app/__init__.py

@@ -0,0 +1 @@
+

fastapi_minimal_template/template/src/app/main.py

@@ -0,0 +1,16 @@
+from fastapi import FastAPI
+
+app = FastAPI(
+    title="{{ project_title }}",
+    version="0.1.0",
+)
+
+
+@app.get("/")
+async def hello_world() -> dict[str, str]:
+    return {"message": "Hello World"}
+
+
+@app.get("/health")
+async def health_check() -> dict[str, str]:
+    return {"status": "healthy"}

fastapi_minimal_template/template/tests/test_main.py

@@ -0,0 +1,18 @@
+from app.main import app
+from fastapi.testclient import TestClient
+
+client = TestClient(app)
+
+
+def test_hello_world() -> None:
+    response = client.get("/")
+
+    assert response.status_code == 200
+    assert response.json() == {"message": "Hello World"}
+
+
+def test_health_check() -> None:
+    response = client.get("/health")
+
+    assert response.status_code == 200
+    assert response.json() == {"status": "healthy"}

fastapi_minimal_template-0.1.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: fastapi-minimal-template
+Version: 0.1.0
+Summary: Generate a minimal FastAPI project for learning Docker and uv
+Project-URL: Homepage, https://github.com/dirleiflsilva/fastapi-minimal-template
+Project-URL: Issues, https://github.com/dirleiflsilva/fastapi-minimal-template/issues
+Author: fastapi-minimal-template contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,docker,fastapi,template,uv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.12
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# fastapi-minimal-template
+
+Uma pequena ferramenta CLI de código aberto que cria uma aplicação FastAPI
+deliberadamente mínima. Ela foi projetada para aulas práticas sobre Python, APIs
+REST, Docker, Docker Compose e gerenciamento de dependências com
+[uv](https://docs.astral.sh/uv/).
+
+O projeto gerado contém dois endpoints, testes e arquivos opcionais para Docker.
+Intencionalmente, ele não inclui banco de dados, autenticação, ORM ou
+infraestrutura de produção.
+
+## Início rápido
+
+Execute a versão mais recente publicada sem instalá-la:
+
+```bash
+uvx fastapi-minimal-template@latest new hello-api
+cd hello-api
+uv sync
+uv run fastapi dev src/app/main.py
+```
+
+Acesse:
+
+- API: <http://localhost:8000>
+- Swagger: <http://localhost:8000/docs>
+- Verificação de saúde: <http://localhost:8000/health>
+
+A forma abreviada também é aceita:
+
+```bash
+uvx fastapi-minimal-template@latest hello-api
+```
+
+Use `--no-docker` para omitir os arquivos do Docker. Um destino existente nunca
+será alterado, a menos que `--force` seja informado explicitamente:
+
+```bash
+fastapi-minimal-template new hello-api --no-docker
+fastapi-minimal-template new hello-api --force
+```
+
+## Outras opções de instalação
+
+Execute uma versão específica:
+
+```bash
+uvx fastapi-minimal-template@0.1.0 new hello-api
+```
+
+Instale o comando permanentemente:
+
+```bash
+uv tool install fastapi-minimal-template
+fastapi-minimal-template new hello-api
+```
+
+## Desenvolvimento da CLI
+
+```bash
+git clone https://github.com/dirleiflsilva/fastapi-minimal-template.git
+cd fastapi-minimal-template
+uv sync
+uv run fastapi-minimal-template new hello-api
+```
+
+Para reproduzir a experiência do `uvx` antes da publicação:
+
+```bash
+uvx --from . fastapi-minimal-template new hello-api
+```
+
+Um caminho absoluto pode ser usado após `--from` caso a forma com o diretório
+atual não seja resolvida por uma versão mais antiga do uv.
+
+Execute todas as verificações de qualidade e construa a distribuição:
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+uv build
+```
+
+## Publicação
+
+Depois de atualizar a única declaração de versão em
+`src/fastapi_minimal_template/__init__.py`, valide e construa o pacote:
+
+```bash
+uv sync
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+uv build
+uv publish
+```
+
+A publicação requer credenciais do PyPI e deve ser realizada a partir de um
+commit de release limpo e revisado.
+
+## Licença
+
+[MIT](LICENSE)

fastapi_minimal_template-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+fastapi_minimal_template/__init__.py,sha256=Ci7MMtDHsagF8KcV5V7nKk7i0H6iIk08tQzvw9ksmic,64
+fastapi_minimal_template/__main__.py,sha256=qaNlkaBBYtmLnuL5PoXEkpv7PDMHj1Bn07Qdi4jTImQ,83
+fastapi_minimal_template/cli.py,sha256=0S8cOcRJPmYlPcjJ_NqslU4TaL28hkChJx4RoNrHMtM,2580
+fastapi_minimal_template/generator.py,sha256=JVRQgf_uX9XPIRyFYWLwAau2PD1_ZC7WJUrfhQLTnck,5764
+fastapi_minimal_template/template/.dockerignore,sha256=50suLhiPMrCXWLqSm6ChpOi7AOW-3KPLPT2gxJvCpug,54
+fastapi_minimal_template/template/.gitignore,sha256=Fg2EuuSfVx2-J3hlGjnw5jO0ZL0KZYfJFWEnuptMI2g,58
+fastapi_minimal_template/template/Dockerfile,sha256=fwzbqj8SRVhKVcibXntxDdb5h7_rLyy5ATNsa6P0KqI,223
+fastapi_minimal_template/template/README.md.template,sha256=dg3rlQ_zflVNGqiP3QRoZmiI7VXbCCu_2Y7NVHEDJU8,702
+fastapi_minimal_template/template/compose.yaml,sha256=gcCVi23jI52c_qLUczzC9U4YZqyr7YvLpfcah5jcHUg,76
+fastapi_minimal_template/template/pyproject.toml.template,sha256=7OVq-t2CU59ZYUY5AL9v1DPpJ_LQskRa1ZGYW0idURA,542
+fastapi_minimal_template/template/src/app/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fastapi_minimal_template/template/src/app/main.py,sha256=FfgIznNLZPb8zZIpm_-pP_xOqEwcauQ_hQn4gElL-qw,296
+fastapi_minimal_template/template/tests/test_main.py,sha256=5ZDORN1gJSXirsBifKIXoxyAOi_Perhj0bXs6z0rEE4,419
+fastapi_minimal_template-0.1.0.dist-info/METADATA,sha256=EY9uf3QldSSBGDNAvCz-2LdCKtdKX1R4uctgr3MNrFk,3304
+fastapi_minimal_template-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+fastapi_minimal_template-0.1.0.dist-info/entry_points.txt,sha256=SOPIYvzpz6zKHrsiTAUJzXlkg77henAM9Pr6kwhcDeo,78
+fastapi_minimal_template-0.1.0.dist-info/licenses/LICENSE,sha256=n-aLqXlCtdhUoQoHs4y83v8blhW3XbbH948iek9zCWo,1094
+fastapi_minimal_template-0.1.0.dist-info/RECORD,,

fastapi_minimal_template-0.1.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

fastapi_minimal_template-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fastapi-minimal-template = fastapi_minimal_template.cli:app

fastapi_minimal_template-0.1.0.dist-info/licenses/LICENSE

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