16.3. time — Acesso ao horário e conversões

---

Esse módulo provê várias funções relacionadas à tempo. Para funcionalidades relacionadas veja também os módulos datetime e calendar

Apesar desse módulo sempre estar disponível, nem todas as suas funções estão disponíveis em todas as plataformas. A maioria das funções definidas nesse módulo chamam funções da biblioteca da plataforma de C com mesmo nome. Pode ser útil consultar a documentação da plataforma, pois da semântica dessas funções variam a depender da plataforma.

A seguir, uma explicação de algumas terminologias e convenções.

• A epoca é o ponto onde o tempo começa e depende da plataforma. Em Unix, a época é 1ª de Janeiro de 1970, ás 00:00:00 (UTC). Para descobrir a época em alguma plataforma, veja em time.gmtime(0)

• O termo segundos desde a época refere-se ao número total de segundos decorrido desde a época, tipicamente excluindo-se os segundos bissextos. Segundos bissextos são excluídos desse total em todas as plataformas compatíveis com POSIX.

• As funções desse módulo podem não conseguir tratar de datas e horários antes da época ou muito distantes no futuro. O limite no futuro é determinado pela biblioteca C; para sistemas de 32 bit, geralmente é 2038.

• Year 2000 (Y2K) issues: Python depends on the platform’s C library, which generally doesn’t have year 2000 issues, since all dates and times are represented internally as seconds since the epoch. Function strptime() can parse 2-digit years when given %y format code. When 2-digit years are parsed, they are converted according to the POSIX and ISO C standards: values 69–99 are mapped to 1969–1999, and values 0–68 are mapped to 2000–2068.

• UTC é Coordinated Universal Time (antigamente conhecido como Greenwich Mean Time ou GMT). O acrônimo UTC não é um erro, mas um acordo entre inglês e francês.

• DST é Daylight Saving Time (Horário de Verão), um ajuste de fuso horário por (normalmente) uma hora durante parte do ano. As regras de Horário de Verão são mágicas (determinadas por leis locais) e podem mudar de ano a ano. A biblioteca C possui uma tabela contendo as regras locais (normalmente lidas de um arquivo de sistema por flexibilidade) e nesse contexto é a única fonte de Conhecimento Verdadeiro.

• A precisão de várias funções em tempo real podem ser menores do que o que pode estar sugerido pelas unidades nas quais seu valor ou argumento estão expressos. E.g. na maioria dos sistemas Unix, o relógio “conta” apenas 50 ou 100 vezes por segundo.

• Por outro lado, a precisão de time() e sleep() é melhor do que suas equivalentes Unix: Tempos são expressos como números em ponto flutuante, time() retorna o tempo mais preciso disponível (utilizando gettimeofday() do Unix, quando disponível) e sleep() irá aceitar qualquer tempo como uma fração não zero (select() do Unix é utilizada para implementar isto, quando disponível).

• O valor de tempo conforme retornado pelas gmtime(), localtime(), e strptime(), e aceito pelas asctime(), mktime() e strftime(), é uma sequência de 9 inteiros. Os valores retornados das gmtime(), localtime(), e strptime() também oferecem nomes de atributo para campos individuais.

  Veja struct_time para a descrição desses objetos.

  Alterado na versão 3.3: O tipo struct_time foi estendido para prover os atributos tm_gmtoff e tm_zone quando a plataforma suporta os membros struct tm correspondentes

  Alterado na versão 3.6: Os atributos tm_gmtoff e tm_zone da classe struct_time estão disponíveis em todas as plataformas agora.

• Utilize as seguintes funções para converter entre representações de tempo:

  De	Para	Utilize
  segundos desde a época	struct_time em UTC	gmtime()
  segundos desde a época	struct_time em tempo local	localtime()
  struct_time em UTC	segundos desde a época	calendar.timegm()
  struct_time em tempo local	segundos desde a época	mktime()

16.3.1. Funções

time.asctime([t])

Convert a tuple or struct_time representing a time as returned by gmtime() or localtime() to a string of the following form: 'Sun Jun 20 23:21:05 1993'. If t is not provided, the current time as returned by localtime() is used. Locale information is not used by asctime().

Nota

Diferentemente da função em C de mesmo nome, asctime() não adiciona uma nova linha em seguida.

time.clock()

On Unix, return the current processor time as a floating point number expressed in seconds. The precision, and in fact the very definition of the meaning of “processor time”, depends on that of the C function of the same name.

On Windows, this function returns wall-clock seconds elapsed since the first call to this function, as a floating point number, based on the Win32 function QueryPerformanceCounter(). The resolution is typically better than one microsecond.

Obsoleto desde a versão 3.3: The behaviour of this function depends on the platform: use perf_counter() or process_time() instead, depending on your requirements, to have a well defined behaviour.

time.clock_getres(clk_id)

Retorna a resolução (precisão) do relógio clk_id especificado. Confira Constantes de ID de Relógio para uma lista de valores aceitos para clk_id

Disponibilidade: Unix.

Novo na versão 3.3.

time.clock_gettime(clk_id)

Retorna o tempo to relógio clk_id especificado. Confira Constantes de ID de Relógio para uma lista de valores aceitos para clk_id.

Disponibilidade: Unix.

Novo na versão 3.3.

time.clock_settime(clk_id, time)

Define o tempo do relógio clk_id especificado. Atualmente, CLOCK_REALTIME é o único valor aceito para clk_id.

Disponibilidade: Unix.

Novo na versão 3.3.

time.ctime([secs])

Convert a time expressed in seconds since the epoch to a string representing local time. If secs is not provided or None, the current time as returned by time() is used. ctime(secs) is equivalent to asctime(localtime(secs)). Locale information is not used by ctime().

time.get_clock_info(name)

Obtém informação do relógio específico como um objeto espaço de nomes. Nomes de relógios suportados e as funções correspondentes para ler seus valores são:

• 'clock': time.clock()

• 'monotonic': time.monotonic()

• 'perf_counter': time.perf_counter()

• 'process_time': time.process_time()

• 'time': time.time()

O resultado possui os seguintes atributos:

• adjustable: True se o relógio pode ser alterado automaticamente (e.g. por um daemon NTP) ou manualmente por um administrador do sistema, False se contrário

• implementation: O nome da função C subjacente utilizada para obter o valor do relógio. Confira Constantes de ID de Relógio para valores possíveis.

• monotonic: True se o relógio não pode retornar a valores anteriores, backward, False contrário

• resolution: A resolução do relógio em segundos (float)

Novo na versão 3.3.

time.gmtime([secs])

Converte um tempo expresso em segundos desde a época para uma struct_time em UTC onde o sinalizador de horário de verão é sempre zero. Se secs não é fornecido ou None, o tempo atual como retornado por time() é utilizado. Frações de segundo são ignoradas. Veja acima para uma descrição do objeto struct_time. Veja calendar.timegm() para o inverso desta função.

time.localtime([secs])

Como gmtime(), mas converte para o tempo local. Se secs não é fornecido ou None, o tempo atual como retornado por time() é utilizado. O sinalizador de horário de verão é definido como 1 quando o Horário de verão for aplicável para o tempo fornecido.

time.mktime(t)

Esta é a função inversa de localtime(). Seu argumento é a struct_time ou uma 9-tupla (sendo o sinalizador de horário de verão necessário; utilize -1 como sinalizador de horário de verão quando este for desconhecido) que expressa o tempo em tempo local, não UTC. Retorna um número em ponto flutuante, para ter compatibilidade com time(). Se o valor de entrada não puder ser representado como um tempo válido, ou OverflowError ou ValueError serão levantadas (o que irá depender se o valor inválido é capturado pelo Python ou por bibliotecas C subjacentes). A data mais recente para qual um tempo pode ser gerado é dependente da plataforma.

time.monotonic()

Return the value (in fractional seconds) of a monotonic clock, i.e. a clock that cannot go backwards. The clock is not affected by system clock updates. The reference point of the returned value is undefined, so that only the difference between the results of consecutive calls is valid.

On Windows versions older than Vista, monotonic() detects GetTickCount() integer overflow (32 bits, roll-over after 49.7 days). It increases an internal epoch (reference time) by 2³² each time that an overflow is detected. The epoch is stored in the process-local state and so the value of monotonic() may be different in two Python processes running for more than 49 days. On more recent versions of Windows and on other operating systems, monotonic() is system-wide.

Novo na versão 3.3.

Alterado na versão 3.5: A função não está sempre disponível.

time.perf_counter()

Return the value (in fractional seconds) of a performance counter, i.e. a clock with the highest available resolution to measure a short duration. It does include time elapsed during sleep and is system-wide. The reference point of the returned value is undefined, so that only the difference between the results of consecutive calls is valid.

Novo na versão 3.3.

time.process_time()

Return the value (in fractional seconds) of the sum of the system and user CPU time of the current process. It does not include time elapsed during sleep. It is process-wide by definition. The reference point of the returned value is undefined, so that only the difference between the results of consecutive calls is valid.

Novo na versão 3.3.

time.sleep(secs)

Execução suspensa da thread chamada para o número de segundos dado. O argumento pode ser um número em ponto flutuante para indicar um tempo de sono mais preciso. O tempo de suspensão atual pode ser menor do que o solicitado porque qualquer sinal capturado irá terminar sleep() seguindo a execução da rotina de captura daquele sinal. Além disso, o tempo de suspensão pode ser maior do que o solicitado por uma quantidade arbitrária devido ao agendamento de outra atividade no sistema.

Alterado na versão 3.5: A função agora dorme por pelo menos secs mesmo se o sono é interrompido por um sinal, exceto se o tratador de sinal levanta uma exceção (veja PEP 475 para a explicação).

time.strftime(format[, t])

Converte a tupla ou struct_time representando um tempo como retornado por gmtime() ou localtime() para uma string como especificado pelo argumento format. Se t não é fornecido, o tempo atual como retornado pela localtime() é utilizado. format deve ser uma string. ValueError é levantado se qualquer campo em t está fora do intervalo permitido.

0 é um argumento legal para qualquer posição na tupla de tempo; se é normalmente ilegal, o valor é formado a um valor correto.

As diretivas a seguir podem ser incorporadas na string format. Elas estão mostradas sem os campos de comprimento e especificação de precisão opcionais, e estão substituídos pelos caracteres indicados no resultado da strftime():

Diretiva	Significado	Notas
%a	Nome abreviado do dia da semana da localidade.
%A	Nome completo do dia da semana da localidade.
%b	Nome abreviado do mês da localidade.
%B	Nome completo do mês da localidade.
%c	Representação de data e hora apropriada da localidade.
%d	Dia do mês como um número decimal [01,31].
%H	Hora (relógio 24 horas) como um número decimal [00,23].
%I	Hora (relógio 12 horas) como um número decimal [01,12].
%j	Dia do ano como um número decimal [001,366].
%m	Mês como um número decimal [01,12].
%M	Minuto como um número decimal [00,59].
%p	Equivalente da localidade a AM ou PM.	(1)
%S	Segundo como um número decimal [00,61].	(2)
%U	Número da semana do ano (domingo como primeiro dia da semana) como um número decimal [00,53]. Todos os dias em um ano novo que precedem o primeiro domingo são considerados como estando na semana 0.	(3)
%w	Dia da semana como um número decimal [0(Domingo),6]
%W	Número da semana do ano (segunda-feira como o primeiro dia da semana) como um número decimal [00,53]. Todos os dias do ano que precedem o primeiro domingo serão considerados como estando na semana 0.	(3)
%x	Representação de data apropriada de localidade.
%X	Representação de hora apropriada da localidade.
%y	Ano sem século como um número decimal [00,99].
%Y	Ano com o século como um número decimal.
%z	Deslocamento de fuso horário indicando uma diferença de tempo positiva ou negativa de UTC/GMT formatado como +HHMM ou -HHMM, onde H representa os dígitos decimais de hora e M representa os dígitos decimais de minuto [-23:59, +23:59].
%Z	Nome do fuso horário (nenhum caractere se nenhum fuso horário existe).
%%	Um caractere literal '%'.

Notas:

1. Quando utilizado com a função strptime(), a diretiva %p apenas afeta a saída do campo se a diretiva %I é utilizada para analisar a hora.

2. O intervalo é realmente 0 até 61; o valor 60 é válido em timestamps representando segundos bissextos e o valor 61 é suportado por razões históricas.

3. Quando utilizado co a função strptime(), %U e %W são utilizados em cálculos apenas quando o dia da semana e ano são especificados.

Veja este exemplo, um formato para datas compatível com as especificações dos padrões de e-mail RFC 2822. 1

>>> from time import gmtime, strftime
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
'Thu, 28 Jun 2001 14:17:15 +0000'

Diretivas adicionais podem ser suportadas por algumas plataformas, mas apenas as listadas aqui possuem significado padronizado por ANSI C. Para ver a lista completa de códigos de formato suportados na sua plataforma, consulte a documentação strftime(3).

Em algumas plataformas, um campo adicional de comprimento e especificação de precisão podem seguir imediatamente após '%' como uma diretiva da seguinte ordem; isto também não é portátil. O campo comprimento normalmente é 2 exceto para %j quando é 3.

time.strptime(string[, format])

Analisa a string representando um tempo de acordo com um formato. O valor retornado é um struct_time como retornado por gmtime() ou localtime().

O parâmetro format utiliza as mesmas diretivas das utilizadas por strftime(); é definido por padrão para "%a %b %d %H:%M:%S %Y" que corresponde com a formatação retornada por ctime(). Se string não puder ser analisada de acordo com format, ou se possui excesso de dados após analisar, ValueError é levantado. Os valores padrão utilizados para preencher quaisquer dados faltantes quando valores mais precisos não puderem ser inferidos são (1900, 1, 1, 0, 0, 0, 0, 1, -1). Ambos string e format devem ser strings.

Por exemplo:

>>> import time
>>> time.strptime("30 Nov 00", "%d %b %y")   
time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0,
                 tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)

Suporte para a diretiva %Z é baseado nos valores contidos em tzname e se daylight é verdade. Por causa disso, é específico de plataforma exceto por reconhecer UTC e GMT, que são sempre conhecidos (e considerados fuso horários sem horários de verão).

Apenas as diretivas especificadas na documentação são suportadas. Como strftime() é implementada por plataforma, esta pode apenas as vezes oferecer mais diretivas do que as listadas aqui. Mas strptime() é independente de quaisquer plataformas e portanto não necessariamente suporta todas as diretivas disponíveis que não estão documentadas como suportadas.

class time.struct_time

O tipo da sequência de valor de tempo retornado por gmtime(), localtime(), e strptime(). É um objeto com uma interface named tuple: os valores podem ser acessados por um índice e por um nome de atributo. Os seguintes valores estão presentes:

Index	Atributo	Valores
0	tm_year	(por exemplo, 1993)
1	tm_mon	intervalo [1,12]
2	tm_mday	intervalo [1,31]
3	tm_hour	intervalo [0,23]
4	tm_min	intervalo [0,59]
5	tm_sec	intervalo [0,61]; veja (2) na descrição de strftime()
6	tm_wday	intervalo [0,6], segunda-feira é 0
7	tm_yday	intervalo [1, 366]
8	tm_isdst	0, 1 ou -1; veja abaixo
N/D	tm_zone	abreviação do nome do fuso horário
N/D	tm_gmtoff	deslocamento a leste de UTC em segundos

Note que diferentemente da estrutura C, o valor do mês é um intervalo [1,12] e não [0,11].

Em chamadas para mktime(), tm_isdst pode ser definido como 1 quando o horário de verão estiver em efeito, e 0 quando não. Um valor de -1 indica que esta informação não é conhecida, e geralmente resultará no preenchimento do estado correto.

Quando uma tupla com comprimento incorreto é passada para uma função que espera por um struct_time, ou por possuir elementos do tipo errado, um TypeError é levantado.

time.time()

Retorna o tempo em segundos desde a era como um número em ponto flutuante. A data específica da era e a manipulação de segundos bissextos são dependentes da plataforma. Em Windows e na maioria dos sistemas Unix, a era é 1 de janeiro de 1970, 00:00:00 (UTC)

Note que mesmo o tempo sendo retornado sempre como um número em ponto flutuante, nem todos os sistemas fornecem o tempo com precisão melhor que 1 segundo. Enquanto esta função normalmente retorna valores não decrescentes, pode retornar valores menores do que os de uma chamada anterior se o relógio do sistema foi redefinido entre duas chamadas.

O número retornado por time() pode ser convertido a um formato de tempo mais comum (i.e. ano, mês, dia, hora etc…) em UTC por passá-lo para a função gmtime() ou em tempo local por passar para a função localtime(). Em ambos os casos, o objeto struct_time é retornado, por onde os componentes de data do calendário podem ser acessados ou atribuídos.

time.tzset()

Resets the time conversion rules used by the library routines. The environment variable TZ specifies how this is done.

Disponibilidade: Unix.

Nota

Embora em vários casos, alterar a variável de sistema TZ pode afetar a saída de funções como localtime() sem chamar tzset(), este comportamento não deve ser confiado.

A variável de sistema TZ não deve conter espaços em branco.

O formato padrão da variável de sistema TZ é (espaços foram adicionados por motivos de clareza):

std offset [dst [offset [,start[/time], end[/time]]]]

Onde os componentes são:

std e dst

Três ou mais alfanuméricos fornecendo a abreviação do fuso horário. Estes serão propagados para time.tzname

offset

O deslocamento tem a forma: ± hh[:mm[:ss]]. Isso indica que o valor adicionado adicionou o horário local para chegar a UTC. Se precedido por um ‘-‘, o fuso horário está a leste do Meridiano Primário; do contrário, está a oeste. Se nenhum deslocamento segue o horário de verão, o tempo no verão é assumido como estando uma hora a frente do horário padrão.

start[/time], end[/time]

Indica quando mudar e voltar do Horário de Verão. O formato das datas de início e fim é um dos seguintes:

Jn

I dia juliano n (1 <= n <= 365). Os dias bissextos não são contados, então, em todos os anos, 28 de fevereiro é o dia 59 e 1 de março é o dia 60.

n

O dia juliano baseado em zero (0 <= n <= 365). Dias bissextos são contados, e é possível fazer referência a 29 de fevereiro.

Mm.n.d

O d-ésimo dia (0 <= d <= 6) da semana n do mês m do ano (1 <= n <= 5, 1 <= m <= 12, onde semana 5 significa “o último dia d no mês m” que pode ocorrer tanto na quarta como quinta semana). Semana 1 é a primeira semana na qual o d-ésimo dia ocorre. Dia zero é o domingo.

time tem o mesmo formato que offset, exceto que nenhum sinal no início é permitido (‘-‘ ou ‘+’). O padrão, se o tempo não é dado, é 02:00:00.

>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'02:07:36 05/08/03 EDT'
>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'16:08:12 05/08/03 AEST'

Em muitos sistemas Unix (incluindo *BSD, Linux, Solaris, e Darwin), é mais conveniente utilizar o banco de dados de informação de fuso do sistema (tzfile(5)) para especificar as regras de fuso horário. Para fazer isso, defina a variável de sistema TZ ao path do arquivo de dados requerido de fuso horários, relativo à raiz do banco de dados de fuso horário ‘zoneinfo’ do sistema, geralmente encontrado em /usr/share/zoneinfo. Por exemplo, 'US/Eastern', 'Australia/Melbourne', 'Egypt' ou 'Europe/Amsterdam'.

>>> os.environ['TZ'] = 'US/Eastern'
>>> time.tzset()
>>> time.tzname
('EST', 'EDT')
>>> os.environ['TZ'] = 'Egypt'
>>> time.tzset()
>>> time.tzname
('EET', 'EEST')

16.3.2. Constantes de ID de Relógio

Essas constantes são utilizadas como parâmetros para clock_getres() e clock_gettime().

time.CLOCK_HIGHRES

O Solaris OS possui um timer CLOCK_HIGHRES que tenta utilizar recursos otimizados do hardware, e pode fornecer resolução perto de nanossegundos. CLOCK_HIGHRES é o relógio nanoajustável de alta resolução.

Availability: Solaris.

Novo na versão 3.3.

time.CLOCK_MONOTONIC

Relógio que não pode ser definido e representa um tempo monotônico desde um ponto de início não especificado.

Disponibilidade: Unix.

Novo na versão 3.3.

time.CLOCK_MONOTONIC_RAW

Semelhante à CLOCK_MONOTONIC, mas fornece acesso a um tempo bruto baseado em hardware que não está sujeito a ajustes NTP.

Availability: Linux 2.6.28 or later.

Novo na versão 3.3.

time.CLOCK_PROCESS_CPUTIME_ID

Timer de alta resolução por processo no CPU.

Disponibilidade: Unix.

Novo na versão 3.3.

time.CLOCK_THREAD_CPUTIME_ID

Relógio de tempo de CPU específico a thread.

Disponibilidade: Unix.

Novo na versão 3.3.

A constante a seguir é o único parâmetro que pode ser enviado para clock_settime().

time.CLOCK_REALTIME

Relógio em tempo real de todo o sistema. Definições deste relógio requerem privilégios apropriados.

Disponibilidade: Unix.

Novo na versão 3.3.

16.3.3. Constantes de Fuso Horário

time.altzone

O deslocamento do fuso horário DST local, em segundos a oeste de UTC, se algum for fornecido. É negativo se o fuso horário DST local está a leste de UTC (como na Europa Ocidental, incluindo o Reino Unido). Somente utilize se daylight for diferente de zero. Veja a nota abaixo.

time.daylight

Diferente de zero se um fuso horário DST é definido. Veja nota abaixo.

time.timezone

O deslocamento para o fuso horário local (não DST), em segundos a oeste de UTC (negativo na maior parte da Europa Ocidental, positivo nos Estados Unidos e Brasil, zero no Reino Unido). Ver nota abaixo.

time.tzname

A tupla de duas strings: A primeira é o nome do fuso horário local não DST, a segunda é o nome do fuso horário local DST. Se nenhum fuso horário DST for definido, a segunda string é usada. Veja nota abaixo.

Nota

Para as constantes de Fuso Horário acima (altzone, daylight, timezone, e tzname), o valor é determinado pelas regras de fuso horário em efeito no módulo de carregamento de tempo ou a última vez que tzset() é chamada e pode estar incorreto para tempos no passado. É recomendado utilizar os resultados tm_gmtoff e tm_zone da localtime() para obter informação de fuso horário.

Ver também

Módulo datetime

Mais interfaces orientada a objetos para datas e tempos.

Módulo locale

Serviços de internacionalização. A configuração de localidade afeta a interpretação de muitos especificadores de formato em strftime() e strptime().

Módulo calendar

Funções gerais relacionadas a calendários. timegm() é a função inversa de gmtime() deste módulo.

Notas de rodapé

1

A utilização de %Z está descontinuada, mas o escape %z que expande para um deslocamento hora/minuto preferido não é suportado por todas as bibliotecas ANSI C. Além disso, a leitura do padrão original RFC 822 de 1982 mostra que este pede um ano com dois dígitos (%y em vez de %Y), mas a prática consolidou a utilização de anos com 4 dígitos mesmo antes dos anos 2000. Após isso, o RFC 822 se tornou obsoleto e o ano de 4 dígitos foi primeiro recomendado por RFC 1123 e depois obrigatório por RFC 2822.