fastapi-minimal-template 0.1.0__tar.gz

fastapi_minimal_template-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install dependencies
+        run: uv sync --locked
+      - name: Lint
+        run: uv run ruff check .
+      - name: Check formatting
+        run: uv run ruff format --check .
+      - name: Test
+        run: uv run pytest
+      - name: Build package
+        run: uv build

fastapi_minimal_template-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,48 @@
+name: Publicar no PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    name: Publicar pacote
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/fastapi-minimal-template/
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Instalar uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Configurar Python
+        run: uv python install 3.12
+
+      - name: Instalar dependências
+        run: uv sync --locked
+
+      - name: Executar lint
+        run: uv run ruff check .
+
+      - name: Verificar formatação
+        run: uv run ruff format --check .
+
+      - name: Executar testes
+        run: uv run pytest
+
+      - name: Construir pacote
+        run: uv build --no-sources
+
+      - name: Publicar no PyPI
+        run: uv publish

fastapi_minimal_template-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+.tools/
+dist/
+build/
+*.egg-info/

fastapi_minimal_template-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

fastapi_minimal_template-0.1.0/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.

fastapi_minimal_template-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,104 @@
+# 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/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fastapi-minimal-template"
+dynamic = ["version"]
+description = "Generate a minimal FastAPI project for learning Docker and uv"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+    { name = "fastapi-minimal-template contributors" },
+]
+keywords = ["fastapi", "docker", "template", "cli", "uv"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Framework :: FastAPI",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Code Generators",
+]
+dependencies = [
+    "typer>=0.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/dirleiflsilva/fastapi-minimal-template"
+Issues = "https://github.com/dirleiflsilva/fastapi-minimal-template/issues"
+
+[project.scripts]
+fastapi-minimal-template = "fastapi_minimal_template.cli:app"
+
+[dependency-groups]
+dev = [
+    "fastapi[standard]>=0.115,<0.116",
+    "httpx",
+    "pytest",
+    "ruff",
+]
+
+[tool.uv]
+constraint-dependencies = [
+    "anyio<4.10",
+    "pydantic<2.12",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fastapi_minimal_template"]
+
+[tool.hatch.version]
+path = "src/fastapi_minimal_template/__init__.py"
+
+[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-0.1.0/src/fastapi_minimal_template/__init__.py

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

fastapi_minimal_template-0.1.0/src/fastapi_minimal_template/__main__.py

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

fastapi_minimal_template-0.1.0/src/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-0.1.0/src/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()