datatools-dev/docs/CLI-REFERENCE.es.md

🌐 Idioma: Español · English

Referencia de la CLI

⚠️ Los comandos, banderas y valores de las opciones son idénticos en ambos idiomas. La CLI emite todos sus mensajes en inglés; este documento traduce las explicaciones, no los comandos.

Tres módulos de CLI, uno por cada herramienta Lista:

Módulo	Comando	Propósito
src.cli	python -m src.cli FILE	Buscar duplicados
src.cli_text_clean	python -m src.cli_text_clean FILE	Limpiar texto
src.cli_analyze	python -m src.cli_analyze FILE	Analizador (escaneo de solo lectura)

Cada comando es previsualización por defecto — añade --apply para escribir la salida.

---

Buscar duplicados

python -m src.cli ARCHIVO_ENTRADA [OPCIONES]

Opciones

Generales

• --apply — escribe los archivos de salida (por defecto: previsualización).
• -o, --output RUTA — ruta de salida (por defecto {input}_deduplicated.csv).

Selección de columnas

• -s, --subset COLS — columnas separadas por comas en las que hacer la coincidencia (por defecto: detección automática).
• -k, --key COLS — columnas de clave fuerte; cada una se convierte en una estrategia independiente de coincidencia exacta (fb_id, ein, sku).

Coincidencia difusa

• --fuzzy COLS — columnas separadas por comas para coincidencia difusa.
• -a, --algorithm ALG — levenshtein / jaro_winkler (por defecto) / token_set_ratio.
• -t, --threshold N — similitud 0-100 (por defecto 85).

Normalización

• --normalize COL:TIPO — pares col:tipo separados por comas. Tipos: email, phone, name, address, string.

Tipo	Efecto	Ejemplo
email	minúsculas, elimina puntos de Gmail, elimina +etiqueta	John.Doe+x@gmail.com → johndoe@gmail.com
phone	E.164 (extensión preservada)	(555) 123-4567 ext 100 → +15551234567;ext=100
name	elimina títulos + sufijos + partículas, baja a minúsculas	Dr. Charles de Gaulle Jr. → charles gaulle
address	abreviaturas USPS + nombre de estado → 2 letras, minúsculas	123 Main Street, California → 123 main st ca
string	recorta + colapsa + minúsculas	HELLO WORLD → hello world

Selección del superviviente

• --survivor REGLA — first (por defecto) / last / most-complete / most-recent.
• --date-column COL — obligatoria para most-recent.
• --merge — rellena los huecos del superviviente desde las filas eliminadas.

Revisión interactiva

• --review — pregunta s/n/saltar por cada grupo de coincidencias con diff lado a lado.

Configuración

• --config RUTA — carga toda la configuración desde un JSON.
• --save-config RUTA — guarda la configuración actual en un JSON.

Manejo de archivos

• --sheet NOMBRE|N — nombre de hoja de Excel o índice base 0.
• --encoding ENC — anula la codificación autodetectada.
• --header-row N — fila de encabezado en base 0.

Recetas

# Deduplicación básica con autodetección
python -m src.cli customers.csv [--apply]

# Coincidencia difusa de nombres al 80%
python -m src.cli customers.csv --fuzzy name --threshold 80 --apply

# Múltiples claves fuertes (lógica OR)
python -m src.cli donors.csv --key fb_id,ein --apply

# Fila más completa + fusionar campos faltantes
python -m src.cli contacts.csv --survivor most-complete --merge --apply

# Más reciente + fusión
python -m src.cli contacts.csv --survivor most-recent --date-column updated_at --merge --apply

# Revisión interactiva
python -m src.cli customers.csv --review --apply

# Guardar / cargar perfil
python -m src.cli customers.csv --fuzzy name --threshold 80 --save-config dedup.json
python -m src.cli new.csv       --config dedup.json --apply

# Excel
python -m src.cli data.xlsx --sheet "Sales" --apply

Algoritmos

• jaro_winkler (por defecto) — el mejor para cadenas cortas (nombres); pondera los primeros caracteres.
• levenshtein — ratio de distancia de edición; errores tipográficos y transposiciones.
• token_set_ratio — el mejor para direcciones; ignora el orden de las palabras.

Detección automática

Cuando no se pasan banderas --subset / --fuzzy, las columnas se detectan por su nombre:

Patrón	Algoritmo	Umbral	Normalizador	Clave
Email	exacto	100%	email	fuerte
Teléfono	exacto	100%	phone	fuerte
Nombre	jaro_winkler	85%	name	débil
Dirección	token_set_ratio	80%	address	débil

Reglas de estrategia: claves fuertes → OR independiente; claves débiles → AND emparejadas con cada clave fuerte; sin claves fuertes → las débiles se promueven a independientes; sin patrones → coincidencia exacta en todas las columnas.

Archivos de salida (con --apply)

Archivo	Contenido
{stem}_deduplicated.csv	Datos limpios
{stem}_removed.csv	Filas eliminadas
{stem}_match_groups.csv	_group_id, _is_survivor, _confidence, _matched_on, _original_row + columnas originales

Registro: logs/dedup_YYYYMMDD_HHMMSS.log.

---

Limpiar texto

python -m src.cli_text_clean ARCHIVO_ENTRADA [OPCIONES]

Higiene a nivel de carácter. Ver TECHNICAL.md §10.2 (solo en inglés) para la especificación.

Opciones

Generales

• --apply — escribe la salida (por defecto: previsualización).
• -o, --output RUTA — ruta de salida (por defecto {input}_cleaned.csv).
• --preset NOMBRE — minimal / excel-hygiene (por defecto) / paranoid.

Alcance

• --columns COLS — columnas separadas por comas a limpiar (por defecto: todas las columnas de texto).
• --skip COLS — excluye estas columnas.

Anulaciones por operación (anulan el preset activo)

• --no-trim, --no-collapse, --no-nfc, --nfkc, --no-smart-chars, --no-zero-width, --no-bom, --no-control, --no-line-endings.

Mayúsculas / minúsculas

• --case MODO — upper / lower / title / sentence. O por columna: --case title:name,upper:sku.
• El modo título preserva los tokens en mayúsculas (USA) y deja en minúsculas las partículas internas (of, and).

Auditoría + configuración

• --full-changelog — escribe todos los cambios (por defecto se limita a los primeros 1000).
• --config RUTA / --save-config RUTA.

Archivo

• --sheet, --encoding, --header-row — iguales que en Buscar duplicados.

Presets

Preset	Qué hace
minimal	Solo recorte y colapso.
excel-hygiene (por defecto)	Recorte, colapso, NFC, plegado de caracteres tipográficos, eliminación de caracteres invisibles, eliminación de BOM, eliminación de caracteres de control, normalización de finales de línea.
paranoid	excel-hygiene + plegado de compatibilidad NFKC (con pérdida).

Recetas

# Valores por defecto seguros (previsualiza, luego aplica)
python -m src.cli_text_clean messy.csv [--apply]

# Solo recorte y colapso, sin tocar Unicode
python -m src.cli_text_clean messy.csv --preset minimal --apply

# Nombres en formato título, SKUs en mayúsculas
python -m src.cli_text_clean people.csv --case title:name,upper:sku --apply

# Limpiar solo columnas concretas
python -m src.cli_text_clean orders.csv --columns vendor,product --apply

# Excluir una columna de notas en texto libre
python -m src.cli_text_clean tickets.csv --skip notes --apply

Archivos de salida (con --apply)

Archivo	Contenido
{stem}_cleaned.csv	Datos limpios
{stem}_changes.csv	row, column, old, new, ops_applied (limitado a 1000; --full-changelog quita el límite)

Registro: logs/text_clean_YYYYMMDD_HHMMSS.log.

---

Analizador

python -m src.cli_analyze ARCHIVO_ENTRADA [OPCIONES]

Escaneo de solo lectura; muestra todos los hallazgos del detector sin modificar el archivo.

Opciones

• --sample-rows N — límite de filas escaneadas (por defecto 1000).
• --json — imprime los hallazgos como un array JSON en stdout.
• --strict — sale con código no cero ante cualquier hallazgo warn/error.

Esquema JSON (un objeto por hallazgo)

{
  "id": "smart_punctuation_in_data",
  "severity": "warn",
  "confidence": "high",
  "fix_action": "fold_smart_punctuation",
  "pre_applied": false,
  "tool": "02_text_cleaner",
  "count": 17,
  "description": "17 cell(s) contain curly quotes…",
  "column": null,
  "samples": [{"row": 3, "column": "name", "value": "“Alice”"}]
}

Significado de los campos

• severity — info / warn / error. Solo error bloquea la verificación de la GUI.
• confidence — high (un clic), medium (previsualiza), low (opt-in).
• fix_action — id del algoritmo en src/core/fixes.py. Vacío si es solo informativo.
• pre_applied — true para correcciones ya aplicadas durante la lectura a nivel de bytes.

Detectores

Puntuación tipográfica, espacios NBSP / Unicode, caracteres de ancho cero, encabezados sucios, relleno con espacios, centinelas tipo null, huellas de mojibake, columnas de email con mayúsculas/minúsculas mezcladas, formatos de fecha inconsistentes, filas casi duplicadas, identificadores con ceros a la izquierda, finales de línea mezclados, fallo de decodificación de codificación, presencia de U+FFFD.

Agregar un detector: añade la entrada en analyze.py y la corrección correspondiente en fixes.py. Ningún otro punto de llamada cambia.