v0.2.1 — Pulido académico integral del SDK

Pulido académico integral del SDK. Sin cambios en la API pública, cero breaking changes.

• PyPI: https://pypi.org/project/datos-mexico/0.2.1/
• Docs: https://docs.datosmexico.org
• Instalación: pip install --upgrade datos-mexico

---

[0.2.1] — 2026-05-13

Pulido académico integral del SDK sin cambios en la API pública. Cero breaking changes para usuarios existentes. Cambios concentrados en infraestructura de reproducibilidad, metadata académica, sincronización docs↔código, y robustez operacional.

Added

• Snapshot OpenAPI versionado (openapi/openapi.snapshot.json, 14,727 líneas) como registro citable del contrato API al momento del release.
• Detección automática de drift entre snapshot y API live:
  • Workflow continuo openapi-drift.yml en cada push y PR.
  • Workflow cron diario openapi-drift-cron.yml con gestión automática de issues.
  • Política: drift es información, no error; CI no falla por drift.
• Script de actualización del snapshot openapi/update_snapshot.py idempotente.
• Deploy automático de docs a Cloudflare Pages (docs-deploy.yml) en cada push a main que toque docs/, mkdocs.yml, o src/**.
• Test de reproducibilidad permanente del README (tests/test_readme_examples.py): extrae bloques de código del README, valida compile(), y opcionalmente ejecuta contra la API real.
• Coverage report como artifact en GitHub Actions (XML + HTML) con badge en README.
• requirements-dev.txt con hashes SHA256 desde uv.lock para reproducibilidad CI universal.
• Script scripts/sync_requirements.sh para regenerar el lockfile + requirements export.
• Script scripts/regen_docs_figures.py con tres modos (dry-run, --apply, --verify) para mantener cifras vivas sincronizadas con la API.
• Sección "Cortar un release" en docs/contributing.md documentando el proceso completo (10 pasos).
• Sección "Reproducibilidad del entorno" en docs/contributing.md documentando paths uv y pip --require-hashes.
• Sección "Gestión del drift del OpenAPI spec" en docs/contributing.md.
• Sección "Secretos requeridos por CI/CD" en docs/contributing.md.
• Labels openapi-drift y automated en el repositorio GitHub para gestión automática de issues por el cron.

Changed

• CITATION.cff consolidada como fuente única de metadata académica según schema CFF 1.2.0; campo type: software explicitado.
• BibTeX canónico alineado byte a byte en README, docs/citation.md, y notebook Amafore. Tipo @software (no @misc), author corporativo con brace doble {{Equipo de Datos México}} para preservar entidad en parsers BibTeX, URL apuntando al repositorio del código, campos completos (year, month, version, url, publisher, license, note).
• README "Uso rápido" corregido: el primer bloque ya no usa dict-style camelCase incorrecto (stats['totalServidores']) sino atributos snake_case correctos (stats.total_servidores); ahora corre limpio al copia-pegar.
• README "Uso rápido" unificado al patrón context manager with DatosMexico() as client: consistente con docs/quickstart.md.
• 45 bloques de código en docs/ auditados; 30 corregidos para sincronizar con los modelos Pydantic actuales del SDK (tutoriales cdmx, enigh, consar, comparativo; conceptos identidad-contable; tutorial enoe ya estaba sincronizado).
• Convención de conteo de endpoints documentada explícitamente: endpoints HTTP (95/114 cubiertos = 83%) como cifra canónica comparable con APIs institucionales, métodos SDK (97 públicos) como aclaración pedagógica donde aporta valor.
• Workflow tests.yml ahora usa pip install --require-hashes -r requirements-dev.txt para reproducibilidad universal en lugar de pip install -e ".[dev]" sin lock.
• Versiones de GitHub Actions uniformadas: actions/upload-artifact@v7 en los 5 workflows.
• Casing canónico Datos-Mexico en 26 URLs sobre 17 archivos (la organización en GitHub es Datos-Mexico, no datos-mexico).
• docs/contributing.md ampliada de 36 a más de 300 líneas con guía completa de desarrollo (setup uv, tests unit + integration, ruff/mypy, cómo agregar un namespace, mkdocs serve, release process OIDC).
• docs/tutoriales/cdmx.md generalizada la nota sobre sectores test residuales (la API expone sectores con total_servidores=0 cuya cantidad puede variar entre releases).
• Cifras frías refrescadas contra snapshot vigente de la API (servidores CDMX en README y tutorial).
• docs/conceptos/comparativo y docs/index.md con descripción precisa del alcance real de los 7 endpoints de cruce cross-dataset.
• BibTeX del notebook Amafore completado con version, month, publisher, license, note para coincidir con la versión canónica.

Fixed

• README ejemplo "Uso rápido" que crasheaba con TypeError: 'DashboardStats' object is not subscriptable al copia-pegar la primera línea de código en una terminal de usuario.
• Promesas stale en README: eliminada mención "Próximamente: comparativo cross-dataset" cuando el módulo ya existe desde v0.1.0; agregado ENOE a la lista de walkthroughs.
• Conteo de notebooks: corregido de 5 a 6 (off-by-one introducido al agregar el notebook de ENOE).
• Heading: corregido ## Examples a ## Ejemplos (única sección en inglés en README en español).
• docs/api/ directorio vacío eliminado del filesystem local.
• uv.lock ahora committeado para reproducibilidad CI verificable.
• Patrón .env ampliado a .env* en .gitignore para cubrir variantes futuras.

Infrastructure

• 38 commits sobre v0.2.0 organizados en 5 fases de pulido (PR #6 y PR #7).
• Cobertura de tests: 99% (1964 sentencias, 29 sin cubrir).
• Suite: 234 passed, 27 skipped (gated por DATOS_MEXICO_INTEGRATION_TESTS=1).
• mypy --strict, ruff: clean en todo el código fuente.

Notes for citation

CITATION.cff actualizada con version: 0.2.1 y date-released: 2026-05-13. Los BibTeX en README, docs y notebook reflejan los mismos campos. Use cffconvert -f bibtex -i CITATION.cff para generar la cita canónica, o copie directamente el bloque @software{datos_mexico_py, ...} provisto en cualquiera de las tres ubicaciones.