calendary_co

Calendario de festivos oficiales y eventos culturales de Colombia, con soporte para la Ley Emiliani (vía colombian-holidays) y ventana rodante de 3 años (año actual + 2 siguientes).

Instalación

pip install calendary_co

Desarrollo local:

pip install -e "ruta/a/LIBRERIAS py/calendary_co"

Con dependencias de desarrollo (pytest):

pip install -e "ruta/a/LIBRERIAS py/calendary_co[dev]"

Ventana rodante de años

El paquete precalienta automáticamente el año en curso y los dos siguientes. No hace falta añadir años manualmente cada enero:

from datetime import date
from calendary_co import get_active_years, get_full_calendar

# Con fecha de referencia (útil en tests)
ref = date(2026, 7, 2)
print(list(get_active_years(ref)))  # [2026, 2027, 2028]

calendario = get_full_calendar(ref)  # {2026: [...], 2027: [...], 2028: [...]}

Consultas fuera de la ventana activa siguen funcionando (cálculo bajo demanda).

Demo rápido

Script de prueba incluido en el repositorio:

cd "/calendary_co"
pip install -e .
python demo_calendary.py

Muestra festivos y eventos culturales entre dos fechas (edita FECHA_INICIO y FECHA_FIN en el archivo).

API principal

Festivos oficiales

from datetime import date
from calendary_co import is_holiday, get_holiday_name, get_holidays_for_year

d = date(2026, 7, 20)
is_holiday(d)           # True (festivo o domingo)
get_holiday_name(d)     # "Día de la Independencia (Independence Day)"
get_holidays_for_year(2026)  # lista de (fecha, nombre), 18 festivos legales

Consulta por rango (recomendado)

Solo festivos nombrados y eventos culturales entre dos fechas, con día de la semana en español:

from datetime import date
from calendary_co import consultar_festividades, format_consulta_festividades

inicio = date(2026, 6, 1)
fin = date(2026, 6, 30)

resultados = consultar_festividades(inicio, fin)

# Filtrar por ciudad (opcional):
# consultar_festividades(inicio, fin, ciudad="Cali")

# Filtrar por nivel (opcional):
# consultar_festividades(inicio, fin, niveles=["nacional"])
# consultar_festividades(inicio, fin, niveles=["municipal", "regional"])
# consultar_festividades(inicio, fin, niveles=["municipal"])

# resultados["festivos_oficiales"]  -> festivos legales (siempre, independiente del filtro niveles)
# resultados["eventos_culturales_rangos"]  -> culturales agrupados por fechas
# resultados["niveles_aplicados"]  -> niveles usados en la consulta
# resultados["dias"]  -> detalle por dia (uso avanzado)

print(format_consulta_festividades(resultados, inicio, fin))

No incluye días vacíos (sin festivo nombrado ni evento cultural). Los domingos sin actividad cultural no aparecen.

Contexto detallado para un día o rango

from datetime import date
from calendary_co import get_calendar_context, get_calendar_contexts, format_context_for_prompt

ctx = get_calendar_context(date(2026, 12, 27), ciudad="Cali")
# ctx.is_holiday_or_sunday, ctx.holiday_name, ctx.cultural_events, ctx.season

contextos = get_calendar_contexts(date(2026, 7, 14), date(2026, 7, 20), ciudad="Cali")
texto = format_context_for_prompt(contextos)

Validación de temporalidad

Evita mensajes incoherentes (por ejemplo, “Feliz Navidad” en julio):

from datetime import date
from calendary_co import validar_temporalidad_mensaje

validar_temporalidad_mensaje("Feliz Navidad", date(2026, 7, 20))  # False
validar_temporalidad_mensaje("Recuerda tu pago", date(2026, 7, 20))  # True

Eventos incluidos

Festivos oficiales: 18 festivos legales + domingos (Ley Emiliani, Pascua, traslados).

Culturales nacionales: Velitas, Novena de Aguinaldos, Amor y Amistad, Día de la Madre/Padre, Halloween, Semana Santa, etc.

Municipales: ferias y fiestas patronales por municipio (referencia MINCIT), incluyendo San Juan (24 de junio) y Fiestas de San Juan y San Pedro en Tolima y Huila. San Pedro y San Pablo es festivo oficial (Ley Emiliani).

Ferias regionales: Carnaval de Barranquilla, Feria de Cali, Feria de las Flores, Leyenda Vallenata, Carnaval de Negros y Blancos, Feria de Manizales, y más en municipal_events.py.

colombia.co: eventos adicionales desde colombia.co/eventos (API /mark-events/events/{año}/{mes}/es), empaquetados en calendary_co/data/colombia_co_events.json. Actualizar con python scripts/sync_colombia_co_events.py.

Opcionalmente puedes filtrar eventos regionales y municipales pasando ciudad="Nombre del municipio" en las consultas.

Tests

cd "/calendary_co"
python -m pytest tests/ -v

Publicación en PyPI

pip install --upgrade build twine
python -m build
python -m twine upload dist/*

Paquete: pip install calendary_co

Licencia

MIT — Copyright (c) 2026 Alejandro Galicia. Derechos de autor reservados al titular; la licencia permite uso, modificación y distribución libre en proyectos personales, comerciales y de código abierto, con inclusión del aviso de copyright. Ver LICENSE.

Dependencias

• colombian-holidays>=1.0.0 — festivos oficiales Colombia (Ley Emiliani)
• python-dateutil>=2.8.2 — cálculo de Pascua y eventos móviles