typer Télécharger - typer Téléchargement du code source

typer

Python

0.15.1

Télécharger

Tapez, créez de superbes CLI. Facile à coder. Basé sur des astuces de type Python.

Documentation : https://typer.tiangolo.com

Code source : https://github.com/fastapi/typer

Typer est une bibliothèque permettant de créer des applications CLI que les utilisateurs adoreront utiliser et que les développeurs adoreront créer . Basé sur des astuces de type Python.

C'est également un outil de ligne de commande pour exécuter des scripts, en les convertissant automatiquement en applications CLI.

Les principales caractéristiques sont :

Intuitif à écrire : Excellent support de l’éditeur. Achèvement partout. Moins de temps de débogage. Conçu pour être facile à utiliser et à apprendre. Moins de temps à lire des documents.
Facile à utiliser : Il est facile à utiliser pour les utilisateurs finaux. Aide automatique et complétion automatique pour tous les shells.
Court : minimisez la duplication de code. Plusieurs fonctionnalités de chaque déclaration de paramètre. Moins de bugs.
Commencez simplement : L'exemple le plus simple ajoute seulement 2 lignes de code à votre application : 1 import, 1 appel de fonction .
Grandissez : augmentez la complexité autant que vous le souhaitez, créez des arbres de commandes et des groupes de sous-commandes arbitrairement complexes, avec des options et des arguments.
Exécuter des scripts : Typer comprend une commande/un programme typer que vous pouvez utiliser pour exécuter des scripts, les convertissant automatiquement en CLI, même s'ils n'utilisent pas Typer en interne.

FastAPI des CLI

Typer est le petit frère de FastAPI, c'est la FastAPI des CLI.

Installation

Créez et activez un environnement virtuel puis installez Typer :

$ pip install typer
---> 100%
Successfully installed typer rich shellingham

Exemple

Le minimum absolu

Créez un fichier main.py avec :

 def main ( name : str ):
    print ( f"Hello { name } " )

Ce script n'utilise même pas Typer en interne. Mais vous pouvez utiliser la commande typer pour l'exécuter en tant qu'application CLI.

Exécutez-le

Exécutez votre application avec la commande typer :

 // Run your application
$ typer main.py run

// You get a nice error, you are missing NAME
Usage: typer [PATH_OR_MODULE] run [OPTIONS] NAME
Try 'typer [PATH_OR_MODULE] run --help' for help.
╭─ Error ───────────────────────────────────────────╮
│ Missing argument 'NAME'.                          │
╰───────────────────────────────────────────────────╯


// You get a --help for free
$ typer main.py run --help

Usage: typer [PATH_OR_MODULE] run [OPTIONS] NAME

Run the provided Typer app.

╭─ Arguments ───────────────────────────────────────╮
│ *    name      TEXT  [default: None] [required]   |
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --help          Show this message and exit.       │
╰───────────────────────────────────────────────────╯

// Now pass the NAME argument
$ typer main.py run Camila

Hello Camila

// It works! ?

Il s’agit du cas d’utilisation le plus simple, sans même utiliser Typer en interne, mais il peut déjà être très utile pour des scripts simples.

Remarque : la saisie semi-automatique fonctionne lorsque vous créez un package Python et l'exécutez avec --install-completion ou lorsque vous utilisez la commande typer .

Utilisez Typer dans votre code

Commençons maintenant à utiliser Typer dans votre propre code, mettez à jour main.py avec :

 import typer


def main ( name : str ):
    print ( f"Hello { name } " )


if __name__ == "__main__" :
    typer . run ( main )

Vous pouvez maintenant l'exécuter directement avec Python :

 // Run your application
$ python main.py

// You get a nice error, you are missing NAME
Usage: main.py [OPTIONS] NAME
Try 'main.py --help' for help.
╭─ Error ───────────────────────────────────────────╮
│ Missing argument 'NAME'.                          │
╰───────────────────────────────────────────────────╯


// You get a --help for free
$ python main.py --help

Usage: main.py [OPTIONS] NAME

╭─ Arguments ───────────────────────────────────────╮
│ *    name      TEXT  [default: None] [required]   |
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --help          Show this message and exit.       │
╰───────────────────────────────────────────────────╯

// Now pass the NAME argument
$ python main.py Camila

Hello Camila

// It works! ?

Remarque : vous pouvez également appeler ce même script avec la commande typer , mais ce n'est pas obligatoire.

Exemple de mise à niveau

C’était l’exemple le plus simple possible.

Voyons maintenant un cas un peu plus complexe.

Un exemple avec deux sous-commandes

Modifiez le fichier main.py .

Créez une application typer.Typer() et créez deux sous-commandes avec leurs paramètres.

 import typer

app = typer . Typer ()


@ app . command ()
def hello ( name : str ):
    print ( f"Hello { name } " )


@ app . command ()
def goodbye ( name : str , formal : bool = False ):
    if formal :
        print ( f"Goodbye Ms. { name } . Have a good day." )
    else :
        print ( f"Bye { name } !" )


if __name__ == "__main__" :
    app ()

Et cela va :

Créez explicitement une application typer.Typer .
- Le typer.run précédent en crée un implicitement pour vous.
Ajoutez deux sous-commandes avec @app.command() .
Exécutez app() lui-même, comme s'il s'agissait d'une fonction (au lieu de typer.run ).

Exécutez l'exemple mis à niveau

Consultez la nouvelle aide :

$ python main.py --help

 Usage: main.py [OPTIONS] COMMAND [ARGS]...

╭─ Options ─────────────────────────────────────────╮
│ --install-completion          Install completion  │
│                               for the current     │
│                               shell.              │
│ --show-completion             Show completion for │
│                               the current shell,  │
│                               to copy it or       │
│                               customize the       │
│                               installation.       │
│ --help                        Show this message   │
│                               and exit.           │
╰───────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────╮
│ goodbye                                           │
│ hello                                             │
╰───────────────────────────────────────────────────╯

// When you create a package you get  auto-completion  for free, installed with --install-completion

// You have 2 subcommands (the 2 functions): goodbye and hello

Vérifiez maintenant l'aide de la commande hello :

$ python main.py hello --help

 Usage: main.py hello [OPTIONS] NAME

╭─ Arguments ───────────────────────────────────────╮
│ *    name      TEXT  [default: None] [required]   │
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --help          Show this message and exit.       │
╰───────────────────────────────────────────────────╯

Et maintenant, consultez l'aide de la commande goodbye :

$ python main.py goodbye --help

 Usage: main.py goodbye [OPTIONS] NAME

╭─ Arguments ───────────────────────────────────────╮
│ *    name      TEXT  [default: None] [required]   │
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --formal    --no-formal      [default: no-formal] │
│ --help                       Show this message    │
│                              and exit.            │
╰───────────────────────────────────────────────────╯

// Automatic --formal and --no-formal for the bool option ?

Vous pouvez maintenant essayer la nouvelle application en ligne de commande :

 // Use it with the hello command

$ python main.py hello Camila

Hello Camila

// And with the goodbye command

$ python main.py goodbye Camila

Bye Camila!

// And with --formal

$ python main.py goodbye --formal Camila

Goodbye Ms. Camila. Have a good day.

Résumer

En résumé, vous déclarez une fois les types de paramètres ( arguments CLI et options CLI ) comme paramètres de fonction.

Vous faites cela avec des types Python modernes standard.

Vous n'avez pas besoin d'apprendre une nouvelle syntaxe, les méthodes ou classes d'une bibliothèque spécifique, etc.

Juste du Python standard.

Par exemple, pour un int :

 total : int

ou pour un drapeau bool :

 force : bool

Et de même pour les fichiers , les chemins , les énumérations (choix), etc. Et il existe des outils pour créer des groupes de sous-commandes , ajouter des métadonnées, une validation supplémentaire, etc.

Vous obtenez : un excellent support d'éditeur, y compris des vérifications de complétion et de type partout.

Vos utilisateurs obtiennent : --help automatique, la complétion automatique dans leur terminal (Bash, Zsh, Fish, PowerShell) lorsqu'ils installent votre package ou lorsqu'ils utilisent la commande typer .

Pour un exemple plus complet incluant plus de fonctionnalités, consultez le Tutoriel - Guide de l'utilisateur.

Dépendances

Typer se tient sur les épaules d'un géant. Sa seule dépendance interne requise est Click.

Par défaut, il est également livré avec des dépendances standard supplémentaires :

rich : pour afficher automatiquement les erreurs bien formatées.
shellingham : pour détecter automatiquement le shell actuel à la fin de l'installation.
- Avec shellingham vous pouvez simplement utiliser --install-completion .
- Sans shellingham , vous devez transmettre le nom du shell pour lequel l'installation est terminée, par exemple --install-completion bash .