calendary-co 0.1.0__tar.gz

calendary_co-0.1.0/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Alejandro Galicia
+
+Se reservan los derechos de autor del titular. En virtud de esta licencia MIT,
+cualquier persona puede usar, copiar, modificar, fusionar, publicar, distribuir,
+sublicenciar y/o vender copias del software, sujeto a las condiciones siguientes.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

calendary_co-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include calendary_co/data/*.json

calendary_co-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: calendary_co
+Version: 0.1.0
+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 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), segment_id="21701_CALI_SEGMENTO")
+# 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), segment_id="21701_CALI_SEGMENTO")
+texto_xml = 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`.
+
+Los eventos municipales y regionales se filtran por `segment_id` con tokens como `_CALI_`, `_IBAGUÉ_`, `_NEIVA_`, `_EL_ESPINAL_`, etc.
+
+## Integración (agente 4)
+
+Instalar `calendary_co` como dependencia del proyecto agente. En el prompt dinámico:
+
+```python
+from datetime import date
+from calendary_co import get_calendar_contexts, format_context_for_prompt
+
+fechas = [date.fromisoformat(d) for d in dias_bloque]
+contexto_text = format_context_for_prompt(
+    get_calendar_contexts(fechas[0], fechas[-1], segmento_id)
+)
+# Inyectar en <contexto_temporal>{contexto_text}</contexto_temporal>
+```
+
+En validación post-LLM:
+
+```python
+from datetime import date
+from calendary_co import validar_temporalidad_mensaje
+
+for item in plan:
+    fecha = date.fromisoformat(item["fecha"])
+    if not validar_temporalidad_mensaje(item["mensaje"], fecha, segmento_id):
+        raise ValueError("Mensaje temporalmente incoherente")
+```
+
+## 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
+
+## Relación con `contact_co`
+
+`contact_co` usa `holidays.Colombia()` para validación legal de contacto. `calendary_co` es independiente y está orientado al contexto temporal de mensajes (prompts y validación). Una migración futura de `contact_co` a `calendary_co` es opcional.

calendary_co-0.1.0/README.md

@@ -0,0 +1,188 @@
+# 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 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), segment_id="21701_CALI_SEGMENTO")
+# 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), segment_id="21701_CALI_SEGMENTO")
+texto_xml = 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`.
+
+Los eventos municipales y regionales se filtran por `segment_id` con tokens como `_CALI_`, `_IBAGUÉ_`, `_NEIVA_`, `_EL_ESPINAL_`, etc.
+
+## Integración (agente 4)
+
+Instalar `calendary_co` como dependencia del proyecto agente. En el prompt dinámico:
+
+```python
+from datetime import date
+from calendary_co import get_calendar_contexts, format_context_for_prompt
+
+fechas = [date.fromisoformat(d) for d in dias_bloque]
+contexto_text = format_context_for_prompt(
+    get_calendar_contexts(fechas[0], fechas[-1], segmento_id)
+)
+# Inyectar en <contexto_temporal>{contexto_text}</contexto_temporal>
+```
+
+En validación post-LLM:
+
+```python
+from datetime import date
+from calendary_co import validar_temporalidad_mensaje
+
+for item in plan:
+    fecha = date.fromisoformat(item["fecha"])
+    if not validar_temporalidad_mensaje(item["mensaje"], fecha, segmento_id):
+        raise ValueError("Mensaje temporalmente incoherente")
+```
+
+## 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
+
+## Relación con `contact_co`
+
+`contact_co` usa `holidays.Colombia()` para validación legal de contacto. `calendary_co` es independiente y está orientado al contexto temporal de mensajes (prompts y validación). Una migración futura de `contact_co` a `calendary_co` es opcional.

calendary_co-0.1.0/calendary_co/__init__.py

@@ -0,0 +1,40 @@
+from .calendar_service import (
+    NIVELES_EVENTO,
+    agrupar_eventos_culturales,
+    consultar_festividades,
+    format_consulta_festividades,
+    format_context_for_prompt,
+    get_active_years,
+    get_calendar_context,
+    get_calendar_contexts,
+    get_calendar_for_year,
+    get_full_calendar,
+    is_in_active_window,
+    nombre_dia_semana,
+    validar_temporalidad_mensaje,
+)
+from .colombia_holidays import get_holiday_name, get_holidays_for_year, is_holiday
+from .municipal_events import get_municipal_events_for_year
+from .types import CalendarContext, CalendarEvent
+
+__all__ = [
+    "CalendarContext",
+    "CalendarEvent",
+    "NIVELES_EVENTO",
+    "agrupar_eventos_culturales",
+    "consultar_festividades",
+    "format_consulta_festividades",
+    "format_context_for_prompt",
+    "get_active_years",
+    "get_calendar_context",
+    "get_calendar_contexts",
+    "get_calendar_for_year",
+    "get_full_calendar",
+    "get_holiday_name",
+    "get_holidays_for_year",
+    "get_municipal_events_for_year",
+    "is_holiday",
+    "is_in_active_window",
+    "nombre_dia_semana",
+    "validar_temporalidad_mensaje",
+]