Introdução

Python é amplamente conhecido por sua versatilidade e facilidade de uso, especialmente ao construir aplicativos de interface de linha de comando (CLI). Se você deseja automatizar tarefas rotineiras, construir ferramentas de desenvolvedor ou criar scripts flexíveis, o rico ecossistema do Python oferece várias bibliotecas para lidar com CLI de forma eficiente.

Nesta postagem do blog, nos aprofundaremos no trabalho com CLIs em Python, abordando o seguinte:

• Por que criar uma CLI?
• Módulos Python para construção de CLIs
• Noções básicas de argumentos de linha de comando
• Recursos avançados usando argparse
• Construindo ferramentas CLI com clique
• Tratamento de erros em ferramentas CLI
• Empacotando ferramentas CLI para distribuição

Ao final desta postagem, você estará equipado para criar aplicativos de linha de comando robustos e fáceis de usar.

Por que criar uma CLI?

CLIs são amplamente utilizadas em administração de sistemas, processamento de dados e desenvolvimento de software porque oferecem:

1. Automação: crie scripts de tarefas repetitivas para economizar tempo e reduzir erros.
2. Simplicidade: execute comandos complexos com apenas algumas teclas.
3. Portabilidade: Uma ferramenta CLI bem construída pode ser usada em qualquer máquina sem uma GUI.
4. Ferramentas de desenvolvedor: Muitas ferramentas de desenvolvimento (como git, npm e pip) são baseadas em CLI.

Módulos Python para desenvolvimento CLI

Python oferece várias bibliotecas para construir ferramentas CLI:

1. sys.argv: Acesso direto a argumentos de linha de comando, adequado para scripts pequenos e simples.
2. argparse: Módulo integrado para lidar com argumentos de linha de comando com geração automática de ajuda.
3. click: uma biblioteca poderosa e flexível para criar aplicativos CLI complexos.
4. typer: uma biblioteca moderna construída com base no clique, que usa dicas de tipo Python para facilitar o uso.

Trabalhando com sys.argv

sys.argv é uma maneira básica de acessar argumentos de linha de comando. Ele armazena os argumentos da linha de comando como uma lista, onde o primeiro elemento é sempre o nome do script.

import sys

# Command-line arguments
print(f"Script Name: {sys.argv[0]}")
print(f"Arguments: {sys.argv[1:]}")

Executando o script:

$ python script.py arg1 arg2 arg3
Script Name: script.py
Arguments: ['arg1', 'arg2', 'arg3']

Limitações de sys.argv:

• Sem verificação de tipo: todas as entradas são tratadas como strings.
• Nenhuma mensagem de ajuda integrada: você precisa validar manualmente as entradas e exibir informações de uso.

Construindo CLIs com argparse

O módulo argparse é a biblioteca padrão do Python para criação de CLIs. Ele oferece mais controle do que sys.argv e gera automaticamente mensagens de ajuda e tratamento de erros.

Exemplo básico:

import argparse

parser = argparse.ArgumentParser(description="A simple CLI tool")
parser.add_argument("name", help="Your name")
parser.add_argument("--greet", help="Custom greeting", default="Hello")

args = parser.parse_args()

print(f"{args.greet}, {args.name}!")

Executando o script:

$ python script.py Alice
Hello, Alice!

$ python script.py Alice --greet Hi
Hi, Alice!

Principais recursos do argparse:

1. Argumentos posicionais e opcionais: Defina facilmente parâmetros obrigatórios e opcionais.
2. Verificação de tipo: certifique-se de que o usuário forneça o tipo de dados correto.
3. Escolhas: restrinja entradas a valores específicos usando o parâmetro de escolhas.
4. Mensagens de ajuda: gera ajuda automaticamente com o sinalizador -h ou --help.

Exemplo com verificação de tipo e opções:

parser.add_argument("age", type=int, help="Your age")
parser.add_argument("--format", choices=["json", "xml"], help="Output format")

Executando o script:

$ python script.py Alice 30 --format json

Ferramentas CLI avançadas com clique

click é uma biblioteca mais avançada para criar interfaces de linha de comando. Ele fornece uma abordagem baseada em decorador para definir comandos, subcomandos e opções.

Por que usar o clique?

• Melhor legibilidade: Uma sintaxe mais Pythonica baseada em decorador.
• Validação automática de argumentos: garante que os argumentos sejam validados corretamente.
• Componentes reutilizáveis: comandos, opções e argumentos podem ser facilmente reutilizados em diferentes partes do seu aplicativo.

Exemplo básico usando clique:

import click

@click.command()
@click.option('--name', prompt='Your name', help='The person to greet.')
@click.option('--greet', default="Hello", help='Greeting to use.')
def greet(name, greet):
    """Simple program that greets NAME with a GREET."""
    click.echo(f'{greet}, {name}!')

if __name__ == '__main__':
    greet()

Executando o script:

$ python greet.py --name Alice --greet Hi
Hi, Alice!

Subcomandos com clique:

Você pode criar ferramentas CLI mais complexas com vários subcomandos.

import click

@click.group()
def cli():
    pass

@cli.command()
def start():
    click.echo("Starting the application...")

@cli.command()
def stop():
    click.echo("Stopping the application...")

if __name__ == '__main__':
    cli()

Executando o script:

$ python app.py start
Starting the application...

$ python app.py stop
Stopping the application...

Tratamento de erros em ferramentas CLI

Não importa qual biblioteca você usa, o tratamento de erros é crucial para fornecer uma experiência de usuário tranquila.

Exemplo em argparse:

Se um argumento obrigatório estiver faltando, argparse gerará um erro e exibirá instruções de uso:

$ python script.py
usage: script.py [-h] name
script.py: error: the following arguments are required: name

Tratamento de erros no clique:

Com o clique, você pode gerar exceções personalizadas e lidar com erros normalmente usando decoradores.

@click.command()
@click.option('--count', type=int, help='Number of repetitions')
def repeat(count):
    if count is None or count 







  
  
  Combinando argparse e clique com outras bibliotecas


Para estender a funcionalidade CLI, você pode combinar argparse ou click com outras bibliotecas como os, subprocess ou até mesmo bibliotecas personalizadas.


  
  
  Exemplo: Combinando argparse com os




import os
import argparse

parser = argparse.ArgumentParser(description="File operations CLI")
parser.add_argument("filename", help="Name of the file to check")
parser.add_argument("--create", action="store_true", help="Create the file if it does not exist")

args = parser.parse_args()

if os.path.exists(args.filename):
    print(f"{args.filename} already exists.")
else:
    if args.create:
        with open(args.filename, 'w') as f:
            f.write("New file created.")
        print(f"{args.filename} created.")
    else:
        print(f"{args.filename} does not exist.")




Executando o script:



$ python filecli.py example.txt --create
example.txt created.








  
  
  Empacotando sua ferramenta CLI


Para distribuir sua ferramenta CLI, você pode empacotá-la usando setuptools e torná-la acessível globalmente em qualquer sistema.


  
  
  Etapa 1: Crie um arquivo setup.py




from setuptools import setup

setup(
    name='greet-cli',
    version='0.1',
    py_modules=['greet'],
    install_requires=[
        'click',
    ],
    entry_points='''
        [console_scripts]
        greet=greet:greet
    ''',
)





  
  
  Etapa 2: Instale sua CLI localmente




$ pip install --editable .




Agora, o comando greet está disponível globalmente:



$ greet --name Alice
Hello, Alice!





  
  
  Distribuir no PyPI


Para distribuir sua ferramenta publicamente, crie uma conta PyPI e siga as etapas para enviar seu pacote:


Construa o pacote:



   python setup.py sdist bdist_wheel





Carregue o pacote:



   twine upload dist/*








  
  
  Práticas recomendadas para construção de CLIs




Forneça mensagens de ajuda claras: sempre inclua --help para orientar os usuários.

Validar entradas: Use verificação de tipo e trate exceções normalmente.

Projete comandos intuitivos: certifique-se de que sua estrutura de comandos seja lógica e fácil de usar.

Teste com casos extremos: certifique-se de que sua ferramenta CLI se comporte corretamente mesmo com entradas inválidas.

Modularize seu código: mantenha sua lógica de linha de comando separada de sua funcionalidade principal para testes e manutenção mais fáceis.






  
  
  Conclusão


Python fornece um excelente kit de ferramentas para construir aplicativos de interface de linha de comando (CLI). Esteja você usando o módulo argparse integrado ou o clique com mais recursos, você pode criar ferramentas poderosas e fáceis de usar que podem automatizar fluxos de trabalho, processar dados e aumentar a produtividade.

Agora que você aprendeu os recursos básicos e avançados para trabalhar com CLI em Python, é hora de colocá-los em prática. Crie sua própria ferramenta, compartilhe-a ou até mesmo distribua-a globalmente!




Sinta-se à vontade para entrar em contato com perguntas ou sugestões:

• LinkedIn
• GitHub