Aritmética de fechas: fin de mes, bisiestos y DST
Curso de fechas 4: 31 de enero + 1 mes en 7 herramientas (28 de feb o 3 de mar), 29 de feb + 1 año, días de 23 h en Madrid y Chile, edades y días hábiles.
Serie: curso de fechas y zonas horarias 4/6 (intermedio). Esta clase es para ti si ya sabes parsear e imprimir fechas (clase 3) y ahora tienes que calcular con ellas: fechas de renovación, periodos de prueba, recordatorios "mañana a la misma hora", edades y plazos de entrega en días hábiles. Al terminar tendrás una sola tabla con lo que devuelven siete herramientas en los casos límite clásicos, y funciones cortas listas para copiar en las reglas donde no se ponen de acuerdo.
La aritmética de fechas parece aritmética de enteros hasta el día 29 del mes. Una suscripción que empezó el 31 de enero se renueva el 28 de febrero en un lenguaje y el 3 de marzo en otro; un recordatorio de "mañana a mediodía" sale una hora antes o después el fin de semana del cambio de hora en Madrid o en Santiago; una fecha de nacimiento del 29 de febrero hace que una función falle una vez cada cuatro años. Si haces apps como freelance para clientes de varios países, te van a pasar las tres. Todo se ejecutó en una Mac con Apple Silicon (M1 Pro) con Python 3.9.6, PHP 8.5.6, Java 26, .NET 10.0.14, Swift 6.4.2, Dart 3.11.5, SQLite 3.51.0 y el shell jsc de macOS, siempre con un TZ=… explícito.
Unidades de calendario vs duraciones fijas
Hay dos tipos de "cantidades de tiempo", y la mayoría de los bugs salen de mezclarlos:
- Una duración fija es un número de segundos: 24 horas son siempre 86,400 s. Java la llama
Duration(PT24H), Pythontimedelta, DartDuration. - Un periodo de calendario se cuenta en el calendario: "1 mes", "1 año", "1 día". Cuántos segundos tiene depende de dónde empiezas. Java lo llama
Period(P1M,P1D), PHPDateInterval.
Java hace visible la diferencia: Duration.ofDays(1) imprimió PT24H y Period.ofDays(1) imprimió P1D. Un mes nunca es una duración fija, y en las zonas con horario de verano, un día tampoco. Y "a 30 días" no es "a un mes": en Python, date(2026,1,31) + timedelta(days=30) dio 2026-03-02.
31 de enero + 1 mes: una tabla, siete herramientas
Febrero de 2026 tiene 28 días, así que "31 de enero más un mes" no tiene una respuesta exacta. Se lo preguntamos a todas:
| Herramienta (lo que llamamos) | 2026-01-31 +1 mes | 2026-03-31 −1 mes | 2028-02-29 +1 año |
|---|---|---|---|
| función de Python (abajo) | 2026-02-28 | 2026-02-28 | 2029-02-28 |
Python date.replace(month=2) |
ValueError: day is out of range for month |
— | ValueError (mismo mensaje) |
Java plusMonths / plusYears |
2026-02-28 | 2026-02-28 | 2029-02-28 |
.NET AddMonths / AddYears |
2026-02-28 | 2026-02-28 | 2029-02-28 |
Swift Calendar.date(byAdding:) |
2026-02-28 | 2026-02-28 | 2029-02-28 |
PHP modify('+1 month'), add(P1M) |
2026-03-03 | 2026-03-03 | 2029-03-01 |
JavaScript setUTCMonth / setUTCFullYear |
2026-03-03 | 2026-03-03 | 2029-03-01 |
Dart DateTime.utc(2026, 2, 31) |
2026-03-03 | 2026-03-03 | (2027-02-29 → 2027-03-01) |
SQLite date(d, '+1 month') |
2026-03-03 | 2026-03-03 | 2029-03-01 |
SQLite con 'floor' |
2026-02-28 | — | 2029-02-28 |
Lee la segunda columna dos veces: en PHP, JavaScript, Dart y SQLite, 31 de marzo menos un mes es 3 de marzo. El algoritmo pone el mes en febrero, conserva el día 31 y normaliza el "31 de febrero" pasando los tres días sobrantes al mes siguiente. Ninguna familia está equivocada; responden preguntas distintas. Ajustar al fin de mes es lo que un equipo de cobranza suele querer decir con "mensual".
La biblioteca estándar de Python no tiene aritmética de meses (el popular relativedelta es un paquete de terceros y no lo usamos aquí). Esta función ajusta, como Java:
import calendar
from datetime import date
def add_months(d: date, n: int) -> date:
y, m = divmod(d.month - 1 + n, 12)
y += d.year; m += 1
return d.replace(year=y, month=m, day=min(d.day, calendar.monthrange(y, m)[1]))
En PHP pide el ajuste de forma explícita con last day of next month (imprimió 2026-02-28). En JavaScript, new Date(Date.UTC(2026, 2, 0)) es "el día 0 de marzo", que imprimió 2026-02-28; úsalo para saber cuántos días tiene un mes.
Sumar meses no es asociativo
Ajustar pierde información. Java imprimió chained -> 2026-03-28 vs plusMonths(2) -> 2026-03-31, y .NET y la función de Python hicieron lo mismo. Para una suscripción, calcula siempre la renovación n desde la fecha ancla original (start.plusMonths(n)), nunca desde la renovación anterior, o un cliente del 31 de enero queda en el día 28 para siempre. El modify('+1 month') encadenado de PHP derivó al revés: 01-31 → 03-03 → 04-03.
Las diferencias tampoco coinciden. Del 2026-01-31 al 2026-03-01, Period.between de Java dijo P1M1D y diff() de PHP dijo 0 months 29 days; solo coincidieron en los 29 días totales.
Años bisiestos: 1900, 2000 y el 29 de febrero
La regla gregoriana: un año es bisiesto si es divisible entre 4, salvo los divisibles entre 100, salvo los divisibles entre 400. Por eso 2000 fue bisiesto y 1900 no. calendar.isleap de Python, Year.isLeap de Java, DateTime.IsLeapYear de .NET y format('L') de PHP coincidieron: 1900 falso, 2000 verdadero. La regla corta y % 4 == 0 difirió de calendar.isleap en exactamente seis años entre 1601 y 2400: [1700, 1800, 1900, 2100, 2200, 2300].
Donde el código se rompe es en el propio 29 de febrero:
Java LocalDate.of(2026, 2, 29) -> Invalid date 'February 29' as '2026' is not a leap year
.NET new DateTime(2026, 2, 29) -> Year, Month, and Day parameters describe an un-representable DateTime.
Python date(2028,2,29).replace(year=2029) -> ValueError: day is out of range for month
replace(year=...) es el bug clásico de aniversarios y renovaciones que "funciona tres años y truena el cuarto". "29 de febrero más un año" fue 2029-02-28 en la función de Python y en Java, y 2029-03-01 en PHP, JavaScript y SQLite.
Un día vs 24 horas: Madrid, México y Chile
Revisamos las transiciones con zdump -v sobre el tzdata instalado. En Europe/Madrid los relojes saltaron de 01:59:59 a 03:00:00 (CET → CEST) el domingo 29 de marzo de 2026 y volvieron de 02:59:59 a 02:00:00 el 25 de octubre: los últimos domingos de marzo y octubre. En America/Mexico_City la última transición fue el 30 de octubre de 2022; después de esa fecha zdump no muestra ninguna, que es el efecto de la eliminación del horario de verano en 2022. America/Bogota y America/Argentina/Buenos_Aires no tienen transiciones entre 2020 y 2027. America/Santiago sí: sale del horario de verano el 5 de abril de 2026 y vuelve a él el 6 de septiembre de 2026, y ese cambio ocurre a medianoche.
Desde el sábado a mediodía antes del cambio de Madrid:
| Herramienta | +1 día | +24 horas |
|---|---|---|
Java ZonedDateTime |
plusDays(1) → 12:00+02:00 |
plusHours(24) → 13:00+02:00 |
| Python datetime con zona | + timedelta(days=1) → 12:00+02:00 |
+ timedelta(hours=24) → 12:00+02:00 |
PHP modify() |
'+1 day' → 12:00+02:00 |
'+24 hours' → 12:00+02:00 |
PHP add(DateInterval) |
P1D → 12:00+02:00 |
PT24H → 13:00+02:00 |
| (mismo código en America/Mexico_City) | 12:00−06:00 | 12:00−06:00 |
"Mañana a la misma hora" fue correcto en todos, y en Madrid fueron solo 23 horas reales (Java Duration.between imprimió 23; los timestamps de PHP difirieron en 82,800 s). La sorpresa es la columna de "+24 horas": los datetimes con zona de Python hacen aritmética de reloj de pared cuando ambos lados comparten tzinfo, así que timedelta(hours=24) cayó a las 12:00 y restar los dos datetimes imprimió 1 day, 0:00:00 aunque pasaron 23 horas; convirtiendo a UTC primero dio 23:00:00. modify('+24 hours') de PHP hizo lo mismo, mientras que add(new DateInterval('PT24H')) sumó 24 horas reales. En Ciudad de México todas las columnas coincidieron.
Chile tiene una trampa extra para quien trabaja con "solo fechas". Como el salto es a medianoche, el 6 de septiembre de 2026 no tiene 00:00:
2026-09-05 atStartOfDay -> 2026-09-05T00:00-04:00[America/Santiago] day length 24 h
2026-09-06 atStartOfDay -> 2026-09-06T01:00-03:00[America/Santiago] day length 23 h
2026-09-07 atStartOfDay -> 2026-09-07T00:00-03:00[America/Santiago] day length 24 h
Java LocalDate.atStartOfDay(zone) devolvió 01:00 para ese día. En Python, datetime(2026, 9, 6, 0, 0, tzinfo=ZoneInfo("America/Santiago")) se construyó sin error con -04:00, pero al pasar a UTC y volver se convirtió en 2026-09-06T01:00:00-03:00. Un reporte que agrupa "desde las 00:00" o un cron de medianoche en Chile lo tiene que tener en cuenta.
Regla práctica: unidades de calendario en la zona del usuario para agendas humanas, UTC para duraciones exactas (timeouts, vencimiento de tokens, límites de tasa).
Edades y días hábiles
La edad es una pregunta de calendario, no una división:
def age(birth, today):
return today.year - birth.year - ((today.month, today.day) < (birth.month, birth.day))
Para alguien nacido el 2000-05-20 devolvió 25 el 2026-05-19 y 26 el 2026-05-20. La tentadora (today - birth).days // 365 devolvió 26 ya desde el 2026-05-14, seis días antes, porque se acumulan los días bisiestos. Con 100,000 pares aleatorios (nacimientos 1950–2010, "hoy" en 2026, semilla 42), days // 365 falló 3,037 veces (3.04%) e int(days / 365.25) todavía 104 veces (0.10%). Para quien nació el 2008-02-29, nuestra función dio 18 el 2027-02-28 y 19 el 2027-03-01; si en años no bisiestos el cumpleaños cuenta el 28 de febrero o el 1 de marzo es una cuestión legal que cambia por país, así que confírmalo antes de fijarlo en el código.
Los días hábiles (lunes a viernes menos feriados) son el otro cálculo de todos los días: plazos de facturas, envíos, trámites. Un bucle día por día es fácil de leer; la versión aritmética cuenta las semanas completas como 5 días y solo recorre el resto:
from datetime import date, timedelta
HOLIDAYS = {date(2026, 1, 1), date(2026, 5, 1), date(2026, 12, 25)} # lista de ejemplo
def bizdays_fast(start: date, end: date, holidays=HOLIDAYS) -> int: # [start, end)
weeks, rest = divmod((end - start).days, 7)
wd = start.weekday()
n = weeks * 5 + sum(1 for i in range(rest) if (wd + i) % 7 < 5)
return n - sum(1 for h in holidays if start <= h < end and h.weekday() < 5)
Las dos versiones devolvieron 258 para 2026 y 9 del 21 de diciembre de 2026 al 4 de enero de 2027. Ese 9 ya esconde un bug: la lista solo tiene el 1 de enero de 2026, así que el Año Nuevo de 2027 contó como hábil. Los feriados cambian por país (México, Colombia, Argentina y España tienen calendarios distintos, y algunos se trasladan a lunes) y por año: son datos que cargas, no constantes en el código.
Medición: bucle vs fórmula
10,000 rangos aleatorios (inicio 2020–2025, de 1 a 1,094 días, semilla 42); las dos funciones coincidieron en todos los pares (comprobado con assert). Mediana de 5 corridas, Python 3.9.6, Mac con Apple Silicon (M1 Pro):
| Función | Tiempo para 10,000 rangos |
|---|---|
| bucle día por día | 1,812.0 ms |
| semanas × 5 + resto | 10.2 ms |
Unas 178 veces más rápida. El bucle sirve para una factura; para un reporte que calcula el vencimiento de cada ticket del año, usa la fórmula y deja el bucle como oráculo en los tests.
Errores comunes → qué pasa realmente → cómo arreglarlo
| Error | Lo que vimos | Arreglo |
|---|---|---|
date.replace(year=y+1) para aniversarios |
ValueError con 2028-02-29 |
ajustar con calendar.monthrange, o decidir 28 de feb vs 1 de mar |
| Renovar desde la renovación anterior | Java: 01-31 → 02-28 → 03-28 | siempre ancla.plusMonths(n) |
+ timedelta(hours=24) con zona |
12:00 del día siguiente, 23 h reales | pasar a UTC, sumar, volver |
modify('+24 hours') en PHP |
mismo resultado de reloj de pared | add(new DateInterval('PT24H')) |
| Suponer que todo día empieza a las 00:00 | Santiago, 2026-09-06: empieza a las 01:00 | atStartOfDay(zone) o rangos en UTC |
days // 365 para edades |
falla el 3.04% de las veces | comparar mes y día |
Límites honestos / notas de versión
- El modificador
floorde SQLite llegó en 3.46; ejecutamos 3.51.0. Las versiones anteriores solo desbordan. - La tabla muestra lo que cada API devolvió en estas versiones. Java, .NET y Swift documentan el ajuste a fin de mes; PHP y JavaScript documentan la normalización de días fuera de rango.
- Python no trae aritmética de meses en la biblioteca estándar.
dateutil.relativedeltaajusta como Java, pero es de terceros y no se ejecutó aquí. - Las fechas de cambio de hora vienen del tzdata instalado en esta Mac (2026d). Los gobiernos cambian las reglas (México en 2022 es el ejemplo), así que léelas del tzdata, nunca de memoria.
- JavaScript se ejecutó solo en
jsc, que no teníaTemporal.
Ejercicios
1. Un gimnasio cobra el mismo día cada mes desde el 2026-08-31. Con la regla de ajuste desde la fecha ancla, lista los tres siguientes cobros. ¿Qué daría el modify('+1 month') encadenado de PHP?
2. Un recordatorio está guardado como 2026-10-24T09:00:00+02:00 en Europe/Madrid y se repite "todos los días a las 9". Tu código le suma 86,400 segundos cada vez. ¿Qué hora local ve el usuario el 25 de octubre, y por qué?
Respuestas
1. Ajustando desde el ancla: 2026-09-30, 2026-10-31, 2026-11-30 (add_months(ancla, n) con n = 1, 2, 3). PHP encadenado: 08-31 + 1 mes = 2026-10-01 (como en nuestra ejecución), luego 2026-11-01 y 2026-12-01: el cliente perdió el cobro de septiembre completo.
2. Las 08:00. Madrid salió del horario de verano el 25 de octubre de 2026 (zdump muestra CEST → CET), así que ese día tuvo 25 horas; 86,400 segundos después de 09:00+02:00 son las 08:00+01:00. Suma un día de calendario en la zona (plusDays(1) en Java, add(P1D) en PHP).
Sigue
- Anterior: Fechas 3/6: parsear y formatear, ISO 8601 y locales
- Siguiente: Fechas 5/6: fechas y horas en bases de datos
- Antes: clase 1/6: timestamps Unix y UTC, clase 2/6: zonas horarias y horario de verano; después: cron, zonas y desfase de relojes
- Probar código que depende de "hoy": tests inestables por tiempo, azar y concurrencia
- Funciones de fecha de SQLite en contexto: SQL básico: SELECT, WHERE y ORDER BY
- Los valores y tipos de Python de arriba: Python básico: tipos y mutabilidad
- Todas las series: ruta de aprendizaje de programación
Preguntas frecuentes
¿Cuánto es 31 de enero más un mes?
Depende de la herramienta. Java plusMonths, .NET AddMonths, Swift Calendar y una función de Python con calendar.monthrange ajustaron a 2026-02-28. PHP modify('+1 month'), JavaScript setMonth, Dart y date() de SQLite sin el modificador floor se desbordaron a 2026-03-03. Decide qué regla necesita tu producto, escríbela y pruébala con los días 29, 30 y 31.
¿Sumar un día es lo mismo que sumar 24 horas?
No cuando cambia el horario de verano. En Europe/Madrid, el sábado 2026-03-28 a las 12:00 más un día de calendario es el domingo a las 12:00, solo 23 horas reales después. Java plusHours(24) y PHP add(new DateInterval('PT24H')) dieron las 13:00; Python timedelta(hours=24) y PHP modify('+24 hours') dieron las 12:00 porque hicieron aritmética de reloj de pared.
¿Cómo calculo bien la edad de una persona?
Resta los años y resta uno más si el cumpleaños de este año todavía no llegó: today.year - birth.year - ((today.month, today.day) < (birth.month, birth.day)). Dividir los días entre 365 falló en el 3.04% de 100,000 casos aleatorios en nuestra prueba, y entre 365.25 todavía en el 0.10%.