Metadata-Version: 2.4
Name: calendary_co
Version: 0.1.1
Summary: Calendario de festivos oficiales y eventos culturales de Colombia (Ley Emiliani)
Author: Alejandro Galicia
Author-email: Alejandro Galicia <iglesiag1908@gmail.com>
License: MIT
Keywords: colombia,holidays,festivos,calendario,cultural-events
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: colombian-holidays>=1.0.0
Requires-Dist: python-dateutil>=2.8.2
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# 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

```powershell
pip install calendary_co
```

Desarrollo local:

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

Con dependencias de desarrollo (pytest):

```powershell
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:

```python
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:

```powershell
cd "LIBRERIAS py/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

```python
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:

```python
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

```python
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):

```python
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](https://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

```powershell
cd "LIBRERIAS py/calendary_co"
python -m pytest tests/ -v
```

## Publicación en PyPI

```powershell
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](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
