Einstieg

Dieser Leitfaden erstellt eine kleine Kommandozeilenanwendung mit einem Einstiegspunkt, einem positionalen Argument und einem Schalter. quickli unterstützt Python 3.12, 3.13 und 3.14.

quickli installieren

Für ein Projekt, das das veröffentlichte Paket verwendet, installiere quickli in einer virtuellen Umgebung:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install quickli

Wenn du aus dem quickli-Repository arbeitest, installiere das Paket stattdessen im editierbaren Modus:

python -m pip install -e packages/core

Zum Projekt hinzufügen

Starte dort, wo du bist.

Füge quickli einem bestehenden Git-Projekt hinzu oder erstelle ein neues Projekt zum Ausprobieren.

Bestehendes Projekt

quickli zu Git hinzufügen

Behalte dein aktuelles Projekt und installiere quickli in seiner virtuellen Umgebung.

pip

Terminal

pip install quickli

uv

Terminal

uv add quickli

Neues Projekt

Workspace initialisieren

Erstelle ein kleines Git-Projekt und füge quickli als erste Abhängigkeit hinzu.

pip

Terminal

mkdir my-cli && cd my-cli
git init
python -m venv .venv
source .venv/bin/activate
python -m pip install quickli

uv

Terminal

mkdir my-cli && cd my-cli
git init
uv init
uv add quickli

Lieber eine geführte Einführung? Weiter zu dem Einstiegsleitfaden.

Eine Anwendung erstellen

Speichere dieses Beispiel als hello.py:

from __future__ import annotations

from quickli import Application, Argument, Option


app = Application(
    name="hello",
    description="Grüße eine Person von der Kommandozeile.",
)


@app.entrypoint(
    help_text="Einen Gruß ausgeben.",
    arguments=[Argument("name", help_text="Name, der gegrüßt werden soll.")],
    options=[
        Option(
            "uppercase",
            short_name="u",
            is_flag=True,
            help_text="Den Gruß in Großbuchstaben ausgeben.",
        ),
    ],
)
def greet(name: str, uppercase: bool = False) -> str:
    message = f"Hello, {name}!"
    return message.upper() if uppercase else message


if __name__ == "__main__":
    sys.exit(app.main())

Ausführen

Übergebe die Kommandozeilen-Token an die Anwendung:

python hello.py Ada
python hello.py Ada --uppercase

Der erste Befehl gibt Hello, Ada! aus; der zweite gibt HELLO, ADA! aus.

Generierte Hilfe erkunden

Die Anwendung generiert Hilfe aus ihren registrierten Argumenten, Optionen und Hilfs-Strings. Führe sie ohne Argumente aus, um den Hilfstext zu sehen:

python hello.py

Application.main() ist der einsteigerfreundliche Einstiegspunkt für ausführbare Programme. Er liest sys.argv[1:] für dich, gibt den Rückgabewert aus, meldet quickli- Laufzeitfehler und liefert einen Exit-Code zurück.

Application.run() gibt das Handler-Ergebnis weiterhin für Tests, Bibliotheken und anderen Code zurück, der direkte Kontrolle möchte. Ohne Argumente liest es ebenfalls standardmäßig sys.argv[1:]. Übergib eine explizite Liste zum Überschreiben oder setze auto_sys_argv=False, um das automatische Lesen zu deaktivieren.

Wie es weitergeht

• Verwende @app.command(), um ein Multi-Command-CLI zu bauen.
• Verwende converter=int oder converter=Path, um Eingabewerte zu konvertieren.
• Füge Validatoren wie file_path() oder number_range() für geprüfte Eingaben hinzu.
• Lies die Projektbeispiele für kleine, fokussierte Anwendungen.