download typer - download do código-fonte typer

typer

Pitão

0.15.1

Baixar

Typer, crie ótimas CLIs. Fácil de codificar. Baseado em dicas de tipo Python.

Documentação : https://typer.tiangolo.com

Código fonte : https://github.com/fastapi/typer

Typer é uma biblioteca para construir aplicativos CLI que os usuários vão adorar usar e os desenvolvedores vão adorar criar . Baseado em dicas de tipo Python.

É também uma ferramenta de linha de comando para executar scripts, convertendo-os automaticamente em aplicativos CLI.

Os principais recursos são:

Intuitivo para escrever : Excelente suporte ao editor. Conclusão em todos os lugares. Menos tempo de depuração. Projetado para ser fácil de usar e aprender. Menos tempo lendo documentos.
Fácil de usar : É fácil de usar para os usuários finais. Ajuda automática e preenchimento automático para todos os shells.
Resumindo : Minimize a duplicação de código. Vários recursos de cada declaração de parâmetro. Menos erros.
Comece de forma simples : o exemplo mais simples adiciona apenas 2 linhas de código ao seu aplicativo: 1 importação, 1 chamada de função .
Crescer : Aumente a complexidade o quanto quiser, crie árvores arbitrariamente complexas de comandos e grupos de subcomandos, com opções e argumentos.
Executar scripts : Typer inclui um comando/programa typer que você pode usar para executar scripts, convertendo-os automaticamente em CLIs, mesmo que não usem Typer internamente.

FastAPI de CLIs

Typer é o irmão mais novo do FastAPI, é o FastAPI das CLIs.

Instalação

Crie e ative um ambiente virtual e depois instale o Typer :

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

Exemplo

O mínimo absoluto

Crie um arquivo main.py com:

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

Este script nem usa Typer internamente. Mas você pode usar o comando typer para executá-lo como um aplicativo CLI.

Execute-o

Execute seu aplicativo com o comando 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! ?

Este é o caso de uso mais simples, nem mesmo usando o Typer internamente, mas já pode ser bastante útil para scripts simples.

Nota : o preenchimento automático funciona quando você cria um pacote Python e o executa com --install-completion ou quando você usa o comando typer .

Use Typer em seu código

Agora vamos começar a usar o Typer em seu próprio código, atualize main.py com:

 import typer


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


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

Agora você pode executá-lo diretamente com 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! ?

Nota : você também pode chamar esse mesmo script com o comando typer , mas não é necessário.

Exemplo de atualização

Este foi o exemplo mais simples possível.

Agora vamos ver um um pouco mais complexo.

Um exemplo com dois subcomandos

Modifique o arquivo main.py .

Crie um aplicativo typer.Typer() e crie dois subcomandos com seus parâmetros.

 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 ()

E isso irá:

Crie explicitamente um aplicativo typer.Typer .
- O typer.run anterior na verdade cria um implicitamente para você.
Adicione dois subcomandos com @app.command() .
Execute o próprio app() , como se fosse uma função (em vez de typer.run ).

Execute o exemplo atualizado

Confira a nova ajuda:

$ 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

Agora verifique a ajuda do comando 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.       │
╰───────────────────────────────────────────────────╯

E agora verifique a ajuda do comando 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 ?

Agora você pode experimentar o novo aplicativo de linha de comando:

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

Recapitular

Em resumo, você declara uma vez os tipos de parâmetros ( argumentos CLI e opções CLI ) como parâmetros de função.

Você faz isso com tipos Python modernos padrão.

Você não precisa aprender uma nova sintaxe, os métodos ou classes de uma biblioteca específica, etc.

Apenas Python padrão.

Por exemplo, para um int :

 total : int

ou para um sinalizador bool :

 force : bool

E da mesma forma para arquivos , caminhos , enums (escolhas), etc. E existem ferramentas para criar grupos de subcomandos , adicionar metadados, validação extra, etc.

Você obtém : excelente suporte ao editor, incluindo preenchimento e verificações de tipo em todos os lugares.

Seus usuários obtêm : --help automático, preenchimento automático em seus terminais (Bash, Zsh, Fish, PowerShell) quando instalam seu pacote ou ao usar o comando typer .

Para um exemplo mais completo incluindo mais recursos, consulte o Tutorial - Guia do Usuário.

Dependências

Typer está sobre os ombros de um gigante. Sua única dependência interna necessária é Click.

Por padrão, ele também vem com dependências padrão extras:

rich : para mostrar erros bem formatados automaticamente.
shellingham : para detectar automaticamente o shell atual ao concluir a instalação.
- Com shellingham você pode simplesmente usar --install-completion .
- Sem shellingham , você deve passar o nome do shell para o qual instalar a conclusão, por exemplo --install-completion bash .