zoneinfo — Suporte a fuso horário da IANA

Adicionado na versão 3.9.

Código-fonte: Lib/zoneinfo

O módulo zoneinfo fornece uma implementação concreta de fuso horário para oferecer suporte ao banco de dados de fuso horário da IANA, conforme especificado originalmente na PEP 615. Por padrão, zoneinfo usa os dados de fuso horário do sistema, se disponíveis; se nenhum dado de fuso horário do sistema estiver disponível, a biblioteca voltará a usar o pacote original tzdata disponível no PyPI.

Ver também

Módulo: datetime

Fornece os tipos time e datetime com os quais a classe ZoneInfo foi projetada para ser usada.

Pacote tzdata

Pacote próprio mantido pelos desenvolvedores principais do CPython para fornecer dados de fuso horário via PyPI.

Disponibilidade: not WASI.

Este módulo não funciona ou não está disponível em WebAssembly. Veja Plataformas WebAssembly para mais informações.

Usando ZoneInfo

ZoneInfo é uma implementação concreta da classe base abstrata datetime.tzinfo e deve ser anexada a tzinfo, por meio do construtor, do método datetime.replace ou datetime.astimezone:

>>> from zoneinfo import ZoneInfo
>>> from datetime import datetime, timedelta

>>> dt = datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-10-31 12:00:00-07:00

>>> dt.tzname()
'PDT'

Datas e horas construídas dessa maneira são compatíveis com a aritmética de data e hora e lidam com transições de horário de verão sem intervenção adicional:

>>> dt_add = dt + timedelta(days=1)

>>> print(dt_add)
2020-11-01 12:00:00-08:00

>>> dt_add.tzname()
'PST'

Esses fusos horários também oferecem suporte ao atributo fold introduzido em PEP 495. Durante transições de deslocamento que induzem horários ambíguos (como uma transição do horário de verão para o horário padrão), o deslocamento anterior à transição é usado quando fold=0, e o deslocamento posterior à transição é usado quando fold=1, por exemplo:

>>> dt = datetime(2020, 11, 1, 1, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-11-01 01:00:00-07:00

>>> print(dt.replace(fold=1))
2020-11-01 01:00:00-08:00

Ao converter de outro fuso horário, a dobra será definida para o valor correto:

>>> from datetime import timezone
>>> LOS_ANGELES = ZoneInfo("America/Los_Angeles")
>>> dt_utc = datetime(2020, 11, 1, 8, tzinfo=timezone.utc)

>>> # Antes da transição PDT -> PST
>>> print(dt_utc.astimezone(LOS_ANGELES))
2020-11-01 01:00:00-07:00

>>> # Após a transição PDT -> PST
>>> print((dt_utc + timedelta(hours=1)).astimezone(LOS_ANGELES))
2020-11-01 01:00:00-08:00

Fontes de dados

O módulo zoneinfo não fornece dados de fuso horário diretamente, mas, em vez disso, extrai informações de fuso horário do banco de dados de fuso horário do sistema ou do pacote PyPI original tzdata, se disponível. Alguns sistemas, incluindo principalmente os Windows, não possuem um banco de dados IANA disponível e, portanto, para projetos que buscam compatibilidade multiplataforma e exigem dados de fuso horário, recomenda-se declarar uma dependência em tzdata. Se nem os dados do sistema nem o tzdata estiverem disponíveis, todas as chamadas para ZoneInfo levantarão ZoneInfoNotFoundError.

Configurando as fontes de dados

Quando ZoneInfo(key) é chamado, o construtor primeiro pesquisa nos diretórios especificados em TZPATH por um arquivo que corresponda a key e, em caso de falha, procura uma correspondência no pacote tzdata. Esse comportamento pode ser configurado de três maneiras:

  1. O padrão TZPATH, quando não especificado de outra forma, pode ser configurado em tempo de compilação.

  2. TZPATH pode ser configurado usando uma variável de ambiente.

  3. Em tempo de execução, o caminho de pesquisa pode ser manipulado usando a função reset_tzpath().

Configuração em tempo de compilação

O TZPATH padrão inclui vários locais de implantação comuns para o banco de dados de fuso horário (exceto no Windows, onde não há locais “conhecidos” para dados de fuso horário). Em sistemas POSIX, distribuidores downstream e aqueles que constroem o Python a partir do código-fonte e que sabem onde os dados de fuso horário do sistema estão implantados podem alterar o caminho do fuso horário padrão especificando a opção de tempo de compilação TZPATH (ou, mais provavelmente, o sinalizador de configuração --with-tzpath), que deve ser uma string delimitada por os.pathsep.

Em todas as plataformas, o valor configurado está disponível como a chave TZPATH em sysconfig.get_config_var().

Configuração do ambiente

Ao inicializar TZPATH (no momento da importação ou sempre que reset_tzpath() for chamado sem argumentos), o módulo zoneinfo usará a variável de ambiente PYTHONTZPATH, se existir, para definir o caminho de pesquisa.

PYTHONTZPATH

Esta é uma string separada por os.pathsep contendo o caminho de pesquisa de fuso horário a ser usado. Ela deve consistir apenas em caminhos absolutos, e não relativos. Componentes relativos especificados em PYTHONTZPATH não serão usados, mas, caso contrário, o comportamento quando um caminho relativo é especificado é definido pela implementação; o CPython levantará InvalidTZPathWarning, mas outras implementações podem ignorar silenciosamente o componente incorreto ou levantar uma exceção.

Para configurar o sistema para ignorar os dados do sistema e usar o pacote tzdata, defina PYTHONTZPATH="".

Configuração em tempo de execução

O caminho de busca TZ também pode ser configurado em tempo de execução usando a função reset_tzpath(). Geralmente, essa não é uma operação aconselhável, embora seja razoável usá-la em funções de teste que exigem o uso de um caminho de fuso horário específico (ou que exijam a desativação do acesso aos fusos horários do sistema).

A classe ZoneInfo

class zoneinfo.ZoneInfo(key)

Uma subclasse concreta de datetime.tzinfo que representa um fuso horário IANA especificado pela string key. Chamadas ao construtor primário sempre retornarão objetos que sejam idênticos em comparação; em outras palavras, exceto pela invalidação de cache via ZoneInfo.clear_cache(), para todos os valores de key, a seguinte asserção será sempre verdadeira:

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

key deve estar no formato de um caminho POSIX relativo e normalizado, sem referências de nível superior. O construtor levantará ValueError se uma chave não conforme for passada.

Se nenhum arquivo correspondente a key for encontrado, o construtor levantará ZoneInfoNotFoundError.

A classe ZoneInfo tem dois construtores alternativos:

classmethod ZoneInfo.from_file(file_obj, /, key=None)

Constructs a ZoneInfo object from a file-like object returning bytes (e.g. a file opened in binary mode or an io.BytesIO object). Unlike the primary constructor, this always constructs a new object.

The key parameter sets the name of the zone for the purposes of __str__() and __repr__().

Objects created via this constructor cannot be pickled (see pickling).

classmethod ZoneInfo.no_cache(key)

An alternate constructor that bypasses the constructor’s cache. It is identical to the primary constructor, but returns a new object on each call. This is most likely to be useful for testing or demonstration purposes, but it can also be used to create a system with a different cache invalidation strategy.

Objects created via this constructor will also bypass the cache of a deserializing process when unpickled.

Cuidado

Using this constructor may change the semantics of your datetimes in surprising ways, only use it if you know that you need to.

The following class methods are also available:

classmethod ZoneInfo.clear_cache(*, only_keys=None)

A method for invalidating the cache on the ZoneInfo class. If no arguments are passed, all caches are invalidated and the next call to the primary constructor for each key will return a new instance.

If an iterable of key names is passed to the only_keys parameter, only the specified keys will be removed from the cache. Keys passed to only_keys but not found in the cache are ignored.

Aviso

Invoking this function may change the semantics of datetimes using ZoneInfo in surprising ways; this modifies module state and thus may have wide-ranging effects. Only use it if you know that you need to.

A classe possui um atributo:

ZoneInfo.key

This is a read-only attribute that returns the value of key passed to the constructor, which should be a lookup key in the IANA time zone database (e.g. America/New_York, Europe/Paris or Asia/Tokyo).

For zones constructed from file without specifying a key parameter, this will be set to None.

Nota

Although it is a somewhat common practice to expose these to end users, these values are designed to be primary keys for representing the relevant zones and not necessarily user-facing elements. Projects like CLDR (the Unicode Common Locale Data Repository) can be used to get more user-friendly strings from these keys.

String representations

The string representation returned when calling str on a ZoneInfo object defaults to using the ZoneInfo.key attribute (see the note on usage in the attribute documentation):

>>> zone = ZoneInfo("Pacific/Kwajalein")
>>> str(zone)
'Pacific/Kwajalein'

>>> dt = datetime(2020, 4, 1, 3, 15, tzinfo=zone)
>>> f"{dt.isoformat()} [{dt.tzinfo}]"
'2020-04-01T03:15:00+12:00 [Pacific/Kwajalein]'

For objects constructed from a file without specifying a key parameter, str falls back to calling repr(). ZoneInfo’s repr is implementation-defined and not necessarily stable between versions, but it is guaranteed not to be a valid ZoneInfo key.

Pickle serialization

Rather than serializing all transition data, ZoneInfo objects are serialized by key, and ZoneInfo objects constructed from files (even those with a value for key specified) cannot be pickled.

The behavior of a ZoneInfo file depends on how it was constructed:

  1. ZoneInfo(key): When constructed with the primary constructor, a ZoneInfo object is serialized by key, and when deserialized, the deserializing process uses the primary and thus it is expected that these are expected to be the same object as other references to the same time zone. For example, if europe_berlin_pkl is a string containing a pickle constructed from ZoneInfo("Europe/Berlin"), one would expect the following behavior:

    >>> a = ZoneInfo("Europe/Berlin")
>>> b = pickle.loads(europe_berlin_pkl)
>>> a is b
True

  2. ZoneInfo.no_cache(key): When constructed from the cache-bypassing constructor, the ZoneInfo object is also serialized by key, but when deserialized, the deserializing process uses the cache bypassing constructor. If europe_berlin_pkl_nc is a string containing a pickle constructed from ZoneInfo.no_cache("Europe/Berlin"), one would expect the following behavior:

    >>> a = ZoneInfo("Europe/Berlin")
>>> b = pickle.loads(europe_berlin_pkl_nc)
>>> a is b
False

  3. ZoneInfo.from_file(file_obj, /, key=None): When constructed from a file, the ZoneInfo object raises an exception on pickling. If an end user wants to pickle a ZoneInfo constructed from a file, it is recommended that they use a wrapper type or a custom serialization function: either serializing by key or storing the contents of the file object and serializing that.

This method of serialization requires that the time zone data for the required key be available on both the serializing and deserializing side, similar to the way that references to classes and functions are expected to exist in both the serializing and deserializing environments. It also means that no guarantees are made about the consistency of results when unpickling a ZoneInfo pickled in an environment with a different version of the time zone data.

Funções

zoneinfo.available_timezones()

Get a set containing all the valid keys for IANA time zones available anywhere on the time zone path. This is recalculated on every call to the function.

This function only includes canonical zone names and does not include “special” zones such as those under the posix/ and right/ directories, or the posixrules zone.

Cuidado

This function may open a large number of files, as the best way to determine if a file on the time zone path is a valid time zone is to read the “magic string” at the beginning.

Nota

These values are not designed to be exposed to end-users; for user facing elements, applications should use something like CLDR (the Unicode Common Locale Data Repository) to get more user-friendly strings. See also the cautionary note on ZoneInfo.key.

zoneinfo.reset_tzpath(to=None)

Sets or resets the time zone search path (TZPATH) for the module. When called with no arguments, TZPATH is set to the default value.

Calling reset_tzpath will not invalidate the ZoneInfo cache, and so calls to the primary ZoneInfo constructor will only use the new TZPATH in the case of a cache miss.

The to parameter must be a sequence of strings or os.PathLike and not a string, all of which must be absolute paths. ValueError will be raised if something other than an absolute path is passed.

Globals

zoneinfo.TZPATH

A read-only sequence representing the time zone search path – when constructing a ZoneInfo from a key, the key is joined to each entry in the TZPATH, and the first file found is used.

TZPATH may contain only absolute paths, never relative paths, regardless of how it is configured.

The object that zoneinfo.TZPATH points to may change in response to a call to reset_tzpath(), so it is recommended to use zoneinfo.TZPATH rather than importing TZPATH from zoneinfo or assigning a long-lived variable to zoneinfo.TZPATH.

For more information on configuring the time zone search path, see Configurando as fontes de dados.

Exceptions and warnings

exception zoneinfo.ZoneInfoNotFoundError

Raised when construction of a ZoneInfo object fails because the specified key could not be found on the system. This is a subclass of KeyError.

exception zoneinfo.InvalidTZPathWarning

Raised when PYTHONTZPATH contains an invalid component that will be filtered out, such as a relative path.