Entwicklungsumgebung einrichten

Ein umfassender Leitfaden zum Einrichten einer Entwicklungsumgebung für Beiträge zu FastAPI-fastkit.

Voraussetzungen

Bevor Sie starten, stellen Sie sicher, dass Sie haben:

• Python 3.12 oder höher installiert
• Git installiert und konfiguriert
• Grundkenntnisse in Python und FastAPI
• Einen Texteditor oder eine IDE (VS Code, PyCharm usw.)

Schnelles Setup mit Makefile

FastAPI-fastkit bietet ein Makefile für einfaches Entwicklungs-Setup:

$ git clone https://github.com/bnbong/FastAPI-fastkit.git
$ cd FastAPI-fastkit
$ make install-dev
Setting up development environment...
Creating virtual environment...
Installing dependencies...
Installing pre-commit hooks...
✅ Development environment ready!

Dieser einzelne Befehl:

• Installiert das Paket im Editable-Modus mit Dev-Abhängigkeiten
• Richtet Pre-Commit-Hooks ein
• Konfiguriert Entwicklungstools

Note

Sie sollten eine virtuelle Umgebung erstellen und aktivieren, bevor Sie diesen Befehl ausführen.

Manuelles Setup

Wenn Sie ein manuelles Setup bevorzugen oder das Makefile auf Ihrem System nicht funktioniert:

1. Repository klonen

$ git clone https://github.com/bnbong/FastAPI-fastkit.git
$ cd FastAPI-fastkit

2. Virtuelle Umgebung erstellen

$ python -m venv .venv
$ source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Abhängigkeiten installieren

# Install package in editable mode with development dependencies
$ pip install -e ".[dev]"

# Or install from requirements files
$ pip install -r requirements.txt
$ pip install -r requirements-dev.txt

4. Pre-Commit-Hooks einrichten

$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

5. Installation überprüfen

$ fastkit --version
fastapi-fastkit, version 1.2.1

$ python -m pytest tests/
======================== test session starts ========================
collected 45 items
tests/test_cli.py::test_init_command PASSED
tests/test_templates.py::test_template_listing PASSED
...
======================== 45 passed in 2.34s ========================

Entwicklungstools

Die Entwicklungsumgebung enthält mehrere Tools zur Code-Qualität:

Einzeilen-Befehle

mit Makefile:

$ make format lint
Running isort...
Running black...
Running mypy...
✅ All checks passed!

mit den mitgelieferten Skripten:

$ ./scripts/format.sh
$ ./scripts/lint.sh

Code-Formatierung

Black — Code-Formatter:

$ black src/ tests/
reformatted src/main.py
reformatted tests/test_cli.py
All done! ✨ 🍰 ✨

isort — Import-Sortierer:

$ isort src/ tests/
Fixing import order in src/main.py

Code-Linting

mypy — Typprüfung:

$ mypy src/
Success: no issues found in 12 source files

Verfügbare Make-Befehle

Das Projekt-Makefile bietet praktische Befehle für gängige Entwicklungsaufgaben:

Setup-Befehle

Befehl	Beschreibung
make install	Paket im Produktionsmodus installieren
make install-dev	Paket mit Dev-Abhängigkeiten installieren
make install-test	Paket für Tests installieren (deinstallieren + neu installieren)
make uninstall	Paket deinstallieren
make clean	Build-Artefakte und Cache-Dateien löschen

Befehle zur Code-Qualität

Befehl	Beschreibung
make format	Code mit black und isort formatieren
make format-check	Formatierung prüfen, ohne Änderungen vorzunehmen
make lint	Alle Linting-Prüfungen ausführen (isort, black, mypy)

Test-Befehle

Befehl	Beschreibung
make test	Alle Tests ausführen
make test-verbose	Tests mit ausführlicher Ausgabe ausführen
make test-coverage	Tests mit Coverage-Bericht ausführen
make coverage-report	Detaillierten Coverage-Bericht erzeugen (FORMAT=html/xml/json/all)

Befehle zur Vorlagen-Inspektion

Befehl	Beschreibung
make inspect-templates	Alle Vorlagen inspizieren
make inspect-templates-verbose	Mit ausführlicher Ausgabe inspizieren
make inspect-template	Eine oder mehrere Vorlagen inspizieren (Parameter TEMPLATES)

Dokumentations-Befehle

Befehl	Beschreibung
make serve-docs	Dokumentation lokal bereitstellen
make build-docs	Dokumentation bauen

Übersetzungs-Befehle

Befehl	Beschreibung
make translate	Dokumentation übersetzen (Parameter LANG, PROVIDER, MODEL)

Beispiele

# Format code and run all checks
$ make format lint
Running isort...
Running black...
Running mypy...
✅ All checks passed!

# Run tests with coverage
$ make test-coverage
======================== test session starts ========================
collected 45 items
tests/test_cli.py::test_init_command PASSED
...
======================== 45 passed in 2.34s ========================

---------- coverage: platform darwin, python 3.12.1-final-0 ----------
Name                     Stmts   Miss  Cover
--------------------------------------------
src/main.py                 45      2    96%
src/cli.py                  89      5    94%
src/templates.py            67      3    96%
--------------------------------------------
TOTAL                      201     10    95%

# Generate HTML coverage report
$ make coverage-report FORMAT=html
🌐 Opening HTML coverage report in browser...

# Translate documentation to Korean
$ make translate LANG=ko PROVIDER=github MODEL=gpt-4o-mini
Starting translation...
Running: python scripts/translate.py --target-lang ko --api-provider github --model gpt-4o-mini

Projektstruktur

Die Projektstruktur zu verstehen, ist für die Entwicklung entscheidend:

FastAPI-fastkit/
├── src/
│   ├── fastapi_fastkit/
│   │   ├── __main__.py                      # Entry point of the application
│   │   ├── backend/
│   │   │   ├── inspector.py                 # FastAPI-fastkit template inspector
│   │   │   ├── interactive/
│   │   │   │   ├── config_builder.py        # Configuration builder for interactive mode
│   │   │   │   ├── prompts.py               # Prompts for interactive mode
│   │   │   │   ├── selectors.py             # Selectors logic for interactive mode
│   │   │   │   └── validators.py            # User input validators for interactive mode
│   │   │   ├── main.py                      # Backend's logic entry point
│   │   │   ├── package_managers/
│   │   │   │   ├── base.py                  # Base class for package managers
│   │   │   │   ├── factory.py               # Factory for package managers
│   │   │   │   ├── pdm_manager.py           # PDM package manager
│   │   │   │   ├── pip_manager.py           # pip package manager
│   │   │   │   ├── poetry_manager.py        # Poetry package manager
│   │   │   │   └── uv_manager.py            # uv package manager
│   │   │   ├── project_builder/
│   │   │   │   ├── config_generator.py      # Configuration generator for project builder
│   │   │   │   └── dependency_collector.py  # Dependency collector for project builder
│   │   │   └── transducer.py                # Transducer for project builder
│   │   ├── cli.py                           # FastAPI-fastkit main CLI entry point
│   │   ├── core/
│   │   │   ├── exceptions.py                # Exception handling
│   │   │   └── settings.py                  # Settings configuration
│   │   ├── fastapi_project_template/
│   │   │   ├── PROJECT_README_TEMPLATE.md   # fastkit template project base README file
│   │   │   ├── README.md                    # fastkit template README
│   │   │   ├── fastapi-async-crud/
│   │   │   ├── fastapi-custom-response/
│   │   │   ├── fastapi-default/
│   │   │   ├── fastapi-dockerized/
│   │   │   ├── fastapi-empty/
│   │   │   ├── fastapi-mcp/
│   │   │   ├── fastapi-psql-orm/
│   │   │   ├── fastapi-single-module/
│   │   │   └── modules/
│   │   │       ├── api/
│   │   │       │   └── routes/
│   │   │       ├── crud/
│   │   │       └── schemas/
│   │   ├── py.typed
│   │   └── utils/
│   │       ├── logging.py                   # Logging configuration
│   │       └── main.py                      # FastAPI-fastkit main entry point
│   └── logs
├── tests
│   ├── conftest.py                          # pytest configuration
│   ├── test_backends/
│   ├── test_cli_operations/
│   ├── test_core.py
│   ├── test_rich/
│   ├── test_templates/
│   └── test_utils.py
├── uv.lock
├── docs/                                    # Documentation
├── scripts/                                 # Development scripts
├── mkdocs.yml
├── overrides/                               # mkdocs overrides
├── pdm.lock
├── pyproject.toml
├── requirements-docs.txt                    # requirements for documentation
├── requirements.txt                         # requirements for development
├── CHANGELOG.md
├── CITATION.cff
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── MANIFEST.in
├── Makefile
├── README.md
├── SECURITY.md
└── env.example                              # environment example(configures translation AI model env vars)

Wichtige Verzeichnisse

• src/fastapi_fastkit/ — Hauptquellcode des Pakets
  • cli.py — Haupteinstiegspunkt des CLI
  • backend/ — zentrale Backend-Logik
    • inspector.py — Vorlagen-Inspektor
    • interactive/ — Komponenten des interaktiven Modus (Prompts, Selectors, Validators)
    • package_managers/ — Implementierungen der Paketmanager (pip, uv, pdm, poetry)
    • project_builder/ — Hilfsfunktionen zum Projektbau
    • transducer.py — Vorlagen-Transducer
  • core/ — zentrale Konfiguration und Exceptions
  • fastapi_project_template/ — Projektvorlagen (fastapi-default, fastapi-async-crud usw.)
  • utils/ — gemeinsame Hilfsfunktionen
• tests/ — Test-Suite
  • test_backends/ — Backend-spezifische Tests
  • test_cli_operations/ — Tests der CLI-Operationen
  • test_templates/ — Tests des Vorlagensystems
• docs/ — Dokumentation (MkDocs)
  • Nutzerhandbücher, Tutorials und API-Referenz

Entwicklungs-Workflow

1. Feature-Branch erstellen

$ git checkout -b feature/add-new-template
Switched to a new branch 'feature/add-new-template'

2. Änderungen vornehmen

Code bearbeiten, Funktionen ergänzen, Bugs beheben…

3. Tests und Prüfungen ausführen

$ make dev-check
Running all quality checks...
Running all tests...
✅ All tests passed!

4. Änderungen committen

Pre-Commit-Hooks laufen automatisch:

$ git add .
$ git commit -m "Add new FastAPI template with authentication"
format...................................................................Passed
isort-check..............................................................Passed
black-fix................................................................Passed
mypy.....................................................................Passed
[feature/add-new-template abc1234] Add new FastAPI template with authentication

5. Pushen und Pull-Request erstellen

$ git push origin feature/add-new-template
$ gh pr create --title "Add new FastAPI template with authentication"

Testen

Tests ausführen

Alle Tests:

$ make test
# or
$ python -m pytest

Bestimmte Testdatei:

$ python -m pytest tests/test_cli.py -v

Mit Coverage:

$ make test-coverage
# or
$ python -m pytest --cov=src --cov-report=html

Tests schreiben

Bei neuen Funktionen immer Tests beifügen:

# tests/test_commands/test_new_feature.py
import pytest
from fastapi_fastkit.commands.new_feature import NewFeatureCommand

class TestNewFeatureCommand:
    def test_command_success(self):
        """Test successful command execution"""
        command = NewFeatureCommand()
        result = command.execute(valid_args)
        assert result.success is True
        assert result.message == "Feature executed successfully"

    def test_command_validation_error(self):
        """Test command with invalid arguments"""
        command = NewFeatureCommand()
        with pytest.raises(ValueError, match="Invalid argument"):
            command.execute(invalid_args)

    def test_command_edge_case(self):
        """Test edge case handling"""
        command = NewFeatureCommand()
        result = command.execute(edge_case_args)
        assert result.success is True
        assert "warning" in result.message.lower()

Test-Kategorien

Unit-Tests — einzelne Funktionen und Klassen testen:

def test_validate_project_name():
    assert validate_project_name("valid-name") is True
    assert validate_project_name("invalid name!") is False

Integrationstests — Interaktionen zwischen Befehlen testen:

def test_init_command_creates_project(tmp_path):
    result = runner.invoke(cli, ['init'], input='test-project\n...')
    assert result.exit_code == 0
    assert (tmp_path / "test-project").exists()

End-to-End-Tests — komplette Flüsse testen:

def test_full_project_creation_workflow(tmp_path):
    # Create project
    result = runner.invoke(cli, ['init'], input='...')
    assert result.exit_code == 0

    # Add route
    result = runner.invoke(cli, ['addroute', 'test-project', 'users'])
    assert result.exit_code == 0

    # Verify files exist
    assert (tmp_path / "test-project" / "src" / "api" / "routes" / "users.py").exists()

Dokumentation

Dokumentation lokal bereitstellen

$ make serve-docs
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.43 seconds
INFO     -  [14:30:00] Serving on http://127.0.0.1:8000/

Dokumentation bauen

$ make build-docs
INFO     -  Building documentation...
INFO     -  Documentation built in 0.43 seconds

Dokumentation schreiben

Die Dokumentation wird in Markdown verfasst und mit MkDocs gebaut. Beispielstruktur:

Vorlage für einen Funktions-Leitfaden:

# New Feature Guide

This guide explains how to use the new feature.

## Prerequisites

- FastAPI-fastkit installed
- Basic Python knowledge

## Usage

<div class="termy">

```console
$ fastkit new-feature --option value
✅ Feature executed successfully!
```

</div>

!!! tip "Pro Tip"
    Use `--help` to see all available options.

Für eine ausführliche Referenz zu mkdocs-material siehe mkdocs-material-Dokumentation.

Code-Stil-Richtlinien

Python-Codestil

Folgen Sie PEP 8 mit folgenden Regeln:

• Zeilenlänge: 88 Zeichen (Black-Standard)
• Imports: mit isort organisiert
• Type Hints: für alle öffentlichen Funktionen erforderlich
• Docstrings: Google-Style für alle öffentlichen APIs

Beispiel

from typing import List, Optional
from pathlib import Path

def create_project_structure(
    project_name: str,
    template_path: Path,
    output_dir: Optional[Path] = None,
) -> List[Path]:
    """Create project structure from template.

    Args:
        project_name: Name of the project to create
        template_path: Path to the template directory
        output_dir: Output directory, defaults to current directory

    Returns:
        List of created file paths

    Raises:
        ValueError: If project_name is invalid
        FileNotFoundError: If template_path doesn't exist
    """
    if not project_name.isidentifier():
        raise ValueError(f"Invalid project name: {project_name}")

    if not template_path.exists():
        raise FileNotFoundError(f"Template not found: {template_path}")

    # Implementation here...
    return created_files

Umgebungsvariablen

Für die Entwicklung können Sie folgende Umgebungsvariablen setzen:

Variable	Beschreibung	Standard
FASTKIT_DEBUG	Debug-Logging aktivieren	False
FASTKIT_DEV_MODE	Entwicklungs-Funktionen aktivieren	False
FASTKIT_TEMPLATE_DIR	Verzeichnis für eigene Vorlagen	Eingebaute Vorlagen
FASTKIT_CONFIG_DIR	Konfigurationsverzeichnis	~/.fastkit
TRANSLATION_API_KEY	API-Schlüssel für Übersetzungen (verwenden Sie ein GitHub-PAT, wenn Sie den GitHub-KI-Modell-Anbieter nutzen)	None

$ export FASTKIT_DEBUG=true
$ export FASTKIT_DEV_MODE=true
$ fastkit init
DEBUG: Loading configuration from /home/user/.fastkit/
DEBUG: Available templates: ['fastapi-default', ...]

Für weitere Einstellungen zu Umgebungsvariablen siehe das Modul @settings.py.

Fehlerbehebung

Häufige Probleme

1. Pre-Commit-Hooks schlagen fehl:

$ git commit -m "Fix bug"
black....................................................................Failed
hookid: black

Files were modified by this hook. Additional output:

would reformat src/cli.py

Lösung: Formatter ausführen und erneut committen:

$ make format
$ git add .
$ git commit -m "Fix bug"

2. Tests schlagen bei unterschiedlichen Python-Versionen fehl:

Lösung: tox verwenden, um mehrere Python-Versionen zu testen:

$ pip install tox
$ tox
py38: commands succeeded
py39: commands succeeded
py310: commands succeeded
py311: commands succeeded
py312: commands succeeded

3. Import-Fehler in der Entwicklung:

Lösung: Paket im Editable-Modus installieren:

$ pip install -e .

Hilfe bekommen

• GitHub Issues: Bugs und Feature-Requests melden
• GitHub Discussions: Fragen stellen und Ideen teilen
• Dokumentation: siehe Benutzerhandbuch

Beitrags-Richtlinien

Vor dem Einreichen einer PR

1. Alle Prüfungen ausführen: make dev-check
2. Dokumentation aktualisieren, falls nötig
3. Tests für neue Funktionen hinzufügen
4. Commit-Konventionen befolgen

Format der Commit-Nachricht

type(scope): brief description

Longer description if needed

Fixes #123

Typen:

• feat: neue Funktion
• fix: Bugfix
• docs: Dokumentationsänderungen
• style: Code-Stil-Änderungen
• refactor: Refactoring
• test: Tests hinzufügen/ändern
• chore: Wartungsaufgaben

Beispiele:

feat(cli): add new template command

Add support for creating projects from custom templates.
The command accepts a template path and creates a new
project with the specified configuration.

Fixes #45

fix(templates): handle missing template files gracefully

When a template file is missing, show a clear error message
instead of crashing with a stack trace.

Fixes #67

Release-Prozess

Für Maintainer sieht der Release-Prozess so aus:

1. Version aktualisieren in setup.py und __init__.py
2. CHANGELOG.md aktualisieren
3. Release-PR erstellen
4. Release nach dem Merge taggen
5. GitHub Actions baut und veröffentlicht automatisch

$ git tag v1.2.0
$ git push origin v1.2.0

Nächste Schritte

Nachdem Ihre Entwicklungsumgebung eingerichtet ist:

1. Code erkunden, um die Architektur zu verstehen
2. Test-Suite ausführen, um sicherzustellen, dass alles funktioniert
3. Ein Issue auf GitHub auswählen
4. Sich an Discussions beteiligen, um sich mit anderen Mitwirkenden zu vernetzen

Viel Spaß beim Programmieren! 🚀

Entwicklungs-Tipps

• Vor dem Committen make dev-check ausführen
• Tests zuerst schreiben (TDD-Ansatz)
• Commits klein und fokussiert halten
• Dokumentation mit neuen Funktionen aktualisieren