Zonas Horarias en Python

<div class="centered-container" style="height: 100dvh">
<div class="main-title">
<p>Zonas Horarias en Python</p>

<p class="main-subtitle">Todo lo que ojalá no necesitases</p>

</div>
<div class="main-title-info">
<div class="author">
    Paul Ganssle
</div>

<div class="link">
    <span style="font-size: 1em;"><em>Esta charla en GitHub:
        <a href="https://github.com/pganssle-talks/2026-pycon-us-zonas-horarias">pganssle-talks/2026-pycon-us-zonas-horarias</a></em>
    </span>
</div>

Notes:

¡Hola, bienvenidos a mi charla!

(Si no me ha presentado:) Soy Paul Ganssle, desarrollador en Google y Core Developer de CPython.

Hace ya más de doce años, arreglé un bug en `dateutil`, y luego uno más, ➡️ y aumentó hasta que me encontré con más pericia en este tema de la que parece sano, así que hoy os voy a endilgar lo que sé del tema de zonas horarias, para que vosotros también podáis estar agobiados por el conocimiento.

Lo siento, las puertas ya están cerradas, entonces es demasiado tarde para huir. Así que sí, vamos al lío.

[45s; T: 45s]

# Introducción

## UTC

- Zona horaria de referencia
- Avanza a casi un segundo por segundo (¿qué son unos segundos intercalares entre amigos?)

</div>
<div class="bullets-with-header">

## Zonas horarias vs. desplazamientos

<ul class="fragment" data-fragment-index="1">
    <li><tt>UTC-6</tt> es un desplazamiento</li>
    <li><tt>America/Chicago</tt> es una zona horaria / un huso horario</li>
    <li><tt>CST</tt> es una abreviatura poco fiable que depende mucho de su contexto:
        <ul>
            <li>Central Standard Time (<tt>UTC-6</tt>)</li>
            <li>Cuba Standard Time (<tt>UTC-5</tt>)</li>
            <li>China Standard Time (<tt>UTC+8</tt>)</li>
        </ul>
    </li>
</ul>

</div>

Notes:

Empecemos por lo fácil, aclarando qué es el UTC, que mencionaré muchas veces en esta charla. El UTC es la zona de referencia; es el cero respecto al cual se miden los desplazamientos.

Debería ser un reloj que avance de manera monótona y lineal, pero los comités de estándares parecen odiarnos, así que han puesto segundos intercalares. Entonces, aunque es mejor que una zona con cambios de horario, el UTC tampoco está libre de complicaciones.

➡️ Otro concepto importante es la diferencia entre zonas horarias y desplazamientos. "UTC menos seis" es un desplazamiento (u *offset*). Significa que, para obtener la hora local, hay que restar seis horas al UTC.

"America/Chicago" es una zona horaria, un conjunto de reglas que nos dicen cómo varían los desplazamientos en función del tiempo, y normalmente están asociadas a una región del mundo.

Y quizás hayáis visto algo como "CST". "CST" es una abreviatura que depende totalmente del contexto. En Chicago significa *Central Standard Time*, que es UTC-6. Pero si estás en Cuba, es UTC-5, y en China es *China Standard Time*, que es UTC+8.

Un consejo: nunca confiéis en estas abreviaturas. No intentéis obtener una zona horaria específica de ellas; no deis por hecho que tengan un significado único y ni siquiera podéis asumir que todas las zonas tengan una abreviatura asociada.

[1m 45s; T: 2m 30s]

# Zonas horarias complejas
<div class="centered-container" style="justify-content: space-around">

<style>
img.tzmap {
    max-height: 50dvh;
}
</style>

## Desplazamientos no enteros

- `Australia/Adelaide` (+09:30)
- `Asia/Kathmandu` (+05:45)
- `Africa/Monrovia` (+00:44:30) (Antes de 1979)

</div>
</div>
</div>

Notes:

Vale, ya tenemos claros los conceptos básicos, así que hemos llegado a la parte casi obligatoria de cualquier charla sobre zonas horarias: esa en la que el ponente os cuenta las aberraciones estrafalarias que la gente ha perpetrado con su medición del tiempo local.

Quizás tengas un cuñado que crea que solo hay veinticuatro zonas horarias y que avanzan en incrementos de una hora respecto al UTC, así tal cual. Pero la realidad es más compleja, ➡️ tal que así. Podéis ver que en ➡️ Australia o la India hay zonas con desplazamientos que son múltiplos de media hora, en Nepal hay una de quince minutos, y en los datos históricos hay zonas con desplazamientos que ni siquiera eran de minutos enteros.

[45s; T: 3m 15s]

## Cambio de desplazamiento sin cambio de estatus de horario de verano

<ul>
    <li>
        Venezuela, 2007
        <ul>
            <li><tt>VET (-4 STD) → VET (-4:30 STD) 2007-12-09</tt></li>
        </ul>
    <li>
        Singapur, 1982
        <ul>
            <li><tt>SGT (+7:30 STD) → SGT (+8 STD) 1982-01-01</tt></li>
        </ul>
    </li>
</ul>

</div>
<div class="bullets-with-header" style+"padding: 0.5em">

## Cambio de estatus de horario de verano sin cambio de desplazamiento

<ul>
    <li>
    Portugal, 1992
    <ul>
        <li><tt>WET (+0 STD) → WEST (+1 DST) 1992-03-29</tt></li>
        <li><tt>WEST <span class="fragment custom highlight-current-fragment" data-fragment-index="3">(+1 DST)</span> → CET <span class="custom fragment highlight-current-fragment" data-fragment-index="3">(+1 STD)</span> 1992-09-27</tt><br/></li>
    </ul>
    </li>

    <li>
    Portugal, 1996
    <ul>
        <li><tt>CET  <span class="fragment custom highlight-current-fragment" data-fragment-index="4">(+1 STD)</span> -> WEST <span class="fragment custom bolds highlight-current-fragment" data-fragment-index="4">(+1 DST)</span>  1996-03-31</tt></li>
        <li><tt>WEST (+1 DST) -> WET  (+0 STD)  1996-10-27</tt></li>
    </ul>
    </li>
    </ul>

</div>

Notes:

Además, puede ser que tu cuñado crea que el desplazamiento del UTC solo cambia debido a la hora de verano y viceversa.

➡️ Pero de vez en cuando hay localidades que cambian su desplazamiento por motivos ajenos a los cambios estacionales.

➡️ Por ejemplo en Portugal, en mil novecientos noventa y dos, decidieron que querían usar la zona horaria de Europa Central en vez de la de Europa Occidental, adelantando su desplazamiento estándar una hora.

Para realizar este cambio, cuando su hora de verano iba a acabar, ➡️simplemente no cambiaron los relojes, sino que cambiaron la interpretación de su zona horaria a 'horario estándar'. Lo cual es muy conveniente para los humanos, pero te romperá el código si asumes que el horario de verano no va a terminar sin un cambio de reloj.

De paso, en mil novecientos noventa y seis, decidieron que el sol no debería ponerse después de la medianoche y regresaron a su zona horaria anterior,  ➡️ con la misma forma de transicionar, pero al revés.

Vale, entonces ya conocemos que el desplazamiento estándar puede cambiarse, pero seguramente o una zona tiene hora de verano o no la tiene, ¿no? O sea, o hay dos cambios al año o cero, ¿cierto?

[1m 30s; T: 4m 45s]

## Más de un cambio de DST al año

<ul>
    <li>
    Marruecos, 2012
    <ul>
        <li data class="fragment custom highlight-current-fragment" data-fragment-index="1"><tt>WET  (+0 STD) → WEST (+1 DST)  2012-04-29</tt></li>
        <li data class="fragment custom highlight-current-fragment" data-fragment-index="2"><tt>WEST (+1 DST) → WET  (+0 STD)  <span class="fragment custom highlight-current-fragment" data-fragment-index="4">2012-07-20</span></tt></li>
        <li data class="fragment custom highlight-current-fragment" data-fragment-index="3"><tt>WET  (+0 STD) → WEST (+1 DST)  <span class="fragment custom highlight-current-fragment" data-fragment-index="4">2012-08-20</tt></li>
        <li><tt>WEST (+1 DST) → WET  (+0 STD)  2012-09-30</tt></li>
    </ul>
    </li>
</ul>
</div>
<div class="centered-container" style="height: unset;">
<span >... y en Marruecos durante 2013-2018, en Egipto en 2010 y 2014, y en Palestina en 2011.</span>
</div>
</div>

Notes:

Por supuesto que no. Un contraejemplo es Marruecos, que durante varios años tuvo dos transiciones de hora al año.

Por ejemplo, en dos mil doce cambiaron a la hora de verano en ➡️ abril, pero en ➡️ julio volvieron a la hora estándar durante un mes y después ➡️ regresaron a la hora de verano durante lo que quedaba de verano. ¿Y por qué? Parece muy raro hasta que te das cuenta de que Marruecos es un país de mayoría musulmana, y en dos mil doce ➡️ ese mes era el mes de Ramadán, durante el cual los musulmanes no comen antes del anochecer.

De repente, esa hora que sobra antes de la puesta del sol ya no te hace tanta gracia, ¿no? Así que suspendían el horario de verano. Hoy eso ya no ocurre porque han adoptado la hora de verano permanente, excepto durante el Ramadán; entonces su zona parece más normal, salvo por la extraña brevedad de su hora de verano, o sea, su hora de invierno, porque hoy en día su hora normal es la de verano.

Pues nada, ya sabemos que la gente es muy rara con sus cambios de reloj, pero seguro que este tipo de cosa solo sucede a las tantas de la madrugada y sus travesuras no se van a extender a la mitad del día, cierto?

[1m 30s; T: 6m 15s]

## Días perdidos

**Isla de Navidad (Kiritimati), 31 de diciembre de 1994 (`UTC-10 → UTC+14`):**
<div class="small-spacer"></div>

```python
>>> dt_antes = datetime(1994, 12, 30, 23, 59, tzinfo=ZoneInfo("Pacific/Kiritimati"))
>>> dt_despues = sumar_absoluto(dt_antes, timedelta(minutes=2))

>>> print(dt_antes)
1994-12-30 23:59:00-10:00

>>> print(dt_despues)
1995-01-01 00:01:00+14:00
```

</div>

También Samoa el 29 Enero 2011
<div class="small-spacer"></div>
<span class="fragment confetti-trigger" aria-hidden="true" style="position:absolute;"></span>
</div>

Notes:

Por desgracia, ni esto es verdad. En mil novecientos noventa y cuatro, en Kiribati (que se pronuncia 'kiribas'), decidieron que querían estar al otro lado de la línea internacional de cambio de fecha. Se supone que esto tiene que ver con alinear su medición del tiempo con sus socios comerciales o algo así; eso da igual; lo importante es que, para realizar este cambio, ¡se saltaron el treinta y uno de diciembre! Así que eran las once y cincuenta y nueve de la noche del treinta de diciembre y un minuto después... ➡️ ¡feliz año nuevo!

SKIP THIS PART:

Y quizá digas: 'Pues esto era una cosa de la antigüedad. Eran los noventa, estábamos repartiendo direcciones de IPv4 a mansalva y viendo **Friends**; claro que eso no podría pasar hoy, ¿no?'. Pero hace solo quince años, en dos mil once, lo mismo ocurrió en Samoa.

[45s; T: 7m 00s]

## Días dobles

**Atolón de Kwajalein, 1969**

```python
>>> dt_antes = datetime(1969, 9, 30, 11, 59, tzinfo=ZoneInfo("Pacific/Kwajalein"))
>>> dt_despues = sumar_absoluto(dt_antes, timedelta(minutes=2))

>>> print(dt_antes)
1969-09-30 11:59:00+11:00

>>> print(dt_despues)
1969-09-30 12:01:00+11:00
```

</div>

Notes:

E, históricamente, ha habido sitios que han ido en la dirección contraria también. En el atolón de Kwajalein, en mil novecientos sesenta y nueve, ¡el treinta de septiembre pasó dos veces!

Entonces sí, seguro que hemos llegado al fondo del asunto. Estamos convencidos de que los cambios de reloj pueden ocurrir en cualquier época del año, a cualquier hora del día, millones de veces al año... de acuerdo. Pero seguramente puedo contar con una cosa: que si sé la ubicación de alguien, sé la zona que se aplica. Aunque imagino que podéis vaticinar lo que viene...

[45s; T: 7m 45s]

<div class="fragment disappearing-fragment nospace-fragment fade-out" data-fragment-index="1">
    <h2 style="margin-top: 0.5em; font-family: monospace">Asia/Shanghai</h2>
</div>
<div class="fragment nospace-fragment fade-in" data-fragment-index="1">
    <h2 style="margin-top: 0.5em; font-family: monospace">Asia/Urumqi</h2>
</div>

Notes:

Al gobierno de China le parece una buena idea tener solo un desplazamiento para todo el país. Un país que normalmente abarcaría tres o cuatro zonas usa el UTC más ocho por todas partes. Esto le viene bien a Pekín, donde es el desplazamiento natural, pero en Xinjiang, en el extremo occidental de China, el amanecer ocurre a las cuatro y media de la mañana, lo que le viene... menos bien. Así que, mientras los trenes y las oficinas del gobierno observan el UTC más ocho, ➡️ los locales tienden a observar el UTC más seis, pero no todos los locales.

De hecho, según Wikipedia, lo que normalmente decide si usas el UTC más ocho o el UTC más seis es si formas parte del pueblo uigur, que es un grupo étnico minoritario. Así que esta puede ser una zona horaria de ubicación y... ¿raza?

[1m 15s; T: 9m 00s]

# ¿Por qué narices necesitamos zonas horarias?

```python
from dateutil import rrule as rr
from datetime import datetime, UTC
from zoneinfo import ZoneInfo

# Fin de jornada en Nueva York
horas_de_cerrar = rr.rrule(freq=rr.DAILY, byweekday=(rr.MO, rr.TU, rr.WE, rr.TH, rr.FR),
                           byhour=17, dtstart=datetime(2023, 3, 8, 17), count=5)

NYC = ZoneInfo("America/New_York")
```

<div>

```python
for dt in horas_de_cerrar:
    print(dt.replace(tzinfo=NYC))
```

</div>

<div>

```python
# Obtener fin de jornada en UTC
for dt in horas_de_cerrar:
    print(dt.replace(tzinfo=NYC).astimezone(UTC))
```

</div>

</div>
</div>

</div>

Notes:

Vale, ya os he metido un poco de miedo, y quizás os preguntéis: "Ostras, menudo follón, ¿no podemos simplemente usar UTC para todo?"

Y la respuesta es que no, no podéis, porque el UTC no es una abstracción natural para la mayor parte del mundo. La gente organiza su vida según la posición del sol.

Así que, en el mundo real, si quieres representar la hora que marca el reloj de pared, hay que utilizar una abstracción que capture el tiempo tal y como se observa.

Si quieres representar el fin de jornada en Nueva York, es jarto conveniente hacerlo con una regla que diga "de lunes a viernes a las cinco", en lugar de algo que gire en torno al UTC, donde a veces son las veintidós y otras las veintiuno.

[1m 15s; T: 10m 15s]

.egypt-panel .tz-arrow-wrap.up {
    .tz-label {
        margin-bottom: 0.5em;
        margin-top: 1.25em;
    }
}

.egypt-panel .tz-arrow-wrap.up::before {
  top: 15px;
  height: calc(100% - 15px);
}
.egypt-panel .tz-arrow-wrap.up::after {
  top: 0;
  bottom: auto;
  border-left: 7px solid transparent;
  border-right: 7px solid transparent;
  border-bottom: 15px solid rgba(0, 0, 0, 0.6);
  border-top: none;
}
.egypt-panel .db-icon {
  position: relative;
  width: 3.5em;
  height: 2.2em;
  margin: 0.1em auto;
}
.egypt-panel .db-icon::before {
  content: '';
  position: absolute;
  top: 0;
  left: 0;
  right: 0;
  height: 0.65em;
  background: #b4cce0;
  border: 2px solid #5a7a9a;
  border-radius: 50%;
  z-index: 1;
}
.egypt-panel .db-icon::after {
  content: '';
  position: absolute;
  top: 0.32em;
  left: 0;
  right: 0;
  bottom: 0;
  background: linear-gradient(to right, #8aaccc 0%, #b4cce0 50%, #8aaccc 100%);
  border: 2px solid #5a7a9a;
  border-top: none;
  border-bottom-left-radius: 50% 35%;
  border-bottom-right-radius: 50% 35%;
}
.egypt-panel .egypt-cell img {
  max-width: 100%;
  object-fit: contain;
  padding: 0.5em;
}
</style>

<div class="bullet-container">
<div class="bullets-with-header">
<div class="egypt-panel">
  <div class="egypt-date">01 Julio 2016</div>
  <div class="egypt-date">04 Julio 2016</div>
  <div class="egypt-date">09 Julio 2016</div>
  <div class="egypt-cell">
    <div class="dt-convert">
      <span>2016-07-09 <span class="fragment highlight-current-fragment" data-fragment-index="1">13:00:00 EEST</span></span>
      <div class="tz-arrow-wrap"><span class="tz-label">Africa/Cairo</span></div>
      <span>2016-07-09 10:00:00 UTC</span>
      <div class="tz-arrow-wrap"></div>
      <div class="db-icon"></div>
    </div>
  </div>
  <div class="egypt-cell">
    <img
        src="images/egipto_noticias.png"
        alt="Egipto canceló el horario de verano tres días antes de su entrada en vigor"/>
  </div>
  <div class="egypt-cell">
    <div class="dt-convert">
      <span>2016-07-09 <span class="fragment highlight-current-fragment" data-fragment-index="1">14:00:00 EET</span></span>
      <div class="tz-arrow-wrap up"><span class="tz-label">Africa/Cairo</span></div>
      <span>2016-07-09 10:00:00 UTC</span>
      <div class="tz-arrow-wrap up"></div>
      <div class="db-icon"></div>
    </div>
  </div>
</div>
<div class="small-spacer"></div>
<p style="font-size: 1.25em; text-align: center; margin-top: 0.75em;">
Cuando guardas objetos datetime y lo que importa es la <em>hora de reloj</em>, hay que guardar el tiempo local, porque el mapeo entre UTC y el tiempo local <em>no es estable</em>.
</p>
</div>

</div>

Notes:

Y podéis pensar: "Bueno, seguro que tenemos que manejar zonas horarias al tratar con *humanos*, pero ¿podemos al menos *guardar* los datetimes en UTC, y evitar todo el tinglado?".

Y siento ser otra vez el pájaro de mal agüero, pero tampoco podéis, porque eso no funciona cuando lo que importa es la hora local.

Si programas una reunión a la una en el futuro y, antes de la cita, el desplazamiento cambia (lo cual pasa todo el rato, y muchas veces sin mucho aviso), seguro que quieres mantener la reunión a la una, pero si has guardado el `datetime` en UTC antes del cambio, ➡️ cuando lo saques después, lo que sale no será correcto. El mapeo entre la hora local y UTC no es estable, así que has perdido la información que te importaba.

Dicho de otro modo: tienes que usar la abstracción que mejor represente tu situación; si lo que importa es la hora local, guarda la hora local.

[1m; T: 11m 15s]

</p>

<span><em>Further Reading:</em> 
<a href="https://codeofmatt.com/on-the-timing-of-time-zone-changes/">On the Timing of Time Zone Changes</a>, <a href="https://codeofmatt.com/time-zone-chaos-inevitable-in-egypt/">Time Zone Chaos Inevitable in Egypt</a></span>

# El modelo de zonas horarias de Python: `tzinfo`

* Las zonas horarias se definen mediante subclases de `tzinfo`.

* La información se proporciona en función del objeto `datetime`:
    * <span class="fragment highlight-current-fragment" data-fragment-index="0">`utcoffset`</span>: El desplazamiento respecto a UTC para ese `datetime`.
    * <span class="fragment highlight-current-fragment" data-fragment-index="1">`tzname`</span>: El nombre (normalmente abreviado) del horario para el `datetime` indicado.
    * <span class="fragment strike highlight-red" data-fragment-index="3"><span class="fragment highlight-current-fragment" data-fragment-index="2">`dst`</span>: La magnitud del desplazamiento del `datetime` que se atribuye al horario de verano (normalmente 0 o 1 hora)</span>

</div>

```pycon
>>> LOS = zoneinfo.ZoneInfo("America/Los_Angeles")
>>> dt_mayo = datetime(2026, 5, 13, 14, tzinfo=LOS)
>>> dt_noviembre = datetime(2026, 11, 14, tzinfo=LOS)

>>> dt_mayo.utcoffset() / timedelta(hours=1)
-7.0

>>> dt_noviembre.utcoffset() / timedelta(hours=1)
-8.0
```
</div>

```pycon
>>> LOS = zoneinfo.ZoneInfo("America/Los_Angeles")          # tzinfo
>>> dt_mayo = datetime(2026, 5, 13, 14, tzinfo=LOS)
>>> dt_noviembre = datetime(2026, 11, 14, tzinfo=LOS)

>>> dt_mayo.tzname()  # En Windows podría dar "Pacific Daylight Time"
'PDT'

>>> dt_noviembre.tzname()
'PST'
```
</div>

```pycon
>>> LOS = zoneinfo.ZoneInfo("America/Los_Angeles")
>>> dt_mayo = datetime(2026, 5, 13, 14, tzinfo=LOS)
>>> dt_noviembre = datetime(2026, 11, 14, tzinfo=LOS)

>>> dt_mayo.dst() / timedelta(hours=1)
1.0

>>> dt_noviembre.dst()
0.0
```

</div>

</div>
<div class="fragment disappearing-fragment nospace-fragment fade-in"
     data-fragment-index="4"
     style="width: 100%; display: flex; justify-content: center"
     >

</div>
</div>
<div class="small-spacer"></div>
</div>

Notes:

Ok, ya que hemos establecido que en realidad hace falta *ugh* entender las abstracciones con las que trabajamos, vamos a bucear más en los detalles de cómo funciona en Python.

El modelo de zonas horarias de Python se centra en una clase base abstracta que se llama `tzinfo`. La idea es que cada objeto que representa una zona horaria proporciona tres funciones que toman como argumento un `datetime`.

➡️La más importante y la que de verdad tira del carro es `utcoffset`, que da el desplazamiento que aplica a la fecha y hora indicada.

➡️A continuación hay `tzname`, que da el nombre que aplica a ese desplazamiento — normalmente estos serían nuestras nefastas abreviaturas de tres letras.

➡️Y finalmente tenemos a la oveja negra de la familia, `dst`, que da la diferencia entre el desplazamiento actual y el horario estándar. ➡️La verdad es que creo que casi cada vez que he visto a alguien usar este método ha sido un error de algún tipo. No lo uséis, amigos.

Aunque hace poco, por primera vez en mi vida entera, he dado con un uso legítimo para este método... ➡️ haciendo este mapa de "horas estándares" para esta misma charla. Como si mis recomendaciones no fueran ya lo suficientemente complejas...

[1m 30s; T: 12m 45s]

# Historia de las zonas horarias en Python

Cuando `datetime` se estrenó en [Python 2.3](https://docs.python.org/3/whatsnew/2.3.html#date-time-type), no había zonas horarias concretas en la biblioteca estándar.
</div>

```python
from dateutil import relativedelta as rd  # Trampita...

class ET(tzinfo):
    def utcoffset(self, dt):
        if self.isdaylight(dt):
            return timedelta(hours=-4)
        else:
            return timedelta(hours=-5)

def dst(self, dt):
        if self.isdaylight(dt):
            return timedelta(hours=1)
        else:
            return timedelta(hours=0)

def tzname(self, dt):
        return "EDT" if self.isdaylight(dt) else "EST"

def isdaylight(self, dt):
        dst_start = datetime(dt.year, 1, 1) + rd.relativedelta(month=3, weekday=rd.SU(+2),
                                                               hour=2)
        dst_end = datetime(dt.year, 1, 1) + rd.relativedelta(month=11, weekday=rd.SU,
                                                             hour=2)

return dst_start <= dt.replace(tzinfo=None) < dst_end
```
</div>

</div>

Notes:

Bueno, e históricamente, eso fue todo lo que tenías en Python. En Python dos punto tres, dijeron: "Aquí tienes una interfaz, pero no queremos encargarnos de implementar las reglas por ti". Se suponía que debías averiguar por tu cuenta, según tu lógica de negocio, cuál sería el mejor método para representar tus zonas horarias, y quizá se esperaba que hicieras algo así: una clase con las reglas que representen la hora del Este.

[30s; T: 13m 15s]

# Historia de las zonas horarias en Python: Zonas concretas

- UTC / Desplazamientos fijos <span class="fragment" style="color: green" data-fragment-index="1">✔ Añadidos en 3.2</span>
- Hora local
- Zonas horarias de IANA

</div>

</div>

Notes:

Pero si lo pensáis un poco, la verdad es que solo hay tres tipos de zona horaria que la inmensa mayoría de la gente quiere.

Uno es el UTC o desplazamientos fijos respecto a este; otro es la hora local, o sea, la hora de tu sistema; y el tercero es una zona de la base de datos de IANA, por ejemplo America/Chicago o America/New_York.

➡️ Y el primero es muy fácil, porque solo necesitas un `timedelta` fijo, así que eso lo añadieron pronto, en tres punto dos. Pero los otros dos resultan ser un poco más complejos.

[45s; T: 14m 00s]

# Historia de las zonas horarias en Python: Horas ambiguas

```python
EASTERN = ET()

print(datetime(2017, 11, 4, 12, 0, tzinfo=EASTERN))
print(datetime(2017, 11, 5, 12, 0, tzinfo=EASTERN))
```

```
2017-11-04 12:00:00-04:00
2017-11-05 12:00:00-05:00
```

```python
dt_before_utc = datetime(2017, 11, 5, 0, 30, tzinfo=EASTERN).astimezone(datetime.UTC)
dt_during = (dt_before_utc + timedelta(hours=1)).astimezone(EASTERN)  # 1:30 EDT
dt_after = (dt_before_utc + timedelta(hours=2)).astimezone(EASTERN)   # 1:30 EST

print(dt_during)   # ¡Pinta bien!
print(dt_after)    # ¡Ay no!
```

```
2017-11-05 01:30:00-04:00
2017-11-05 02:30:00-05:00
```

# Horas ambiguas

Las horas ambiguas son aquellas en las que la misma "hora de reloj" se repite, como durante una transición de horario de verano (DST) a estándar (STD).

</div>

```python
from dateutil import tz

dt1 = datetime(2004, 10, 31, 4, 30, tzinfo=timezone.utc)
for i in range(4):
    dt = (dt1 + timedelta(hours=i)).astimezone(NYC)
    print('{} | {} |  {}'.format(dt, dt.tzname(), 
                                   "Ambigua" if tz.datetime_ambiguous(dt)
                                   else "No ambigua"))
```

<pre>
<tt>
2004-10-31 00:30:00-04:00 | EDT |  No ambigua
<span class="fragment highlight-current-fragment" data-fragment-index="1">2004-10-31 01:30:00-04:00 | EDT |  Ambigua</span>
<span class="fragment highlight-current-fragment" data-fragment-index="1">2004-10-31 01:30:00-05:00 | EST |  Ambigua</span>
2004-10-31 02:30:00-05:00 | EST |  No ambigua
</tt>
</pre>

</div>

¡Pueden existir datetimes en una zona que se diferencian solo por su desplazamiento!

</div>

Notes:

Y para explicaros por qué, tengo que irme un poco por las ramas para hablar sobre las horas ambiguas.

Las horas ambiguas son momentos en los que la misma hora se marca dos veces; por ejemplo, cuando toca atrasar el reloj. Si se retrasa la hora a las dos, cada minuto entre la una y las dos pasa dos veces.

➡️ Fijaos en que en esta lista que tengo aquí la "una y media" aparece dos veces, y la diferencia principal es el desplazamiento. Pero si os acordáis, el modelo de `datetime` es que el desplazamiento es la *salida* del método `utcoffset`, no puede formar parte de la entrada, así que en realidad es imposible distinguir entre estas dos situaciones.

Y esto es un problema fundamental, un defecto que tenía la interfaz de `tzinfo` en aquella época.

[1m; T: 15m 00s]

# Horas imaginarias

El complemento de las horas ambiguas son las horas imaginarias: horas de reloj que no existen en una zona determinada, como sucede durante una transición de horario estándar (STD) a verano (DST).

</div>

```python
dt1 = datetime(2004, 4, 4, 6, 30, tzinfo=timezone.utc)
for i in range(3):
    dt = (dt1 + timedelta(hours=i)).astimezone(NYC)
    print(f'{dt} | {dt.tzname()} ')
```

</div>

¡Fijaos en que falta la hora `2004-04-04 02:30:00`!

</div>

Notes:

Y además hay otro problema, el complemento de las horas ambiguas, que llamamos horas imaginarias. Estas son básicamente horas que no existen en una zona horaria; por ejemplo, cuando toca adelantar el reloj: cualquier hora en ese hueco no corresponderá a un momento real.

Lidiar con esto es más fácil porque estos tiempos simplemente no existen, pero aun así, es importante definir qué debe hacer `tzinfo` en estos casos.

[30s; T: 15m 30s]

# El modelo de zonas horarias de `pytz`

El objecto `timezone` es una fabrica que adjunta el `tzinfo`:

```pycon
>>> LOS_p = pytz.timezone('America/Los_Angeles')
>>> dt = LOS_p.localize(datetime(2017, 8, 11, 14, 0))
>>> print_tzinfo(dt)

2017-08-11 14:00:00-0700
    tzname:   PDT;      UTC Offset:  -7.00h;        DST:      1.0h
```

</div>
<div class="bullets-with-header">

Los `tzinfos` son todos *desplazamientos fijos*:
<div class="small-spacer"></div>

```pycon
>>> print(repr(LOS_p))
<DstTzInfo 'America/Los_Angeles' LMT-1 day, 16:07:00 STD>

>>> print(repr(dt.tzinfo))
<DstTzInfo 'America/Los_Angeles' EDT-1 day, 20:00:00 DST>
```

</div>

Puedes escoger el lado de una transición cuando llamas a `localize`:

```pycon
>>> ambiguo = datetime(2004, 10, 31, 1, 30)
>>> print_tzinfo(LOS_p.localize(ambiguo, is_dst=False))
2004-10-31 01:30:00-0800
tzname:   PST;      UTC Offset:  -8.00h;        DST:      0.0h
```

</div>

El modelo de Python está diseñado ser *lazy* (perezoso), pero lo de `pytz` es *eager* (ansioso).

</div>

Notes:

Bueno, quizás te estés diciendo: "¿No es cierto que `pytz` existió durante diez años y todo el mundo lo usó con mucho éxito?". ¿Cómo resolvió `pytz` este problema? ¿Podemos hacerlo de la misma manera?

Y eres muy listo, querido oyente hipotético, porque sí, `pytz` sí que lo había resuelto, pero la verdad es que el modelo de zonas horarias que tiene `pytz` es fundamentalmente diferente de lo de `datetime`.

El problema es que no hay suficiente información guardada en el objeto `datetime` para disambiguar entre dos `datetime`s diferenciados por su desplazamiento, así que cuando creas el `datetime`, `pytz` crea un `tzinfo` **fijo** de manera *eager*, y guarda la información ahí dentro.

➡️ Y para escoger qué lado de un cambio quieres, puedes usar el parámetro `is_dst` para especificar el lado de hora de verano o el de hora estándar.

[1m 15s; T: 16m 45s]

<style>

div.is-dst-grid {
    display: grid;
    grid-template-columns: 1fr 2fr;
    column-gap: 1em;
    align-items: center;
}

div.grid-left {
    font-size: 0.9em;
}

</style>

# Manejando horas ambiguas e imaginarias con `pytz`

Ya que se evalúan los desplazamientos de manera ansiosa, es posible representar `datetime`s que solo se diferencian por su desplazamiento por ajuntandoles desplazamientos diferentes a ellos.

El argumento `is_dst` de los métodos fabrica tiene tres modos:

<div class="grid-left">
<span class="value"><code><span class="param_name">is_dst</span>=<span class="value">False</span></code></span><br/>
elige el lado STD si ambiguo<br/>
<em>(por defecto)</em>
</div>

<div>

```python
>>> ambiguo = datetime(2004, 10, 31, 1, 30)
>>> print_tzinfo(LOS_p.localize(ambiguo, is_dst=False))
2004-10-31 01:30:00-0500
tzname:   EST;      UTC Offset:  -5.00h;        DST:      0.0h
```

</div>

`is_dst=True`<br/>
elige el lado DST si ambiguo
</div>

<div>

```python
>>> print_tzinfo(LOS_p.localize(ambiguo, is_dst=True))
2004-10-31 01:30:00-0400
tzname:   EDT;      UTC Offset:  -4.00h;        DST:      1.0h
```

</div>

<div class="grid-left">
<code>is_dst=None</code><br/>
Eleva un error si ambiguo o imaginario
</div>

<div>

```python
>>> LOS_p.localize(ambiguo, is_dst=None)
AmbiguousTimeError: 2004-10-31 01:30:00
```

</div>

</div>

Notes:

Y esto resuelve el problema porque permite que `pytz` acepte un argumento para seleccionar una estrategia para resolver horas ambiguas e imaginarias. Puedes usar `is_dst` para indicar qué lado del cambio quieres, o si debería lanzar un error en casos ambiguos o imaginarios.

[30s; T: 15m 15s]

# Problemas con el modelo de `pytz`

* Requiere calculación ansiosa — ajuntar una zona `pytz` directamente da resultos equivocados:

```
  >>> dt = datetime(2020, 5, 1, tzinfo=LOS_p)
  >>> print_tzinfo(dt)
  2020-05-01 00:00:00-0753
      tzname:   LMT;      UTC Offset:  -7.88h;        DST:      0.0h
  ```

* Tienes que `normalize()` datetimes después de hacer aritmética con ellos:
 
  ```python
  >>> dt = LOS_p.localize(datetime(2020, 5, 1))
  >>> dt_add = dt + timedelta(days=180)
 
  >>> print_tzinfo(dt_add)
  2018-02-07 14:00:00-0700
      tzname:   PDT;      UTC Offset:  -7.00h;        DST:      1.0h
 
  >>> print_tzinfo(LOS_p.normalize(dt_add))
  2018-02-07 13:00:00-0800
      tzname:   PST;      UTC Offset:  -8.00h;        DST:      0.0h
  ```

</div>
</div>

Notes:

Pero no elegimos este modelo en la biblioteca estándar, porque tiene problemas.

Primero, tienes que llamar a `localize`. Si pasas un objeto de `pytz` directamente al constructor de `datetime`, va a darte algo extraño como esta chorrada con un desplazamiento de minutos no enteros.

Y poca gente se da cuenta de eso y acaban teniendo errores en su código.

Igualmente, si haces aritmética con ellos, el comportamiento de Python es hacer los cálculos a la parte naíf y después añadir el `tzinfo` original, pero los `tzinfo`s de `pytz` son zonas fijas, así que si llegas más allá de un cambio de reloj, tienes que llamar al método `normalize()` para recalcular cuál desplazamiento aplica.

Y una vez más, poca gente sabe que tienes que hacer esto y eso causa errores.

Así que la ergonomía no es lo suficientemente buena para ser la solución.

[1m 15s; T: 18m 00s]

# PEP 495: Disambiguación de horas locales

* Introducido en Python 3.6 para resolver el problema de las horas ambiguas.
* Introduce el atributo `fold` en `datetime`.
* Cambios en la comparación de `datetimes` conscientes en horas ambiguas.

Estar en un lado u otro de la transición es una **propiedad del `datetime`**:

```python
>>> print_tzinfo(datetime(2004, 10, 31, 1, 30, tzinfo=NYC))          # fold=0
2004-10-31 01:30:00-0400
    tzname:   EDT;      UTC Offset:  -4.00h;        DST:      1.0h

>>> print_tzinfo(datetime(2004, 10, 31, 1, 30, fold=1, tzinfo=NYC))
2004-10-31 01:30:00-0500
    tzname:   EST;      UTC Offset:  -5.00h;        DST:      0.0h
```

</div>
<img
    src="images/fold_495.svg"
    style="height: 31dvh; margin: 0;"
    class="fragment nospace-fragment fade-in" data-fragment-index="0"
    alt="Diagrama del modelo de resolución de horas ambiguas del PEP 495, mostrando que fold desplaza el momento en que se aplica la etiqueta 'DST'."
/>

</div>
</div>

**N.B.:** `fold=1` representa la *segunda* instancia de un `datetime` ambiguo.

</div>

Notes:

La solución con la que han dado en Python 3.6 era simplemente añadir un solo byte de información a la parte naíf del datetime, y ese es el atributo fold.

La idea es que tienes este atributo que puedes usar para especificar cómo resolver de qué lado de una transición quieres estar, como en pytz, pero con la diferencia de que aquí la información no está guardada en el `tzinfo`, sino en el propio `datetime`, así que se puede usar de manera *lazy*.

➡️ Y como funciona es que `fold=0` es la *primera* instancia de una hora ambigua, y `fold=1` es la *segunda*.

[45s; T: 18m 45s]

<div>

## <tt>pytz</tt>

</div>

<div>

## PEP 495

</div>

Notes:

Y eso es un poco diferente a la manera en que `pytz` lo hace, porque a `pytz` no le importa cuál viene primero.

Lo que `is_dst` quiere decir es que si hay una hora ambigua, puedes escoger si quieres el lado de verano o el lado estándar, pero lo que `fold` quiere decir es: "Vale, si hay una hora ambigua, ¿mantenemos el desplazamiento que se aplicaba antes de la transición o después?".

Y resulta que esta forma es un poco más simple de implementar, y también está mejor definida, porque, como ya hemos aprendido, a veces estas transiciones ocurren por motivos distintos a un cambio de hora de verano, así que puedes tener hora estándar o hora de verano en *ambos lados*. Con `fold` ya no es ambiguo porque solo tienes que saber qué desplazamiento ocurrió antes y cuál después.

[1m; T: 19m 45s]

# Zonas horarias concretas: hora local

- UTC / Desplazamientos fijos <span class="fragment" style="color: green" data-fragment-index="2">✔ Añadidos en 3.2</span>
- Hora local
- Zonas horarias de IANA <span class="fragment" style="color: red" data-fragment-index="2">✘ (en Python 3.8)</span>

A partir de Python 3.2, los `datetime`s naífs ya se consideran hora local del sistema, y puedes adjuntarles un desplazamiento fijo para conseguir información sobre la zona horaria:

```pycon
>>> print(datetime(2023, 11, 4, 12).astimezone())
2023-11-04 12:00:00-04:00
```

```pycon
>>> print(datetime(2023, 11, 5, 12).astimezone())
2023-11-05 12:00:00-05:00
```

Configurar el atributo `fold` en un `datetime` naíf funciona:

```pycon
>>> print(datetime(2023, 11, 5, 1, fold=0).astimezone())
2023-11-05 01:00:00-04:00
>>> print(datetime(2023, 11, 5, 1, fold=1).astimezone())
2023-11-05 01:00:00-05:00
```

</div>

Para más información, mirad mis posts de blog (en inglés): [Why naïve times are local times](https://blog.ganssle.io/articles/2022/04/naive-local-datetimes.html) y [Stop using utcnow and utcfromtimestamp](https://blog.ganssle.io/articles/2019/11/utcnow.html)
</p>

</div>

Notes:

Vale, entonces esto te permite implementar las otras dos formas de zona horaria que comenté antes: hora local y zonas de IANA. Y resulta que muy poca gente lo sabe, pero llevamos ya bastante tiempo con soporte para horas locales en `datetime`, básicamente desde la versión tres punto seis (3.6).

Pero se hizo un poco a escondidas — los `datetime`s naíf, que antes eran horas flotantes sin zona horaria, ahora representan la hora local siempre que Python necesite convertirlos a UTC. Así que puedes llamar a `timestamp` o `astimezone` y ya está.

Y si queréis más información sobre por qué lo hicieron y por que era lo correcto, echad un vistazo a mi blog.

➡️ Y algo aquí que quiero destacar es que si quieres saber el desplazamiento o el nombre local, tienen una interfaz tipo `pytz`: si llamas a `.astimezone` sin argumentos, te dará  un `datetime` consciente con el `tzinfo` fijo que aplica a tu sistema.

Pero no debes hacer aritmética con eso — haz los cálculos primero y luego llama a `astimezone`.

Así que esto nos da dos de nuestros tres tipos de zonas horarias, pero en Python tres punto ocho (3.8), ➡️ todavía no teníamos zonas de IANA, y el motivo eran los datos.

[1m 30s; T: 21m 15s]

# Fuente de datos: Zonas horarias de IANA

- Proporciona información sobre zonas horarias históricas.
- Fuente estándar y abierta (dominio público) para información de zonas horarias.
- Muchos sistemas operativos la incluyen.
- Fuente de datos para `dateutil` y `pytz`.
- 2-21 versiones al año (9 de promedio).

</div>

Notes:

Así que ya he mencionado las zonas horarias de IANA algunas veces, y esto se refiere a la fuente de los datos. Es básicamente la base de datos canónica sobre zonas horarias que todo el mundo usa; bastantes sistemas operativos la incluyen, pero no todos.

Y la idea era incluirla con Python como fuente de las reglas, pero el problema es que sacan versiones nuevas demasiado frecuentemente, con mucha más frecuencia que la cadencia anual de Python, y a menudo es importante que la gente reciba los datos actualizados cuanto antes.

[45s; T: 22m 00s]

# PEP 615: Soporte para la base de datos de zonas horarias de IANA en la biblioteca estándar

- Se usa cuando el sistema tiene disponible la base de datos.
- Por defecto, Python busca en ubicaciones de despliegue "bien conocidas".
- Se puede configurar en el programa con `zoneinfo.reset_tzpath`.
- Se puede configurar con la variable de entorno `PYTHONTZPATH`.
- El valor por defecto se puede configurar en tu compilador.

- También proporcionamos el paquete `tzdata` en PyPI: un paquete "first party" de solo datos como fallback.

</div>

Notes:

Decidimos resolver este dilema convirtiéndolo en una situación de "traer sus propios datos". En vez de incluir una base de datos directamente en Python, `zoneinfo` la busca en ubicaciones bien conocidas, y puedes configurar la ruta de búsqueda de varias formas. También proporcionamos un paquete de PyPI que puedes usar como fallback para plataformas que no traen los datos de forma accesible, como Windows.

[30s; T: 22m 30s]

# Cómo usar `zoneinfo`

## Backport (3.6+)

```python
try:
    from backports import zoneinfo
except ImportError:
    import zoneinfo
```

</div>

</div>

## Construir datetimes conscientes (aware)

```pycon
>>> dt = datetime(2020, 11, 12, 19, tzinfo=ZoneInfo("America/Chicago"))
>>> print(dt)
2020-11-12 19:00:00-06:00

>>> print(datetime.now(ZoneInfo("America/Chicago")))
2020-11-12 19:46:21.211438-06:00
```

</div>

## Convertir entre zonas

```pycon
>>> print(dt.astimezone(ZoneInfo("Europe/Paris")))
2020-11-13 02:00:00+01:00
```

</div>
<div class="small-spacer"></div>
</div>

Notes:

Hoy en día si usas cualquier versión con soporte de Python, ➡️ e incluso muchas versiones sin soporte, puedes usar el módulo `zoneinfo` para tus zonas IANA.

Y no tengo que explicaros cómo usarlo porque lo haces como os imaginaréis. Pasas un objeto `ZoneInfo` al constructor o `.replace` o `.now` o `.astimezone` y funciona bien.

Aunque algo que quiero destacar aquí es que en este mundo post-`pytz`, es mucho más probable que te enfrentes a las semánticas poco intuitivas inherentes al modelo de `datetimes` que tiene Python.

[45s; T: 23m 15s]

# Un caso curioso...

```python
>>> LON = ZoneInfo("Europe/London")

>>> x = datetime(2007, 3, 25, 1, 0, tzinfo=LON)
```

```python
>>> y = datetime.fromtimestamp(x.timestamp(), LON)
>>> x == y
False
```

```python
>>> z = datetime.fromtimestamp(x.timestamp(), ZoneInfo.no_cache("Europe/London"))
>>> x == z
True
```

```python
>>> y == z          # 🤯
True
```

</div>
</div>
<div class="small-spacer"></div>
</div>

Notes:

Para ilustrar eso, os cuento un «bug report» que llegó a `dateutil` hace años y años y fue muy divertido de debuggear. Alguien dijo: "Esta fecha, el veinticinco de marzo a la una de la madrugada en Londres — si la paso a timestamp y de vuelta — los `datetime`s no evalúan como iguales". Un poco chungo, ¿no?

➡️ Y más raro aún: si creo una nueva instancia del objeto de la zona horaria de Londres para hacer mi `datetime`, *sí* que evalúan como iguales. ➡️ E incluso más raro: ¡esas dos también son iguales entre sí! Así que la relación no es transitiva, ¿cierto?

[45s; T: 24m 00s]

# Pista

¡`2007-03-25 01:00:00` en Londres es imaginario!

</div>

```pycon
>>> print(x)                                # x (LON)

2007-03-25 01:00:00+01:00

>>> print(x.astimezone(UTC))                # x (LON ➜ UTC)

2007-03-25 00:00:00+00:00

>>> print(x.astimezone(UTC).
...        .astimezone(LON))                # x (LON ➜ UTC ➜ LON)

2007-03-25 00:00:00+00:00
```

Notes:

Mi primera pista fue darme cuenta de que esta hora no existía — era imaginaria.

Así que Y y Z no podían representar el `datetime` original; no puedes llegar a una hora imaginaria desde UTC.

Y lo que pasa aquí es que X va a UTC — que sí existe — y de ahí al equivalente existente en Londres.

[30s; T: 24m 30s]

# ¿Qué significa la igualdad?

<div style="flex-grow: 2">
<ol>
    <li>Semántica de hora de reloj: solo comparar la parte naíf<br/>
    <table style="margin-top: 0.5em">
        <tr>
            <td><tt>x == y</tt></td>
            <td><tt>False</tt></td>
        </tr>
        <tr>
            <td><tt>x == z</tt></td>
            <td><tt>False</tt></td>
        </tr>
        <tr>
            <td><tt>y == z</tt></td>
            <td><tt>True</tt></td>
        </tr>
    </table>
    <br/>
    </li>
    <li>Semántica de tiempo absoluto: convertir a UTC<br/>
    <table style="margin-top: 0.5em">
        <tr>
            <td><tt>x == y</tt></td>
            <td><tt>True</tt></td>
        </tr>
        <tr>
            <td><tt>x == z</tt></td>
            <td><tt>True</tt></td>
        </tr>
        <tr>
            <td><tt>y == z</tt></td>
            <td><tt>True</tt></td>
        </tr>
    </table>
    </li>
</ol>
</div>

div {
        display: flex;
        flex-direction: column;
        align-items: center;
        margin-top: 0.5em;
        margin-bottom: 0.5em;

tt {
            /* Container query units */
            font-size: 1.8cqi;
            white-space: nowrap;
            margin-left: 0.5em;
            margin-right: 0.5em;
        }

}

}
</style>
<div id="hours-compare">
<div class="fragment disappearing-fragment nospace-fragment fade-out"
     data-fragment-index="1">
<u>Horas de reloj:</u><br/>
<tt>
    x: <b>2007-03-25 01:00:00</b>+01:00<br/><br/>
    y: <b>2007-03-25 00:00:00</b>+00:00<br/><br/>
    z: <b>2007-03-25 00:00:00</b>+00:00<br/><br/>
</tt>
</div>
<div class = "fragment nospace-fragment fade-in " data-fragment-index="1">
<u>UTC:</u><br/>
<tt>
    x: 2007-03-25 <b>00:00:00+00:00</b><br/><br/>
    y: 2007-03-25 <b>00:00:00+00:00</b><br/><br/>
    z: 2007-03-25 <b>00:00:00+00:00</b><br/><br/>
</tt>
</div>
</div>
</div>

## Otra pista

```python
>>> x.tzinfo is y.tzinfo
True
```

```python
>>> x.tzinfo is z.tzinfo
False
```

</div>
</div>

Notes:

Eso nos lleva al tema de la igualdad: ¿qué significa que dos `datetime`s sean iguales? Porque de hecho hay dos candidatos buenos.

Uno es la semántica de hora de reloj: solo comparas la parte naif, ignorando el desplazamiento. En esa situación, X no debería ser igual a Y o Z, e Y y Z deberían ser iguales entre sí.

➡️ La otra es la semántica de tiempo absoluto: pasas todo a UTC antes de compararlos, y en este caso, los tres son iguales.

Pero no vemos ninguno de esos patrones, ¿cierto? ¿Qué pasa?

➡️ La última pista que nos falta es que X e Y usan el mismo objeto `tzinfo`, pero Z tiene uno diferente, aunque sea igual a los otros.

[45s; T: 25m 15s]

# Semántica de comparación de datetimes conscientes

1. Cuando dos `datetime`s están en la *misma zona*, solo se compara la parte naíf (semántica de hora de reloj).

2. Cuando están en *zonas diferentes*, ambos se convierten a UTC primero y después se comparan (semántica absoluta).

3. Dos `datetime`s solo se consideran en la "misma zona" si `dt1.tzinfo is dt2.tzinfo`.

## Misterio resuelto:

<div class="fragment" data-fragment-index="1" style="text-align:center">
<table>
<tr>
    <td></td>
    <td>Pared</td>
    <td>Absoluto</td>
    <td><tt>datetime</tt></td>
</tr>
<tr>
    <td><tt>x == y</tt></td>
    <td><b>False</b></td>
    <td>True</td>
    <td>False</td>
</tr>
<tr>
    <td><tt>x == z</tt></td>
    <td>False</td>
    <td><b>True</b></td>
    <td>True</td>
</tr>
<tr>
    <td><tt>y == z</tt></td>
    <td><b>True</b></td>
    <td>True</td>
    <td>True</td>
</tr>
</table>

</div>

</div>
</div>

Notes:

Y resulta que la semántica que se usa de verdad es que cuando dos `datetime`s están en la misma zona, se usa la hora de reloj, pero cuando están en zonas diferentes, no tiene sentido comparar las partes naif, ¿cierto? Así que primero hay que ponerlos en la misma zona: UTC.

Y la clave final de nuestro misterio es que solo se considera que dos `datetime`s están en la misma zona si tienen el mismo objeto `tzinfo` — el mismísimo objeto, no basta con que tengan el mismo valor.

➡️ Entonces el misterio está resuelto, ¿lo veis? Porque para `x == y` se aplica la hora de reloj, para `x == z` tenemos tiempo absoluto, y para `y == z`, otra vez tenemos la hora de reloj, aunque para la última las dos dan el mismo resultado.

[1m; T: 26m 15s]

# `zoneinfo`: Comportamiento de la caché

Las llamadas al constructor por defecto con argumentos idénticos tienen garantizado devolver objetos idénticos; específicamente, lo siguiente siempre debe ser válido:

```python
   a = ZoneInfo(key)
   b = ZoneInfo(key)
   assert a is b
   ```

Esto es porque `datetime` asume que las zonas horarias son singletons, lo que daría resultados confusos si usáramos una implementación más simple:

```python
   >>> from datetime import *
   >>> from simple_zoneinfo import SimpleZoneInfo
   >>> dt0 = datetime(2020, 3, 8, tzinfo=SimpleZoneInfo("America/New_York"))
   >>> dt1 = dt0 + timedelta(1)
   >>> dt2 = dt1.replace(tzinfo=SimpleZoneInfo("America/New_York"))
   >>> dt2 == dt1
   True
   >>> print(dt2 - dt1)
   0:00:00
   >>> print(dt2 - dt0)
   23:00:00
   >>> print(dt1 - dt0)
   1 day, 0:00:00
   ```

Consultad el [PEP 615](https://www.python.org/dev/peps/pep-0615/) y [la documentación](https://docs.python.org/3/library/zoneinfo.html) para más información de la que jamás querríais saber sobre cómo trabajar con esta caché.

</div>

Notes:

Dicho sea de paso, este problema influyó bastante en cómo se diseñó `ZoneInfo`, porque no queríamos esta situación tan confusa en la que a veces se aplica la semántica de la hora de reloj y otras la de tiempo absoluto.

Así que `ZoneInfo` garantiza que siempre vas a recibir el mismo objeto si usas la misma clave.

[30s; T: 26m 45s]

# Semántica de aritmética con datetimes conscientes

Un problema análogo a la semántica de comparación es que sumar tiempo tras una transición de DST no está bien definida:

```python
>>> NYC = ZoneInfo("America/New_York")
>>> dt1 = datetime(2020, 3, 7, 13, tzinfo=NYC)
>>> dt2 = d1 + timedelta(days=1)
```
</div>

Dado que hay una transición entre `dt1` y `dt2`, hay dos opciones:

```python
>>> # Siguiente día del calendario a la misma hora
>>> print(sumar_reloj(dt1, timedelta(days=1)))
2020-03-08 13:00-04:00

>>> # 24 horas transcurridas después de dt1
>>> print(sumar_absoluto(dt1, timedelta(days=1)))
2020-03-08 12:00-04:00
```

</div>
<div class="small-spacer"></div>
</div>

Notes:

Y además de la comparación, hay un problema análogo con la aritmética. Imagínate que quieres sumar veinticuatro horas a un `datetime` justo antes de un cambio de hora.

Puedes optar por usar la hora de reloj, en la que dices en plan: "Solo dame la misma hora, pero de mañana", lo que serían veintitrés horas de tiempo real.

O puedes decir: "Dame la hora que será cuando hayan pasado veinticuatro horas" — una hora antes.

[30s; T: 27m 15s]

# Semántica de aritmética con datetimes conscientes en Python

`datetime` siempre usa semántica de hora de reloj cuando interactúa con un `timedelta`:

```python
>>> print(sumar_reloj(dt1, timedelta(days=1)))
2020-03-08 13:00-04:00

>>> print(sumar_absoluto(dt1, timedelta(days=1)))
2020-03-08 12:00-04:00

>>> print(dt1 + timedelta(days=1))
2020-03-08 13:00-04:00
```

Cuando se restan dos `datetime`s, el comportamiento es diferente entre los casos de «misma zona» y «zona diferente»:

```
>>> dt2 = datetime(2020, 3, 8, 13, tzinfo=NYC)
>>> dt1_misma = datetime(2020, 3, 7, 13, tzinfo=NYC)
>>> dt1_diferente = dt1_misma.astimezone(timezone.utc)  # dt1_misma == dt1_diferente!

>>> print(dt2 - dt1_misma)
1 day, 0:00:00

>>> print(dt2 - dt1_misma)
23:00:00
```

Consultad mi artículo de blog (en inglés) ["Semantics of timezone-aware datetime arithmetic"](https://blog.ganssle.io/articles/2018/02/aware-datetime-arithmetic.html) para un análisis más exhaustivo.
</div>

</div>

Notes:

Y la dicotomía es la misma que con la comparación, ya que a `datetime` le encanta la hora de reloj. Así que si sumas o restas un `timedelta`, Python dice: "es la misma zona — hora de reloj". Y si restas dos `datetime`s en la misma zona, también, hora de reloj.

Pero si están en zonas diferentes, de nuevo la hora de reloj no tiene sentido, así que te da tiempo absoluto. Y tengo un post que explica por qué esto no es tan descabellado como parece; pero aunque sea razonable, la gente no para de enviar «bug reports» diciendo que los cálculos están mal.

[30s; T: 27m 45s]

# Cómo usar `zoneinfo`: Semántica del tiempo absoluto

La semántica de hora de reloj de Python puede sorprender a muchos usuarios; para utilizar deliberadamente la semántica del tiempo absoluto, primero hay que convertir a UTC:

```python
def sumar_absoluto(dt: datetime, td: timedelta) -> datetime:
    dt_utc = dt.astimezone(timezone.utc)
    rv_utc = dt_utc + td
    return rv_utc.astimezone(dt.tzinfo)

def restar_absoluto(dt1: datetime, dt2: datetime) -> timedelta:
    dt1_utc = dt1.astimezone(timezone.utc)
    dt2_utc = dt2.astimezone(timezone.utc)

return dt1 - dt2
```

</div>
</div>

Notes:

Por desgracia, a estas alturas ya no es algo que podamos cambiar, así que lo que os recomiendo es que definas algunas funciones auxiliares como las que tengo aquí, que tomen tus operandos y los conviertan a UTC antes de hacer las operaciones, para que así no importe si están en la misma zona o no.

[30s; T: 28m 15s]

# Resumen

<div style="text-align: center; font-size: 1.2em; font-style: italic">No hay atajos: ¡tienes que entender tus abstracciones!</div>

<div>

- ¿Qué quieres representar?
  - Tiempo absoluto (UTC, *timestamps*)
  - Hora de reloj (zona IANA, hora local)

- ¿Cuál zona aplica?

</div>

<div>

- ¿Cuál semántica aplica a tu cálculo?
  - Tiempo absoluto: ¿cuánto tiempo ha pasado o pasará?
  - Tiempo de reloj: ¿cuántas horas *nominales* han pasado o pasarán?

</div>

<!--

### Bonus

Nunca tienes que usar `total_seconds()`:

```python
>>> timedelta(days=3, minutes=4).total_seconds() / 60   # ❌
>>> timedelta(days=3, minutes=4) / timedelta(minutes=1) # ✅
4324.0

>>> timedelta(days=3, minutes=4) / timedelta(minutes=4)
1081.0

>>> timedelta(weeks=1) / timedelta(hours=1)
168.0
```

</div>
-->

</div>

Notes:

Sé que normalmente la gente prefiere cuando rematas con un resumen con unos «top tips» simples que sinteticen la charla, pero pensándolo bien, me he dado cuenta de que, en realidad, el tema de esta charla es que aquí no hay atajos: no hay reglas simples como "usa siempre UTC", porque todo depende mucho del contexto.
Así que en vez de reglas simples, os presento unas preguntas que os podéis hacer. Podéis preguntaros, "¿Qué quiero representar?". Si es un evento en el pasado como un log, o algo en el futuro que no depende del reloj humano como la llegada de un asteroide o algo así, probablemente puedes usar UTC o timestamps. En otros casos, tienes que usar la hora local de alguna zona.

Y para cálculos, otra vez preguntaos cuál semántica será mejor: ¿te importa la cantidad del tiempo, o te importan los cálculos en un calendario? Si quieres "la misma hora en siete días", usas tiempo del reloj. Si quieres saber "cuántos segundos han pasado entre estos `datetime`s", usas tiempo absoluto.

<!--
Y finalmente, tengo un bonus, que no tiene que ver mucho con zonas horarias pero es un «tip» que no se descubre fácilmente y es muy útil. Si quieres saber cuántas veces cabe una unidad en un periodo de tiempo, en vez de usar `total_seconds` e intentar dividir por el número de segundos de la unidad, puedes dividir directamente por un `timedelta` que represente la unidad. Es por eso que no hay un `total_minutes` ni `total_hours` u otros métodos en `timedelta`: incluso `total_seconds` fue un error, porque el Core Dev que lo añadió no sabía este tip.

-->

# ¡Gracias!

<div>
<img
    src="external-images/with_time.png"
    class="splash"
    style="max-width: 40dvw"
    alt="Un híbrido entre un globo terráqueo y un reloj"
/>
</div>
<div class="left-container"
style="font-size: 1.25em; display: flex; flex-direction: column; justify-content: center; margin-left: 2em; ">
    <p><b>Página web:</b> <a href="https://ganssle.io">https://ganssle.io</a></p>
    <p><b>Blog:</b> <a href="https://blog.ganssle.io">https://blog.ganssle.io</a></p>
    <p><b>Mastodon:</b> <a href="https://qoto.org/@pganssle">@pganssle@qoto.org</a></p>
    <p><b>Github:</b> <a href="https://github.com/pganssle">@pganssle</a></p>
    <p><b>Gitlab:</b> <a href="https://gitlab.com/pganssle">@pganssle</a></p>
</div>
</div>

</div>

Notes:

Okay, y hasta aquí mi charla. Sé que normalmente la gente prefiere rematar una charla así con un resumen o unos «top tips», pero pensándolo bien, creo que el resumen de mi charla debe ser que no hay reglas simples, y hay que entender las abstracciones que se usan. Lo siento.

Creo que no hay tiempo para preguntas, pero aquí tenéis mi información, y estaré en los pasillos después de la charla (y luego deambulando por la conferencia); o sea, si no he muerto de vergüenza pensando en los errores que acabo de cometer 😅

No, es broma; me habéis aguantado bien.

Hace casi tres años, empecé a aprender español, y el año pasado, mejorar lo suficiente para dar una charla ha sido algo entre meta y reto para mí, así que, mi primera charla en español ya cumplida, os agradezco que hayáis venido y participado en este pequeño hito personal. Gracias y nos vemos por la conferencia.

[1m 15s; T: 29m 30s]

# ¿Por qué usar `zoneinfo`?

¡Es muy **rápida**! (cifras de los benchmarks de `backports.zoneinfo`):

```
Ejecutando el constructor en la zona America/New_York
c_zoneinfo: mean: 214.65 ns ± 43.48 ns; min: 190.88 ns (k=5, N=1000000)
pytz: mean: 1.21 µs ± 78.31 ns; min: 1.10 µs (k=5, N=200000)
dateutil: mean: 1.33 µs ± 117.35 ns; min: 1.23 µs (k=5, N=200000)

Ejecutando from_utc en la zona America/New_York
c_zoneinfo: mean: 658.55 ns ± 28.92 ns; min: 617.08 ns (k=5, N=500000)
pytz: mean: 5.12 µs ± 515.26 ns; min: 4.70 µs (k=5, N=50000)
dateutil: mean: 10.64 µs ± 746.99 ns; min: 10.20 µs (k=5, N=20000)

Ejecutando to_utc en la zona America/New_York
c_zoneinfo: mean: 616.13 ns ± 16.14 ns; min: 604.76 ns (k=5, N=500000)
pytz: mean: 848.44 ns ± 28.10 ns; min: 806.72 ns (k=5, N=500000)
dateutil: mean: 8.03 µs ± 509.75 ns; min: 7.55 µs (k=5, N=50000)

Ejecutando utcoffset en la zona America/New_York
c_zoneinfo: mean: 373.89 ns ± 5.76 ns; min: 368.24 ns (k=5, N=1000000)
pytz: mean: 564.55 ns ± 13.65 ns; min: 552.88 ns (k=5, N=500000)
dateutil: mean: 7.95 µs ± 642.62 ns; min: 7.44 µs (k=5, N=50000)
```

Gracias a su implementación en C, `zoneinfo` es más rápida que `pytz` y `dateutil` en todas las métricas de rendimiento.

</div>

Notes:

Vale, pues no quiero dar por sentado que, por el mero hecho de estar en la biblioteca estándar, vayáis a querer liaros con todo este jaleo que acabo de explicar. Y creo que, además de ser la librería más armónica con el diseño de `datetime`, aun hay al menos dos buenos motivos más para usarla.

Uno es que es muy rápida, ya que está escrita en C. Pero no quiero jactarme del rendimiento, así que no vamos a pasar mucho tiempo en esta diapositiva.

[30s; T: 30m 00s]

pre.code-wrapper {
        margin-top: 0;
        margin-bottom: 0;
    }
}
</style>
<div class="bullet-container medium-code code-indented smaller-margins">

# ¿Por qué usar `zoneinfo`?

Es la única librería de zonas horarias con soporte para fechas posteriores a 2038 (el «epochalypse») y para el formato "slim" de `tzdata`.

```python
>>> for i in range(5):
...     dt = datetime(2037, 6, 1) + timedelta(days=183) * i
...
...     print_comparison(
...         pytz.timezone("America/Los_Angeles").localize(dt),
...         dt.replace(tzinfo=ZoneInfo("America/Los_Angeles"))
...     )
...     print()
```

pytz:          2037-06-01     PDT  -07:00
zoneinfo:      2037-06-01     PDT  -07:00

pytz:          2037-12-01     PST  -08:00
zoneinfo:      2037-12-01     PST  -08:00

<span class="fragment custom highlight-current-fragment" data-fragment-index="1">pytz:          2038-06-02     PST  -08:00</span>
<span class="fragment custom highlight-current-fragment" data-fragment-index="1">zoneinfo:      2038-06-02     PDT  -07:00</span>

pytz:          2038-12-02     PST  -08:00
zoneinfo:      2038-12-02     PST  -08:00

<span class="fragment custom highlight-current-fragment" data-fragment-index="1">pytz:          2039-06-03     PST  -08:00</span>
<span class="fragment custom highlight-current-fragment" data-fragment-index="1">zoneinfo:      2039-06-03     PDT  -07:00</span>
</tt>
</pre>

</div>

Notes:

El motivo más importante es que ni `pytz` ni `dateutil` soporta el nuevo formato de los datos de IANA, y el formato antiguo no admite timestamps de más de treinta y dos bits. Así que para fechas posteriores a dos mil treinta y ocho, deja de funcionar; ➡️ las transiciones simplemente se detienen, y el "epochalypse" se acerca cada día más.

<!-- Skip this for now: probably doesn't apply.

Pero algo más urgente es que algunas distros ya usan el formato "slim", que aprovecha una nueva capacidad en el nuevo formato de usar reglas en lugar de listas de transiciones. Como `pytz` tampoco lo soporta, en muchos sitios, como en los Estados Unidos, si usas los datos del sistema, `pytz` ya falla hoy mismo.

-->

[30s; T: 30m 30s]

# Migrar de `pytz`

Si tienes una interfaz pública que devuelve zonas de `pytz` (o `datetime`s con zonas de `pytz` adjuntadas), migrar fuera de `pytz` implicará un **cambio disruptivo (*breaking change*)**:

```python
def pre_migration():
    return pytz.timezone("America/New_York").localize(datetime(2020, 1, 1))

def post_migration():
    return datetime(2020, 1, 1, tzinfo=ZoneInfo("America/New_York"))

def sesenta_dias_despues(dt: datetime) -> datetime:
    non_normalized_dt = dt + timedelta(days=60)
    return dt.tzinfo.normalize(non_normalized_dt)
```

```python
>>> sesenta_dias_despues(pre_migration())
datetime.datetime(2020, 3, 1, 0, 0, tzinfo=<DstTzInfo 'America/New_York' EST-1 day, 19:00:00 STD>)

>>> sesenta_dias_despues(post_migration())
---------------------------------------------------------------------------
AttributeError                            Traceback (most recent call last)
<ipython-input-7-b71365e0022f> in <module>
----> 1 sesenta_dias_despues(post_migration())

<ipython-input-5-f165abf34e2a> in sixty_days_later(dt)
      7 def sesenta_dias_despues(dt: datetime) -> datetime:
      8     non_normalized_dt = dt + timedelta(days=60)
----> 9     return dt.tzinfo.normalize(non_normalized_dt)

AttributeError: 'zoneinfo.ZoneInfo' object has no attribute 'normalize'
```

</div>

Notes:

Si vas a migrar de `pytz`, y tienes alguna interfaz orientada al público que devuelva sus zonas horarias, hay que ser consciente de que cambiar a `ZoneInfo` supondrá un *breaking change* (un cambio disruptivo). Básicamente, porque tus usuarios pueden esperar que los objetos que devuelves tengan los métodos `localize` y `normalize` u otras interfaces exclusivas de `pytz`, lo cual podría daros algún que otro problema.

# `pytz-deprecation-shim`

[`pytz-deprecation-shim`](https://pytz-deprecation-shim.readthedocs.io) es una implementación mayormente compatible de la interfaz de `pytz` que **también** es una capa fina (wrapper) sobre `zoneinfo`. Se puede usar igual que un objeto de `zoneinfo.ZoneInfo`:

```python
>>> import pytz_deprecation_shim as pds
>>> from datetime import datetime, timedelta
>>> LA = pds.timezone("America/Los_Angeles")

>>> dt = datetime(2020, 10, 31, 12, tzinfo=LA)
>>> print(dt)
2020-10-31 12:00:00-07:00

>>> dt.tzname()
'PDT'
```

Pero también expone la interfaz de `pytz`, lanzando un `DeprecationWarning` cuando se usan funcionalidades específicas de `pytz`:

```python
>>> dt = LA.localize(datetime(2020, 10, 31, 12))
<stdin>:1: PytzUsageWarning: The localize method is no longer necessary, as
this time zone supports the fold attribute (PEP 495). For more details on
migrating to a PEP 495-compliant implementation, see
https://pytz-deprecation-shim.readthedocs.io/en/latest/migration.html

>>> print(dt)
2020-10-31 12:00:00-07:00
>>> dt.tzname()
'PDT'
```

⚠️ **Cuidado:** Hay algunos cambios en la semántica de aritmética; consultad la [guía de migración](https://pytz-deprecation-shim.readthedocs.io/en/latest/migration.html). ⚠️

</div>

Notes:

Para ayudar con eso, he creado esta librería de terceros que se llama `pytz-deprecation-shim`. Funciona así: aunque es imposible ser cien por cien compatible con la interfaz de `pytz`, es "mayormente" compatible porque es un  «thin wrapper» sobre `ZoneInfo`. Expone las interfaces de `pytz`, pero lanza un `DeprecationWarning` cuando se usa algo exclusivo de `pytz` para avisar a tus usuarios de que deberían dejar de usar esos métodos.

Mi única advertencia es que hay algunos cambios sutiles en la semántica de la aritmética, así que, en ciertas circunstancias, el comportamiento de las zonas cambiará para tus usuarios sin aviso previo. Para entender mejor qué cambios son, os recomiendo que le echéis un ojo a la guía de migración. E incluso si no tenéis pensado usar la librería, os sugiero leerla igual, porque me dicen que explica muy bien los problemas típicos al migrar desde `pytz`.

De hecho, espero que no tengáis que usar la librería para migrar, pero si tienes una base de código grande, te puede venir bien para detectar dónde se están llamando a los métodos de `pytz` más allá de los usos directos.