Anleitung 1: Hello World

Diese Anleitung erstellt die kleinste nützliche quickli-Anwendung: ein Begrüßungs- werkzeug, das einen Namen und ein optionales Flag für Großbuchstaben akzeptiert.

Du lernst:

• eine Application mit einer Beschreibung zu erstellen
• mit @app.entrypoint einen Einstiegspunkt zu registrieren
• ein Positions-Argument hinzuzufügen
• ein boolesches Option-Flag hinzuzufügen
• die Anwendung über die Kommandozeile auszuführen

Das vollständige Beispiel

Speichere die folgende Datei als hello.py:

from __future__ import annotations

from quickli import Application, Argument, Option


app = Application(
    name="hello",
    description="Greet a person from the command line.",
)


@app.entrypoint(
    help_text="Print a greeting.",
    arguments=[Argument("name", help_text="Name to greet.")],
    options=[
        Option(
            "uppercase",
            short_name="u",
            is_flag=True,
            help_text="Print the greeting in uppercase.",
        ),
    ],
)
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

python hello.py Ada
# Hello, Ada!

python hello.py Ada --uppercase
# HELLO, ADA!

python hello.py Ada -u
# HELLO, ADA!

Erklärung Zeile für Zeile

Imports

from quickli import Application, Argument, Option

Du musst nur die drei verwendeten Klassen importieren. quickli hält seine öffentliche API klein und ausdrücklich.

Die Anwendung erstellen

app = Application(
    name="hello",
    description="Greet a person from the command line.",
)

Application ist der zentrale Container. name wird in der Hilfe verwendet. description erscheint unter der Nutzungszeile, wenn du das Werkzeug ohne Argumente startest.

Den Einstiegspunkt registrieren

@app.entrypoint(
    help_text="Print a greeting.",
    arguments=[Argument("name", help_text="Name to greet.")],
    options=[
        Option(
            "uppercase",
            short_name="u",
            is_flag=True,
            help_text="Print the greeting in uppercase.",
        ),
    ],
)
def greet(name: str, uppercase: bool = False) -> str:
    ...

@app.entrypoint ist für Anwendungen ohne Befehl gedacht. Die Anwendung hat einen einzigen Zweck, daher ist kein Befehlsname nötig.

• help_text erscheint in der erzeugten Nutzungsausgabe.
• arguments ist eine Liste von Argument-Instanzen in Positionsreihenfolge.
• options ist eine Liste von Option-Instanzen.

Der Konstruktor von Argument

Argument("name", help_text="Name to greet.")

Argument erwartet als erstes Argument einen Positionsnamen. Dieser Name muss zum entsprechenden Funktionsparameter passen. Argumente sind standardmäßig erforderlich. Für ein optionales Argument übergibst du required=False und einen default.

Der Konstruktor von Option

Option(
    "uppercase",
    short_name="u",
    is_flag=True,
    help_text="Print the greeting in uppercase.",
)

• "uppercase" wird in der Kommandozeile zu --uppercase.
• short_name="u" ergänzt die Kurzform -u.
• is_flag=True bedeutet, dass die Option boolesch ist: vorhanden → True, nicht vorhanden → False.
• Der Funktionsparameter muss zum Optionsnamen passen, wobei Bindestriche durch Unterstriche ersetzt werden.

Die Handler-Funktion

def greet(name: str, uppercase: bool = False) -> str:
    message = f"Hello, {name}!"
    return message.upper() if uppercase else message

Der Handler erhält die geparsten Werte direkt. quickli ordnet Argument- und Optionsnamen den Parameternamen zu. Der Standardwert für uppercase entspricht der Abwesenheit der Option.

Der Handler gibt einen String zurück. Application.main() gibt diesen Wert bei erfolgreichen Läufen aus.

Der Einstiegspunkt

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

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

Application.run(argv) akzeptiert weiterhin explizite Tokens, wenn du diese niedrigere, testfreundliche Grenze direkt verwenden willst. Application.run() liest ebenfalls standardmäßig sys.argv[1:], wenn du es ohne Argumente aufrufst. Übergib eine explizite Liste zum Überschreiben oder setze auto_sys_argv=False, um das automatische Lesen zu deaktivieren.

Die Hilfeausgabe erkunden

Starte das Programm ohne Argumente:

python hello.py

quickli erzeugt den Nutzungstext aus den registrierten Argumenten, Optionen und Hilfetexten.

Was du als Nächstes ausprobieren kannst

• Füge eine zweite Option hinzu, etwa --shout, und ändere das Nachrichtenformat.
• Mache das Argument name mit required=False und default="world" optional.
• Lies Anleitung 2: Dateibetrachter, um globale Optionen, mehrere Dateiargumente und Pfadvalidierung kennenzulernen.