Opções de linha de comando e análise de argumentos com argparse em Python

Interfaces de linha de comando (CLIs) são uma das maneiras mais rápidas e eficazes de interagir com softwares. Elas permitem que você execute comandos diretamente, resultando em processamento mais rápido e recursos avançados. Desenvolvedores frequentemente criam CLIs em Python para diversas aplicações, utilitários e scripts de automação — permitindo processar dinamicamente a entrada do usuário. É aqui que entra o módulo argparse do Python.

O módulo argparse simplifica o processamento de argumentos da linha de comando, permitindo que desenvolvedores criem ferramentas interativas e fáceis de usar. Como parte da biblioteca padrão, ele permite definir, processar e validar entradas sem a necessidade de uma lógica complexa.

Neste artigo, abordaremos os conceitos principais, exemplos úteis e recursos avançados do módulo argparse, para que você possa começar a construir ferramentas de linha de comando robustas imediatamente.

Como usar argparse em Python para interfaces de linha de comando

Copiar link

Passo 1: Importar o módulo

Copiar link

Importe o módulo no seu script Python:

import argparse

Isso habilita o parsing de argumentos .py a partir da linha de comando.

Passo 2: Criar um objeto ArgumentParser

Copiar link

A classe ArgumentParser é a classe principal da API do módulo argparse. Para usá-la, comece criando uma instância:

parser = argparse.ArgumentParser(description="A Hostman tutorial on Python argparse.")

Aqui:

• description descreve a função do programa e será exibida quando alguém executar --help.

Passo 3: Adicionar entradas e opções

Copiar link

Defina os parâmetros que seu programa aceitará usando add_argument():

parser.add_argument('filename', type=str, help="Name of the file to process")

parser.add_argument('--verbose', action='store_true', help="Enable verbose mode")

Explicação:

• filename é obrigatório.

• --verbose é opcional e ativa o modo verboso.

Passo 4: Fazer o parsing da entrada do usuário

Copiar link

Use parse_args() para processar os argumentos fornecidos:

args = parser.parse_args()

Isso armazena os valores como atributos do objeto args.

Passo 5: Acessar os dados processados

Copiar link

Exemplo:

print(f"File to process: {args.filename}")

if args.verbose:

    print("Verbose mode enabled")

else:

    print("Verbose mode disabled")

Exemplos de uso do CLI

Copiar link

Processamento de arquivo sem modo verboso

Copiar link

python3 file.py example.txt

Processamento de arquivo com modo verboso

Copiar link

python3 file.py example.txt --verbose

Exibir ajuda

Copiar link

python3 file.py --help

Exemplos comuns do uso de argparse

Copiar link

Exemplo 1: Adicionar valores padrão

Copiar link

Em alguns casos, argumentos opcionais precisam de valores pré-definidos. Neste exemplo, --timeout recebe um valor padrão de 30 segundos:

import argparse

parser = argparse.ArgumentParser(description="Demonstrating default argument values.")

parser.add_argument('--timeout', type=int, default=30, help="Timeout in seconds (default: 30)")

args = parser.parse_args()

print(f"Timeout value: {args.timeout} seconds")

Explicação

• Importação do módulo

• Criação do ArgumentParser

• Adição do argumento --timeout com valor padrão

• Parsing com parse_args()

Caso 1: valor padrão usado

python file.py

Caso 2: valor personalizado

python file.py --timeout 60

Exemplo 2: Utilizando choices

Copiar link

O parâmetro choices permite restringir um argumento a um conjunto de valores válidos:

parser.add_argument('--mode', choices=['basic', 'advanced'], help="Choose the mode of operation")

Caso 1: valor válido

python3 file.py --mode basic

Caso 2: sem entrada

python3 file.py

Caso 3: valor inválido

python3 file.py --mode intermediate

Exemplo 3: Manipulando múltiplos valores

Copiar link

Use nargs='+' para permitir múltiplos valores em um único argumento:

parser.add_argument('--numbers', nargs='+', type=int, help="List of numbers to process")

Caso 1: múltiplos números

python3 file.py --numbers 10 20 30

Caso 2: um número

python3 file.py --numbers 5

Caso 3: sem entrada

python3 file.py

Caso 4: entrada inválida

python3 file.py --numbers 10 abc 20

Exemplo 4: Argumentos opcionais obrigatórios

Copiar link

Embora argumentos com -- sejam opcionais por padrão, você pode torná-los obrigatórios com required=True:

parser.add_argument('--config', required=True, help="Path to the configuration file")

Caso 1: entrada válida

python3 file.py --config settings.json

Caso 2: argumento obrigatório ausente

python3 file.py

Recursos avançados

Copiar link

Flags booleanas

Copiar link

parser.add_argument('--debug', action='store_true', help="Enable debugging mode")

Agrupando argumentos relacionados

Copiar link

group = parser.add_argument_group('File Operations')

group.add_argument('--input', type=str, help="Input file")

group.add_argument('--output', type=str, help="Output file")

Argumentos mutuamente exclusivos

Copiar link

group = parser.add_mutually_exclusive_group()

group.add_argument('--json', action='store_true', help="Output in JSON format")

group.add_argument('--xml', action='store_true', help="Output in XML format")

Conclusão

Copiar link

O módulo argparse facilita a criação de CLIs robustos para manipular argumentos da linha de comando em Python. Desde opções simples até recursos avançados como choices e nargs, desenvolvedores podem criar ferramentas práticas, confiáveis e amigáveis ao usuário. Nomear argumentos de forma clara e escrever boas descrições torna seus scripts mais compreensíveis e fáceis de manter.