Estructura de archivos para CLI con Click

Crear un CLI en Python con Click es más claro y mantenible cuando organizas bien tu proyecto, defines comandos con decoradores y configuras setup.py para instalar un ejecutable. Aquí tienes el esqueleto base: estructura de archivos, comandos create/list/update/delete y un flujo de instalación editable en un virtualenv.

¿Cómo organizar la estructura de archivos en Python para un CLI con Click?

Diseñar con múltiples archivos hace el código más legible y escalable. Un subdirectorio funciona como módulo en Python y agrupa responsabilidades específicas.

• Un directorio raíz para el proyecto.
• Un archivo de entrada: PV.py como punto de entrada del CLI.
• Un módulo clients/ con comandos en commands.py.
• Un setup.py para instalar el ejecutable del CLI.

Estructura sugerida:

PlatziVentas/
├─ PV.py
├─ setup.py
└─ clients/
   └─ commands.py

Claves prácticas:

• Subdirectorios como módulos: agrupan funciones relacionadas.
• Responsabilidad única por archivo: hace el mantenimiento más simple.

¿Qué comandos y decoradores definen el CLI de clientes?

Los decoradores de Click convierten funciones en comandos. Se usa @click.group() para declarar un grupo y @clients.command() para registrar subcomandos. Con @click.pass_context se recibe un contexto mutable; aquí se inicializa como diccionario literal vacío.

¿Cómo inicializar el contexto con click pass context?

En tu punto de entrada se importa Click, se define un group y se inicializa el objeto contexto:

# PV.py
import click

@click.group()
@click.pass_context
def CLI(ctx):
    # inicializar el contexto como diccionario literal vacío
    ctx.obj = {}

# registrar el grupo de clientes desde el módulo clients.commands
from clients import commands as clients_commands
CLI.add_command(clients_commands.all)

Puntos clave:

• ctx.obj = {}: contexto listo para compartir datos entre comandos.
• Legibilidad: se importa clients.commands como alias y se registra con add_command.

¿Cómo convertir funciones en comandos del grupo clients?

Define el grupo clients y sus comandos básicos. Los docstrings alimentan la ayuda de Click, es decir: la interfaz basada en texto del CLI.

# clients/commands.py
import click

@click.group()
def clients():
    """Manages the client's life cycle."""
    pass  # placeholder para evitar error

@clients.command()
@click.pass_context
def create(ctx, name, company, email, position):
    """Create a new client."""
    pass

@clients.command("list")  # evitar colisión con palabra reservada list
@click.pass_context
def list_cmd(ctx):
    """List all clients."""
    pass

@clients.command()
@click.pass_context
def update(ctx, uid):
    """Updates a client."""
    pass

@clients.command()
@click.pass_context
def delete(ctx, uid):
    """Delete a client."""
    pass

# alias para registrar todo el grupo desde PV.py
all = clients

Detalles importantes:

• Decoradores: @clients.command() marca cada función como comando.
• Docstrings como ayuda: Click los muestra en --help.
• Convención de espacios: dos líneas en blanco entre funciones de nivel módulo.
• Alias all: simplifica el registro del grupo completo.

¿Cómo instalar y ejecutar el comando con setup.py y un virtualenv?

La instalación convierte tu CLI en un ejecutable del sistema: sin invocar directamente al intérprete de Python. Se declara el nombre del comando, la versión y el entry point hacia CLI dentro de PV.py.

Ejemplo mínimo de setup.py:

# setup.py
from setuptools import setup

setup(
    name='PV',            # nombre del comando instalado
    version='0.1',        # versión semántica
    py_modules=['PV'],    # módulo de entrada
    install_requires=[
        'click',          # dependencia principal
    ],
    entry_points={
        'console_scripts': [
            'PV=PV:CLI',  # comando=modulo:funcion_de_entrada
        ],
    },
)

Instalar en modo editable dentro de un virtualenv permite ver cambios al instante:

# crear y activar el ambiente virtual
virtualenv -p python3 venv
source venv/bin/activate

# instalar en modo editable
pip install --editable .

# verificar e inspeccionar la ayuda
which PV
PV --help
PV clients --help

Qué observarás al usar --help:

• Uso y opciones del comando raíz.
• El grupo clients con su descripción: "Manages the client's life cycle".
• Subcomandos disponibles: create, list, update, delete.

¿Te gustaría extender estos comandos con opciones y validar entradas? Deja tus dudas o ideas para explorar el siguiente paso juntos.