datetime — Tipos básicos de data e hora

Código-fonte: Lib/datetime.py

---

O módulo datetime fornece as classes para manipulação de datas e horas.

Ainda que a aritmética de data e hora seja suportada, o foco da implementação é na extração eficiente do atributo para formatação da saída e manipulação.

Dica

Pular para os códigos de formatação.

Ver também

Módulo calendar

Funções gerais relacionadas ao calendário.

Módulo time

Acesso de hora e conversões.

Módulo zoneinfo

Fusos horários concretos representando o banco de dados de fusos horários IANA.

Pacote dateutil

Biblioteca de terceiros com fuso horário expandido e suporte à análise.

Package DateType

Biblioteca de terceiros que apresenta tipos estáticos distintos, por exemplo. permitir que verificadores de tipo estático diferenciem datas ingênuas e conscientes.

Objetos Conscientes e Ingênuos

Objetos de data e hora podem ser categorizados como “consciente” ou “ingênuo” dependendo se eles incluem ou não informação sobre fuso horário.

Com conhecimento suficiente dos ajustes de tempo algorítmicos e políticos aplicáveis, como informações de fuso horário e horário de verão, um objeto consciente pode se localizar em relação a outros objetos conscientes. Um objeto consciente representa um momento específico no tempo que não está aberto à interpretação. [1]

Um objeto ingênuo não contém informações suficientes para se localizar inequivocamente em relação a outros objetos de data/hora. Se um objeto ingênuo representa o Coordinated Universal Time (UTC), a hora local, ou a hora em algum outro fuso horário, isso depende exclusivamente do programa, assim como é tarefa do programa decidir se um número específico representa metros, milhas ou massa. Objetos ingênuos são fáceis de entender e trabalhar, com o custo de ignorar alguns aspectos da realidade.

Para aplicativos que requerem objetos conscientes, os objetos datetime e time possuem um atributo opcional de informações do fuso horário, tzinfo, que pode ser definido como uma instância de uma subclasse da classe abstrata tzinfo. Esses objetos tzinfo capturam informações sobre a diferença da hora UTC, o nome do fuso horário e se o horário de verão está em vigor.

Somente uma classe concreta tzinfo, a classe timezone, é fornecida pelo módulo datetime. A classe timezone pode representar fusos horários simples com diferenças fixas do UTC, como o próprio UTC, ou os fusos horários norte-americanos EST e EDT. O suporte a fusos horários em níveis mais detalhados depende da aplicação. As regras para ajuste de tempo em todo o mundo são mais políticas do que racionais, mudam com frequência e não há um padrão adequado para todas as aplicações além da UTC.

Constantes

O módulo datetime exporta as seguintes constantes:

datetime.MINYEAR

The smallest year number allowed in a date or datetime object. MINYEAR is 1.

datetime.MAXYEAR

The largest year number allowed in a date or datetime object. MAXYEAR is 9999.

datetime.UTC

Apelido para o singleton de fuso horário UTC datetime.timezone.utc.

Novo na versão 3.11.

Tipos disponíveis

class datetime.date

Uma data ingênua idealizada, presumindo que o atual calendário Gregoriano sempre foi, e sempre estará em vigor. Atributos: year, month, e day.

class datetime.time

Um horário ideal, independente de qualquer dia em particular, presumindo que todos os dias tenham exatamente 24*60*60 segundos. (Não há noção de “segundos bissextos” aqui.) Atributos: hour, minute, second, microsecond e tzinfo.

class datetime.datetime

Uma combinação de uma data e uma hora. Atributos: year, month, day, hour, minute, second, microsecond, e tzinfo.

class datetime.timedelta

Uma duração que expressa a diferença entre duas instâncias datetime ou date para resolução de microssegundos.

class datetime.tzinfo

Uma classe base abstrata para objetos de informações de fuso horário. Eles são usados pelas classes datetime e time para fornecer uma noção personalizável de ajuste de horário (por exemplo, para considerar o fuso horário e/ou o horário de verão).

class datetime.timezone

Uma classe que implementa a classe base abstrata tzinfo como uma diferença fixa do UTC.

Novo na versão 3.2.

Objetos desse tipo são imutáveis.

Relacionamentos de subclasse:

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

Propriedades Comuns

Os tipos date, datetime, time e timezone compartilham esses recursos comuns:

• Objetos desse tipo são imutáveis.

• Objetos desses tipos são hasheáveis, o que significa que podem ser usados como chaves de dicionário.

• Objetos desse tipo suportam decapagem eficiente através do módulo pickle.

Determinando se um Objeto é Consciente ou Ingênuo

Objetos do tipo date são sempre ingênuos.

Um objeto do tipo time ou datetime pode ser consciente ou ingênuo.

O objeto datetime d é consciente se ambos os seguintes itens forem verdadeiros:

1. d.tzinfo não é None

2. d.tzinfo.utcoffset(d) não retorna None

Caso contrário, d é ingênuo.

O objeto time t é consciente, se os seguintes itens são verdadeiros:

1. t.tzinfo não é None

2. t.tzinfo.utcoffset(None) não retorna None.

Caso contrário, t é ingênuo.

A distinção entre consciente e ingênuo não se aplica a objetos timedelta.

Objetos timedelta

O objeto timedelta representa uma duração, a diferença entre duas instâncias datetime ou date.

class datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)

All arguments are optional and default to 0. Arguments may be integers or floats, and may be positive or negative.

Apenas dias, segundos e microssegundos são armazenados internamente. Os argumentos são convertidos para essas unidades:

• Um milissegundo é convertido em 1000 microssegundos.

• Um minuto é convertido em 60 segundos.

• Uma hora é convertida em 3600 segundos.

• Uma semana é convertida para 7 dias.

e dias, segundos e microssegundos são normalizados para que a representação seja única, com

• 0 <= microseconds < 1000000

• 0 <= seconds < 3600*24 (o número de segundos em um dia)

• -999999999 <= days <= 999999999

O exemplo a seguir ilustra como quaisquer argumentos além de dias, segundos e microssegundos são “mesclados” e normalizados nos três atributos resultantes:

>>> from datetime import timedelta
>>> delta = timedelta(
...     days=50,
...     seconds=27,
...     microseconds=10,
...     milliseconds=29000,
...     minutes=5,
...     hours=8,
...     weeks=2
... )
>>> # Only days, seconds, and microseconds remain
>>> delta
datetime.timedelta(days=64, seconds=29156, microseconds=10)

Se qualquer argumento for um ponto flutuante e houver microssegundos fracionários, os microssegundos fracionários restantes de todos os argumentos serão combinados e sua soma será arredondada para o microssegundo mais próximo usando o desempatador de metade da metade para o par. Se nenhum argumento é ponto flutuante, os processos de conversão e normalização são exatos (nenhuma informação é perdida).

Se o valor normalizado de dias estiver fora do intervalo indicado, OverflowError é gerado.

Observe que a normalização de valores negativos pode ser surpreendente a princípio. Por exemplo:

>>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)

Atributos de classe:

timedelta.min

O mais negativo objeto timedelta, timedelta(-999999999).

timedelta.max

O mais positivo objeto timedelta, timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999).

timedelta.resolution

A menor diferença possível entre objetos não iguais timedelta, timedelta(microseconds=1).

Note that, because of normalization, timedelta.max is greater than -timedelta.min. -timedelta.max is not representable as a timedelta object.

Atributos de instância (somente leitura):

Atributo	Valor
days	Entre -999999999 e 999999999 inclusive
seconds	Entre 0 e 86399 inclusive
microseconds	Entre 0 e 999999 inclusive

Operações suportadas:

Operação	Resultado
t1 = t2 + t3	Sum of t2 and t3. Afterwards t1 - t2 == t3 and t1 - t3 == t2 are true. (1)
t1 = t2 - t3	Difference of t2 and t3. Afterwards t1 == t2 - t3 and t2 == t1 + t3 are true. (1)(6)
t1 = t2 * i or t1 = i * t2	Delta multiplied by an integer. Afterwards t1 // i == t2 is true, provided i != 0.
	In general, t1  * i == t1 * (i-1) + t1 is true. (1)
t1 = t2 * f or t1 = f * t2	Delta multiplicado por um float, ponto flutuante. O resultado é arredondado para o múltiplo mais próximo de timedelta.resolution usando a metade da metade para o par.
f = t2 / t3	Division (3) of overall duration t2 by interval unit t3. Returns a float object.
t1 = t2 / f or t1 = t2 / i	Delta dividido por um float ou um int. O resultado é arredondado para o múltiplo mais próximo de timedelta.resolution usando a metade da metade para o par.
t1 = t2 // i or t1 = t2 // t3	O piso é calculado e o restante (se houver) é jogado fora. No segundo caso, um número inteiro é retornado. (3)
t1 = t2 % t3	O restante é calculado como um objeto timedelta. (3)
q, r = divmod(t1, t2)	Calcula o quociente e o restante: q = t1 // t2 (3) e r = t1% t2. q é um número inteiro e r é um objeto timedelta.
+t1	Retorna um objeto timedelta com o mesmo valor. (2)
-t1	Equivalent to timedelta(-t1.days, -t1.seconds*, -t1.microseconds), and to t1 * -1. (1)(4)
abs(t)	Equivalent to +t when t.days >= 0, and to -t when t.days < 0. (2)
str(t)	Retorna uma string no formato [D day[s], ][H]H:MM:SS[.UUUUUU], onde D é negativo para t negativo. (5)
repr(t)	Retorna uma representação em string do objeto timedelta como uma chamada do construtor com valores de atributos canônicos.

Notas:

1. Isso é exato, mas pode transbordar.

2. Isso é exato e não pode transbordar.

3. Division by zero raises ZeroDivisionError.

4. -timedelta.max is not representable as a timedelta object.

5. As representações de string de objetos timedelta são normalizadas de maneira semelhante à sua representação interna. Isso leva a resultados um tanto incomuns para timedeltas negativos. Por exemplo:

   >>> timedelta(hours=-5)
   datetime.timedelta(days=-1, seconds=68400)
   >>> print(_)
   -1 day, 19:00:00
   

6. A expressão t2 - t3 sempre será igual à expressão t2 + (-t3) exceto quando t3 for igual a timedelta.max; nesse caso, o primeiro produzirá um resultado enquanto o último transbordará.

Além das operações listadas acima, os objetos timedelta suportam certas adições e subtrações com os objetos date e datetime (veja abaixo).

Alterado na versão 3.2: A divisão pelo piso e a divisão verdadeira de um objeto timedelta por outro objeto timedelta agora são suportadas, assim como as operações restantes e a função divmod(). A verdadeira divisão e multiplicação de um objeto timedelta por um objeto float agora são suportadas.

Objetos timedelta dão suporte a comparações de igualdade e ordem.

Em contexto booleano, um objeto timedelta é considerado verdadeiro se, e somente se, não for igual a timedelta(0).

Métodos de instância:

timedelta.total_seconds()

Retorna o número total de segundos contidos na duração. Equivalente a td / timedelta(seconds=1). Para unidades de intervalo diferentes de segundos, use a forma de divisão diretamente (por exemplo td / timedelta(microseconds=1)).

Observe que, em intervalos de tempo muito grandes (mais de 270 anos na maioria das plataformas), esse método perde a precisão de microssegundos.

Novo na versão 3.2.

Exemplos de uso: timedelta

Um exemplo adicional de normalização:

>>> # Components of another_year add up to exactly 365 days
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)
>>> year == another_year
True
>>> year.total_seconds()
31536000.0

Exemplos de aritmética com timedelta:

>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> ten_years = 10 * year
>>> ten_years
datetime.timedelta(days=3650)
>>> ten_years.days // 365
10
>>> nine_years = ten_years - year
>>> nine_years
datetime.timedelta(days=3285)
>>> three_years = nine_years // 3
>>> three_years, three_years.days // 365
(datetime.timedelta(days=1095), 3)

Objetos date

O objeto date representa uma data (ano, mês e dia) em um calendário idealizado, o atual calendário Gregoriano estendido indefinidamente em ambas as direções.

1º de janeiro do ano 1 é chamado de dia número 1, 2º de janeiro do ano 1 é chamado de dia número 2, e assim por diante. [2]

class datetime.date(year, month, day)

Todos os argumentos são obrigatórios. Os argumentos devem ser números inteiros, nos seguintes intervalos:

• MINYEAR <= year <= MAXYEAR

• 1 <= month <= 12

• 1 <= day <= número de dias no mês e ano fornecidos

Se um argumento fora desses intervalos for fornecido, ValueError é levantado.

Outros construtores, todos os métodos de classe.

classmethod date.today()

Retorna a data local atual.

Isso é equivalente a date.fromtimestamp(time.time()).

classmethod date.fromtimestamp(timestamp)

Retorna a data local correspondente ao registro de data e hora do POSIX, como é retornado por time.time().

Isso pode levantar OverflowError, se o registro de data e hora estiver fora do intervalo de valores suportados pela função C localtime() da plataforma, e em caso de falha OSError em localtime(). É comum que isso seja restrito a anos de 1970 a 2038. Observe que, em sistemas não POSIX que incluem segundos bissextos na sua notação de registro de data e hora, os segundos bissextos são ignorados por fromtimestamp().

Alterado na versão 3.3: Levanta OverflowError ao invés de ValueError se o registro de data e hora estiver fora do intervalo de valores suportados pela plataforma C localtime() função. Levanta OSError ao invés de ValueError em falha de localtime() .

classmethod date.fromordinal(ordinal)

Retorna a data correspondente ao ordinal proléptico gregoriano, considerando que 1º de janeiro do ano 1 tem o ordinal 1.

ValueError é levantado, a menos que 1 <= ordinal <= date.max.toordinal(). Para qualquer data d, date.fromordinal(d.toordinal()) == d.

classmethod date.fromisoformat(date_string)

Retorna um date correspondendo a date_string dada em qualquer formato válido de ISO 8601, com as seguintes exceções:

1. Datas de precisão reduzida não são atualmente suportadas (YYYY-MM, YYYY).

2. Representações de data estendidas não são atualmente suportadas (±YYYYYY-MM-DD).

3. Atualmente, as datas ordinais não são suportadas (YYYY-OOO).

Exemplos:

>>> from datetime import date
>>> date.fromisoformat('2019-12-04')
datetime.date(2019, 12, 4)
>>> date.fromisoformat('20191204')
datetime.date(2019, 12, 4)
>>> date.fromisoformat('2021-W01-1')
datetime.date(2021, 1, 4)

Novo na versão 3.7.

Alterado na versão 3.11: Anteriormente, este método tinha suporte apenas ao formato YYYY-MM-DD.

classmethod date.fromisocalendar(year, week, day)

Retorna um objeto date correspondendo a data em calendário ISO especificada por year, week e day. Esta é o inverso da função date.isocalendar().

Novo na versão 3.8.

Atributos de classe:

date.min

A data representável mais antiga, date(MINYEAR, 1, 1).

date.max

A data representável mais tardia, date(MAXYEAR, 12, 31).

date.resolution

A menor diferença possível entre objetos date não iguais, timedelta(days=1).

Atributos de instância (somente leitura):

date.year

Entre MINYEAR e MAXYEAR incluindo extremos.

date.month

Entre 1 e 12 incluindo extremos.

date.day

Entre 1 e o número de dias no mês especificado do ano especificado.

Operações suportadas:

Operação	Resultado
date2 = date1 + timedelta	date2 will be timedelta.days days after date1. (1)
date2 = date1 - timedelta	Computes date2 such that date2 + timedelta == date1. (2)
timedelta = date1 - date2	(3)
date1 == date2 date1 != date2	Comparação de igualdade. (4)
date1 < date2 date1 > date2 date1 <= date2 date1 >= date2	Comparação de ordem. (5)

Notas:

1. date2 é movida para frente no tempo se timedelta.days > 0, ou para trás se timedelta.days < 0. Posteriormente date2 - date1 == timedelta.days. timedelta.seconds e timedelta.microseconds são ignorados. OverflowError é levantado se date2.year for menor que MINYEAR ou maior que MAXYEAR.

2. timedelta.seconds e timedelta.microseconds são ignoradas.

3. This is exact, and cannot overflow. timedelta.seconds and timedelta.microseconds are 0, and date2 + timedelta == date1 after.

4. Objetos date são iguais se representam a mesma data.

5. date1 é considerado menor que date2 quando date1 preceder date2 no tempo. Em outras palavras, date1 < date2 se e somente se date1.toordinal() < date2.toordinal().

Em contextos booleanos, todo objeto date é considerado verdadeiro.

Métodos de instância:

date.replace(year=self.year, month=self.month, day=self.day)

Retorna uma data com o mesmo valor, exceto por aqueles parâmetros que receberam novos valores, por quaisquer argumentos nomeados especificados.

Exemplo:

>>> from datetime import date
>>> d = date(2002, 12, 31)
>>> d.replace(day=26)
datetime.date(2002, 12, 26)

date.timetuple()

Retorna uma time.struct_time tal como retornado por time.localtime().

As horas, minutos e segundos são 0, e o sinalizador de horário de verão é -1.

d.timetuple() é equivalente a:

time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))

where yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 is the day number within the current year starting with 1 for January 1st.

date.toordinal()

Retorna o ordinal proléptico gregoriano da data, considerando que 1º de janeiro do ano 1 tem o ordinal 1. Para qualquer objeto date d, date.fromordinal(d.toordinal()) == d.

date.weekday()

Retorna o dia da semana como um inteiro, onde Segunda é 0 e Domingo é 6. Por exemplo, date(2002, 12, 4).weekday() == 2, uma Quarta-feira. Veja também isoweekday().

date.isoweekday()

Retorna o dia da semana como um inteiro, onde Segunda é 1 e Domingo é 7. Por exemplo, date(2002, 12, 4).isoweekday() == 3, uma Quarta-feira. Veja também weekday(), isocalendar().

date.isocalendar()

Retorna um objeto tupla nomeada com três componentes: year, week e weekday.

O calendário ISO é uma variação amplamente usada do calendário gregoriano. [3]

O ano ISO consiste de 52 ou 53 semanas completas, e onde uma semana começa na segunda-feira e termina no domingo. A primeira semana de um ano ISO é a primeira semana no calendário (Gregoriano) de um ano contendo uma quinta-feira. Isso é chamado de semana número 1, e o ano ISO dessa quinta-feira é o mesmo que o seu ano Gregoriano.

Por exemplo, 2004 começa em uma quinta-feira, então a primeira semana do ano ISO 2004 começa na segunda-feira, 29 de dezembro de 2003, e termina no domingo, 4 de janeiro de 2004:

>>> from datetime import date
>>> date(2003, 12, 29).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=1)
>>> date(2004, 1, 4).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=7)

Alterado na versão 3.9: Resultado alterado de uma tupla para uma tupla nomeada.

date.isoformat()

Retorna uma string representando a data no formato ISO 8601, YYYY-MM-DD:

>>> from datetime import date
>>> date(2002, 12, 4).isoformat()
'2002-12-04'

date.__str__()

Para uma data d, str(d) é equivalente a d.isoformat().

date.ctime()

Retorna uma string representando a data:

>>> from datetime import date
>>> date(2002, 12, 4).ctime()
'Wed Dec  4 00:00:00 2002'

d.ctime() é equivalente a:

time.ctime(time.mktime(d.timetuple()))

em plataformas em que a função C nativa ctime() (que é invocada pela função time.ctime(), mas não pelo método date.ctime()) se conforma com o padrão C.

date.strftime(format)

Retorna uma string representando a data, controlado por uma string explícita de formatação. Códigos de formatação referenciando horas, minutos ou segundos irão ver valores 0. Veja também strftime() and strptime() Behavior e date.isoformat().

date.__format__(format)

O mesmo que date.strftime(). Isso torna possível especificar uma string de formatação para o objeto date em literais de string formatados e ao usar str.format(). Veja também strftime() and strptime() Behavior e date.isoformat().

Exemplos de uso: date

Exemplo de contagem de dias para um evento:

>>> import time
>>> from datetime import date
>>> today = date.today()
>>> today
datetime.date(2007, 12, 5)
>>> today == date.fromtimestamp(time.time())
True
>>> my_birthday = date(today.year, 6, 24)
>>> if my_birthday < today:
...     my_birthday = my_birthday.replace(year=today.year + 1)
...
>>> my_birthday
datetime.date(2008, 6, 24)
>>> time_to_birthday = abs(my_birthday - today)
>>> time_to_birthday.days
202

Mais exemplos de uso da classe date:

>>> from datetime import date
>>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
>>> d
datetime.date(2002, 3, 11)

>>> # Methods related to formatting string output
>>> d.isoformat()
'2002-03-11'
>>> d.strftime("%d/%m/%y")
'11/03/02'
>>> d.strftime("%A %d. %B %Y")
'Monday 11. March 2002'
>>> d.ctime()
'Mon Mar 11 00:00:00 2002'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
'The day is 11, the month is March.'

>>> # Methods for to extracting 'components' under different calendars
>>> t = d.timetuple()
>>> for i in t:     
...     print(i)
2002                # year
3                   # month
11                  # day
0
0
0
0                   # weekday (0 = Monday)
70                  # 70th day in the year
-1
>>> ic = d.isocalendar()
>>> for i in ic:    
...     print(i)
2002                # ISO year
11                  # ISO week number
1                   # ISO day number ( 1 = Monday )

>>> # A date object is immutable; all operations produce a new object
>>> d.replace(year=2005)
datetime.date(2005, 3, 11)

Objetos datetime

Um objeto datetime é um único objeto contendo todas as informações de um objeto date e um objeto time.

Assim como um objeto date, datetime assume o atual calendário Gregoriano estendido em ambas as direções; assim como um objeto time, datetime assume que existem exatamente 3600*24 segundos em cada dia.

Construtor:

class datetime.datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

Os argumentos year, month e day são obrigatórios. tzinfo pode ser None, ou uma instância de subclasse de tzinfo. Os argumentos remanescentes devem ser inteiros nos seguintes intervalos:

• MINYEAR <= year <= MAXYEAR,

• 1 <= month <= 12,

• 1 <= day <= número de dias no mês e ano fornecidos,

• 0 <= hour < 24,

• 0 <= minute < 60,

• 0 <= second < 60,

• 0 <= microsecond < 1000000,

• fold in [0, 1].

Se um argumento fora desses intervalos for fornecido, ValueError é levantado.

Alterado na versão 3.6: Adicionado o parâmetro fold.

Outros construtores, todos os métodos de classe.

classmethod datetime.today()

Retorna o datetime local atual, com o atributo tzinfo setado para None.

Equivalente a:

datetime.fromtimestamp(time.time())

Veja também now(), fromtimestamp().

Este método é funcionalmente equivalente a now(), mas sem um parâmetro tz.

classmethod datetime.now(tz=None)

Retorna a data e hora local atual.

Se o argumento opcional tz é None ou não especificado, isto é o mesmo que today(), mas, se possível, fornece mais precisão do que pode ser obtido indo por um registro de data e hora da função time.time() (por exemplo, isto pode ser possível em plataformas que fornecem a função C gettimeofday()).

Se tz não for None, ele deve ser uma instância de uma subclasse de tzinfo, e a data e hora local atual são convertidas para o fuso horário de tz.

Esta função é preferida ao invés de today() e utcnow().

classmethod datetime.utcnow()

Retorna a data e hora atual em UTC, com tzinfo como None.

Este é similar a now(), mas retorna a data e hora atual em UTC, como um objeto datetime ingênuo. Um datetime UTC consciente pode ser obtido chamando datetime.now(timezone.utc). Veja também now().

Aviso

Devido ao fato de objetos datetime ingênuos serem tratados por muitos métodos datetime como hora local, é preferível usar datetimes conscientes para representar horas em UTC. De tal forma, a maneira recomendada para criar um objeto representando a hora local em UTC é chamando datetime.now(timezone.utc).

Obsoleto desde a versão 3.12: Use datetime.now() com UTC.

classmethod datetime.fromtimestamp(timestamp, tz=None)

Retorna a data e hora local correspondente ao registro de data e hora POSIX, como é retornado por time.time(). Se o argumento opcional tz é None ou não especificado, o registro de data e hora é convertido para a data e hora local da plataforma, e o objeto datetime retornado é ingênuo.

Se tz não for None, ela deve ser uma instância de uma subclasse de tzinfo, e o registro de data e hora é convertido para o fuso horário de tz.

fromtimestamp() pode levantar OverflowError, se o registro de data e hora estiver fora do intervalo de valores suportados pelas funções em C localtime() ou gmtime() da plataforma, e ocorrer uma falha de OSError em localtime() ou gmtime(). É comum para isso ser restrito aos anos 1970 até 2038. Perceba que em sistemas não-POSIX que incluem segundos bissextos na sua notação de registro de data e hora, segundos bissextos são ignorados por fromtimestamp(), e então é possível ter dois registros de data e hora com diferença de um segundo que apresentam objetos datetime idênticos. Este método é preferido sobre utcfromtimestamp().

Alterado na versão 3.3: Levanta um OverflowError ao invés de ValueError se o registro de data e hora estiver fora do intervalo dos valores suportados pelas funções C localtime() ou gmtime() da plataforma. Levanta OSError ao invés de ValueError em falhas de localtime() ou gmtime().

Alterado na versão 3.6: fromtimestamp() pode retornar instâncias com fold igual a 1.

classmethod datetime.utcfromtimestamp(timestamp)

Retorna o datetime UTC correspondente ao registro de data e hora POSIX, com tzinfo setado para None. (O objeto resultante é ingênuo.)

Isso pode levantar OverflowError, se o registro de data e hora estiver fora do intervalo de valores suportados pela função C gmtime() da plataforma, e em caso de falha OSError em gmtime(). É comum que isso seja restrito a anos de 1970 a 2038.

Para conseguir um objeto datetime consciente, chame fromtimestamp():

datetime.fromtimestamp(timestamp, timezone.utc)

Nas plataformas compatíveis com POSIX, é equivalente à seguinte expressão:

datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)

com a exceção de que a última fórmula sempre dá suporte ao intervalo completo de anos: entre MINYEAR e MAXYEAR inclusive.

Aviso

Devido ao fato de objetos datetime ingênuos serem tratados por muitos métodos datetime como hora local, é preferível usar datetimes conscientes para representar horas em UTC. De tal forma, a maneira recomendada para criar um objeto representando um registro de data e hora específico em UTC é chamando datetime.fromtimestamp(timestamp, tz=timezone.utc).

Alterado na versão 3.3: Levanta OverflowError ao invés de ValueError se o registro de data e hora estiver fora do intervalo de valores suportados pela função C gmtime() da plataforma. Levanta OSError ao invés de ValueError em caso de falha gmtime().

Obsoleto desde a versão 3.12: Use datetime.fromtimestamp() com UTC.

classmethod datetime.fromordinal(ordinal)

Retorna um datetime correspondente ao ordinal proléptico Gregoriano, onde 1º de janeiro do ano 1 tem ordinal 1. ValueError é levantado a não ser que 1 <= ordinal <= datetime.max.toordinal(). As horas, minutos, segundos e micro segundos do resultado são todos 0, e tzinfo é None.

classmethod datetime.combine(date, time, tzinfo=time.tzinfo)

Retorna um novo objeto datetime no qual os componentes de data são iguais ao objeto date fornecido, e nos quais os componentes de hora são iguais ao do objeto time fornecido. Se o argumento tzinfo é fornecido, seu valor é usado para definir o atributo tzinfo do resultado, caso contrário o atributo tzinfo do argumento time é usado. Se o argumento date é um objeto datetime, seus componentes de hora e atributos tzinfo são ignorados.

Para qualquer objeto datetime d, d == datetime.combine(d.date(), d.time(), d.tzinfo).

Alterado na versão 3.6: Adicionado o argumento tzinfo.

classmethod datetime.fromisoformat(date_string)

Retorna um datetime correspondendo a date_string em qualquer formato válido de ISO 8601, com as seguintes exceções:

1. Os deslocamentos de fuso horário podem ter segundos fracionários.

2. O separador T pode ser substituído por qualquer caractere unicode único.

3. Horas e minutos fracionários não são suportados.

4. Datas de precisão reduzida não são atualmente suportadas (YYYY-MM, YYYY).

5. Representações de data estendidas não são atualmente suportadas (±YYYYYY-MM-DD).

6. Atualmente, as datas ordinais não são suportadas (YYYY-OOO).

Exemplos:

>>> from datetime import datetime
>>> datetime.fromisoformat('2011-11-04')
datetime.datetime(2011, 11, 4, 0, 0)
>>> datetime.fromisoformat('20111104')
datetime.datetime(2011, 11, 4, 0, 0)
>>> datetime.fromisoformat('2011-11-04T00:05:23')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> datetime.fromisoformat('2011-11-04T00:05:23Z')
datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)
>>> datetime.fromisoformat('20111104T000523')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> datetime.fromisoformat('2011-W01-2T00:05:23.283')
datetime.datetime(2011, 1, 4, 0, 5, 23, 283000)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc)
>>> datetime.fromisoformat('2011-11-04T00:05:23+04:00')   
datetime.datetime(2011, 11, 4, 0, 5, 23,
    tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))

Novo na versão 3.7.

Alterado na versão 3.11: Anteriormente, este método suportava apenas formatos que podiam ser emitidos por date.isoformat() ou datetime.isoformat().

classmethod datetime.fromisocalendar(year, week, day)

Retorna um datetime correspondente à data no calendário ISO especificada por year, week e day. Os componentes não-data do datetime são preenchidos normalmente com seus valores padrões. Isso é o inverso da função datetime.isocalendar().

Novo na versão 3.8.

classmethod datetime.strptime(date_string, format)

Retorna um datetime correspondente ao date_string, analisado de acordo com format.

Se format não contiver microssegundos ou informações de fuso horário, isso é equivalente a:

datetime(*(time.strptime(date_string, format)[0:6]))

ValueError é levantado se o date_string e o format não puderem ser interpretados por time.strptime() ou se ele retorna um valor o qual não é uma tupla temporal. Veja também strftime() and strptime() Behavior e datetime.fromisoformat().

Atributos de classe:

datetime.min

O primeiro datetime representável, datetime(MINYEAR, 1, 1, tzinfo=None).

datetime.max

O último datetime representável, datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None).

datetime.resolution

A menor diferença possível entre objetos datetime diferentes, timedelta(microseconds=1).

Atributos de instância (somente leitura):

datetime.year

Entre MINYEAR e MAXYEAR incluindo extremos.

datetime.month

Entre 1 e 12 incluindo extremos.

datetime.day

Entre 1 e o número de dias no mês especificado do ano especificado.

datetime.hour

No intervalo range(24).

datetime.minute

No intervalo range(60).

datetime.second

No intervalo range(60).

datetime.microsecond

No intervalo range(1000000).

datetime.tzinfo

O objeto passado como o argumento tzinfo do construtor datetime, ou None se nada foi passado.

datetime.fold

In [0, 1]. Used to disambiguate wall times during a repeated interval. (A repeated interval occurs when clocks are rolled back at the end of daylight saving time or when the UTC offset for the current zone is decreased for political reasons.) The values 0 and 1 represent, respectively, the earlier and later of the two moments with the same wall time representation.

Novo na versão 3.6.

Operações suportadas:

Operação	Resultado
datetime2 = datetime1 + timedelta	(1)
datetime2 = datetime1 - timedelta	(2)
timedelta = datetime1 - datetime2	(3)
datetime1 == datetime2 datetime1 != datetime2	Comparação de igualdade. (4)
datetime1 < datetime2 datetime1 > datetime2 datetime1 <= datetime2 datetime1 >= datetime2	Comparação de ordem. (5)

1. datetime2 is a duration of timedelta removed from datetime1, moving forward in time if timedelta.days > 0, or backward if timedelta.days < 0. The result has the same tzinfo attribute as the input datetime, and datetime2 - datetime1 == timedelta after. OverflowError is raised if datetime2.year would be smaller than MINYEAR or larger than MAXYEAR. Note that no time zone adjustments are done even if the input is an aware object.

2. Computes the datetime2 such that datetime2 + timedelta == datetime1. As for addition, the result has the same tzinfo attribute as the input datetime, and no time zone adjustments are done even if the input is aware.

3. Subtração de um datetime de outro datetime é definido apenas se ambos os operandos são ingênuos, ou se ambos são conscientes. Se um deles é consciente e o outro é ingênuo, TypeError é levantado.

   Se ambos são ingênuos, ou ambos são conscientes e tem o mesmo atributo tzinfo, os atributos tzinfo são ignorados, e o resultado é um objeto t do tipo timedelta, tal que datetime2 + t == datetime1. Nenhum ajuste de fuso horário é feito neste caso.

   Se ambas são conscientes e têm atributos tzinfo diferentes, a-b age como se a e b foram primeiro convertidas para datetimes ingênuas em UTC. O resultado é (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset()) exceto que a a implementação nunca ultrapassa o limite.

4. Objetos datetime são iguais se representarem a mesma data e hora, levando em consideração o fuso horário.

   Objetos ingênuos e conscientes datetime nunca são iguais. Objetos datetime nunca são iguais a objetos date que também não são instâncias de datetime, mesmo que representem a mesma data.

   If both comparands are aware, and have the same tzinfo attribute, the tzinfo and fold attributes are ignored and the base datetimes are compared. If both comparands are aware and have different tzinfo attributes, the comparison acts as comparands were first converted to UTC datetimes except that the implementation never overflows. datetime instances in a repeated interval are never equal to datetime instances in other time zone.

5. datetime1 is considered less than datetime2 when datetime1 precedes datetime2 in time, taking into account the time zone.

   Order comparison between naive and aware datetime objects, as well as a datetime object and a date object that is not also a datetime instance, raises TypeError.

   If both comparands are aware, and have the same tzinfo attribute, the tzinfo and fold attributes are ignored and the base datetimes are compared. If both comparands are aware and have different tzinfo attributes, the comparison acts as comparands were first converted to UTC datetimes except that the implementation never overflows.

Alterado na versão 3.3: Comparações de igualdade entre instâncias de datetime conscientes e nativas não levantam TypeError.

Métodos de instância:

datetime.date()

Retorna um objeto date com o mesmo ano, mês e dia.

datetime.time()

Retorna um objeto time com a mesma hora, minuto, segundo, microssegundo e fold. O atributo tzinfo é None. Veja também o método timetz().

Alterado na versão 3.6: O valor fold é copiado para o objeto time retornado.

datetime.timetz()

Retorna um objeto time com os mesmos atributos de hora, minuto, segundo, microssegundo, fold e tzinfo. Veja também o método time().

Alterado na versão 3.6: O valor fold é copiado para o objeto time retornado.

datetime.replace(year=self.year, month=self.month, day=self.day, hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)

Retorna um datetime com os mesmos atributos, exceto para aqueles atributos que receberam novos valores por quaisquer argumentos nomeados que foram especificados. Perceba que tzinfo=None pode ser especificado para criar um datetime ingênuo a partir de um datetime consciente, sem conversão de dados da data ou hora.

Alterado na versão 3.6: Adicionado o parâmetro fold.

datetime.astimezone(tz=None)

Retorna um objeto datetime com novo atributo tzinfo definido por tz, ajustando a data e hora de forma que o resultado seja o mesmo horário UTC que self, mas na hora local de tz.

Se fornecido, tz deve ser uma instância de uma subclasse tzinfo, e seus métodos utcoffset() e dst() não devem retornar None. Se self for ingênuo, é presumido que ele representa o tempo no fuso horário do sistema.

Se for chamado sem argumentos (ou com tz=None) o fuso horário do sistema local é assumido como o fuso horário desejado. O atributo .tzinfo da instância datetime convertida será definido para uma instância de timezone com o nome da zona e um deslocamento obtido a partir do sistema operacional.

Se self.tzinfo for tz, self.astimezone(tz) é igual a self: nenhum ajuste nos dados de data ou hora é realizado. Caso contrário o resultado é a hora local no fuso horário tz, representando a mesma hora UTC que self: depois astz = dt.astimezone(tz), astz - astz.utcoffset() terá os mesmos dados de data e hora que dt - dt.utcoffset().

Se você quer meramente anexar um objeto de fuso horário tz a um datetime dt sem ajustes de dados de data e hora, use dt.replace(tzinfo=tz). Se você meramente quer remover o objeto de fuso horário de um datetime consciente dt sem conversão de dados de data e hora, use dt.replace(tzinfo=None).

Perceba que o método padrão tzinfo.fromutc() pode ser substituído em uma subclasse tzinfo para afetar o resultado retornado por astimezone(). Ignorando erros de letras maiúsculas/minúsculas, astimezone() funciona como:

def astimezone(self, tz):
    if self.tzinfo is tz:
        return self
    # Convert self to UTC, and attach the new time zone object.
    utc = (self - self.utcoffset()).replace(tzinfo=tz)
    # Convert from UTC to tz's local time.
    return tz.fromutc(utc)

Alterado na versão 3.3: tz agora pode ser omitido.

Alterado na versão 3.6: O método astimezone() agora pode ser chamado em instâncias ingênuas que presumidamente representam a hora local do sistema.

datetime.utcoffset()

Se tzinfo for None, retorna None, caso contrário retorna self.tzinfo.utcoffset(self), e levanta uma exceção se o segundo não retornar None ou um objeto timedelta com magnitude menor que um dia.

Alterado na versão 3.7: A diferença UTC não é restrita a um número completo de minutos.

datetime.dst()

Se tzinfo for None, retorna None, caso contrário retorna self.tzinfo.dst(self), e levanta uma exceção se o segundo não retornar None ou um objeto timedelta com magnitude menor que um dia.

Alterado na versão 3.7: A diferença de horário de verão não é restrita a um número completo de minutos.

datetime.tzname()

Se tzinfo for None, retorna None, caso contrário retorna self.tzinfo.tzname(self), levanta uma exceção se o segundo não retornar None ou um objeto string.

datetime.timetuple()

Retorna uma time.struct_time tal como retornado por time.localtime().

d.timetuple() é equivalente a:

time.struct_time((d.year, d.month, d.day,
                  d.hour, d.minute, d.second,
                  d.weekday(), yday, dst))

where yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 is the day number within the current year starting with 1 for January 1st. The tm_isdst flag of the result is set according to the dst() method: tzinfo is None or dst() returns None, tm_isdst is set to -1; else if dst() returns a non-zero value, tm_isdst is set to 1; else tm_isdst is set to 0.

datetime.utctimetuple()

If datetime instance d is naive, this is the same as d.timetuple() except that tm_isdst is forced to 0 regardless of what d.dst() returns. DST is never in effect for a UTC time.

If d is aware, d is normalized to UTC time, by subtracting d.utcoffset(), and a time.struct_time for the normalized time is returned. tm_isdst is forced to 0. Note that an OverflowError may be raised if d.year was MINYEAR or MAXYEAR and UTC adjustment spills over a year boundary.

Aviso

Por causa que objetos datetime ingênuos são tratados por muitos métodos datetime como hora local, é preferido usar datetimes conscientes para representar horários em UTC; como resultado, usar datetime.utctimetuple() pode dar resultados enganosos. Se você tem um datetime ingênuo representando UTC, use datetime.replace(tzinfo=timezone.utc) para torná-lo consciente, ponto no qual você pode usar datetime.timetuple().

datetime.toordinal()

Retorna o ordinal proléptico gregoriano da data. o mesmo que self.date().toordinal().

datetime.timestamp()

Retorna o registro de data e hora POSIX correspondente a instância datetime. O valor de retorno é um float similar aquele retornado por time.time().

Assume-se que instâncias datetime ingênuas representam a hora local e este método depende da função C mktime() da plataforma para realizar a conversão. Como datetime suporta um intervalo maior de valores que mktime() em muitas plataformas, este método pode levantar OverflowError ou OSError para horários longe no passado ou longe no futuro.

Para instâncias conscientes de datetime, o valor retornado é computado como:

(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()

Novo na versão 3.3.

Alterado na versão 3.6: O método timestamp() usa o atributo fold para desambiguar os tempos durante um intervalo repetido.

Nota

Não existe método para obter o timestamp POSIX diretamente de uma instância datetime ingênua representando tempo em UTC. Se a sua aplicação usa esta convenção e o fuso horário do seu sistema não está setado para UTC, você pode obter o registro de data e hora POSIX fornecendo tzinfo=timezone.utc:

timestamp = dt.replace(tzinfo=timezone.utc).timestamp()

ou calculando o registro de data e hora diretamente:

timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)

datetime.weekday()

Retorna o dia da semana como um inteiro, em que segunda-feira é 0 e domingo é 6. O mesmo que self.date().weekday(). Veja também isoweekday().

datetime.isoweekday()

Retorna o dia da semana como um inteiro, em que segunda-feira é 1 e domingo é 7. O mesmo que self.date().isoweekday(). Veja também weekday(), isocalendar().

datetime.isocalendar()

Retorna uma tupla nomeada com três componentes: year, week e weekday. O mesmo que self.date().isocalendar().

datetime.isoformat(sep='T', timespec='auto')

Retorna uma string representando a data e o tempo no formato ISO 8601:

• YYYY-MM-DDTHH:MM:SS.ffffff, se microsecond não é 0

• YYYY-MM-DDTHH:MM:SS, se microsecond é 0

Se utcoffset() não retorna None, uma string é adicionada com a diferença UTC:

• YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]], se microsecond não é 0

• YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]], se microsecond é 0

Exemplos:

>>> from datetime import datetime, timezone
>>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()
'2019-05-18T15:17:08.132263'
>>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat()
'2019-05-18T15:17:00+00:00'

O argumento opcional sep (por padrão, 'T') é um separador de caractere único, colocado entre as porções de data e tempo do resultado. Por exemplo:

>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     """A time zone with an arbitrary, constant -06:39 offset."""
...     def utcoffset(self, dt):
...         return timedelta(hours=-6, minutes=-39)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
>>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()
'2009-11-27T00:00:00.000100-06:39'

O argumento opcional timespec especifica o número de componentes adicionais do tempo a incluir (o padrão é 'auto'). Pode ser uma das seguintes strings:

• 'auto': O mesmo que 'seconds' se microsecond é 0, o mesmo que 'microseconds' caso contrário.

• 'hours': Inclui o atributo hour no formato de dois dígitos HH.

• 'minutes': Inclui os atributos hour e minute no formato HH:MM.

• 'seconds': Inclui os atributos hour, minute e second no formato HH:MM:SS.

• 'milliseconds': Inclui o tempo completo, mas trunca a parte fracional dos segundos em milissegundos. Formato HH:MM:SS.sss.

• 'microseconds': Inclui o tempo completo no formato HH:MM:SS.ffffff.

Nota

Componentes do tempo excluídos são truncados, não arredondados.

A exceção ValueError vai ser levantada no caso de um argumento timespec inválido:

>>> from datetime import datetime
>>> datetime.now().isoformat(timespec='minutes')   
'2002-12-25T00:00'
>>> dt = datetime(2015, 1, 1, 12, 30, 59, 0)
>>> dt.isoformat(timespec='microseconds')
'2015-01-01T12:30:59.000000'

Alterado na versão 3.6: Added the timespec parameter.

datetime.__str__()

Para uma instância datetime d, str(d) é equivalente a d.isoformat(' ').

datetime.ctime()

Retorna uma string representando a data e hora:

>>> from datetime import datetime
>>> datetime(2002, 12, 4, 20, 30, 40).ctime()
'Wed Dec  4 20:30:40 2002'

A string de saída não irá incluir informações de fuso horário, independente de a entrada ser consciente ou ingênua.

d.ctime() é equivalente a:

time.ctime(time.mktime(d.timetuple()))

em plataformas onde a função nativa em C ctime() (a qual time.ctime() invoca, mas a qual datetime.ctime() não invoca) conforma com o padrão C.

datetime.strftime(format)

Retorna uma string representando a data e hora, controladas por uma string com formato explícito. Veja também strftime() and strptime() Behavior e datetime.isoformat().

datetime.__format__(format)

O mesmo que datetime.strftime(). Isso torna possível especificar uma string de formatação para o objeto datetime em literais de string formatados e ao usar str.format(). Veja também strftime() and strptime() Behavior e datetime.isoformat().

Exemplos de uso: datetime

Examples of working with datetime objects:

>>> from datetime import datetime, date, time, timezone

>>> # Using datetime.combine()
>>> d = date(2005, 7, 14)
>>> t = time(12, 30)
>>> datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)

>>> # Using datetime.now()
>>> datetime.now()   
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
>>> datetime.now(timezone.utc)   
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)

>>> # Using datetime.strptime()
>>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> dt
datetime.datetime(2006, 11, 21, 16, 30)

>>> # Using datetime.timetuple() to get tuple of all attributes
>>> tt = dt.timetuple()
>>> for it in tt:   
...     print(it)
...
2006    # year
11      # month
21      # day
16      # hour
30      # minute
0       # second
1       # weekday (0 = Monday)
325     # number of days since 1st January
-1      # dst - method tzinfo.dst() returned None

>>> # Date in ISO format
>>> ic = dt.isocalendar()
>>> for it in ic:   
...     print(it)
...
2006    # ISO year
47      # ISO week
2       # ISO weekday

>>> # Formatting a datetime
>>> dt.strftime("%A, %d. %B %Y %I:%M%p")
'Tuesday, 21. November 2006 04:30PM'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'.format(dt, "day", "month", "time")
'The day is 21, the month is November, the time is 04:30PM.'

O exemplo abaixo define uma subclasse tzinfo capturando informações de fuso horário para Kabul, Afeganistão, o qual usou +4 UTC até 1945 e depois +4:30 UTC após esse período:

from datetime import timedelta, datetime, tzinfo, timezone

class KabulTz(tzinfo):
    # Kabul used +4 until 1945, when they moved to +4:30
    UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)

    def utcoffset(self, dt):
        if dt.year < 1945:
            return timedelta(hours=4)
        elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, 30):
            # An ambiguous ("imaginary") half-hour range representing
            # a 'fold' in time due to the shift from +4 to +4:30.
            # If dt falls in the imaginary range, use fold to decide how
            # to resolve. See PEP495.
            return timedelta(hours=4, minutes=(30 if dt.fold else 0))
        else:
            return timedelta(hours=4, minutes=30)

    def fromutc(self, dt):
        # Follow same validations as in datetime.tzinfo
        if not isinstance(dt, datetime):
            raise TypeError("fromutc() requires a datetime argument")
        if dt.tzinfo is not self:
            raise ValueError("dt.tzinfo is not self")

        # A custom implementation is required for fromutc as
        # the input to this function is a datetime with utc values
        # but with a tzinfo set to self.
        # See datetime.astimezone or fromtimestamp.
        if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE:
            return dt + timedelta(hours=4, minutes=30)
        else:
            return dt + timedelta(hours=4)

    def dst(self, dt):
        # Kabul does not observe daylight saving time.
        return timedelta(0)

    def tzname(self, dt):
        if dt >= self.UTC_MOVE_DATE:
            return "+04:30"
        return "+04"

Uso de KabulTz mostrado acima:

>>> tz1 = KabulTz()

>>> # Datetime before the change
>>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00

>>> # Datetime after the change
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00

>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(timezone.utc)
>>> dt3
datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)
>>> dt2
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())
>>> dt2 == dt3
True

Objetos time

A time object represents a (local) time of day, independent of any particular day, and subject to adjustment via a tzinfo object.

class datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

Todos os argumentos são opcionais. tzinfo pode ser None, ou uma instância de uma subclasse de tzinfo. Os argumentos remanescentes devem ser inteiros nos seguintes intervalos:

• 0 <= hour < 24,

• 0 <= minute < 60,

• 0 <= second < 60,

• 0 <= microsecond < 1000000,

• fold in [0, 1].

If an argument outside those ranges is given, ValueError is raised. All default to 0 except tzinfo, which defaults to None.

Atributos de classe:

time.min

O time mais cedo que pode ser representado, time(0, 0, 0, 0).

time.max

O time mais tardio que pode ser representado, time(23, 59, 59, 999999).

time.resolution

A menor diferença possível entre objetos time diferentes, timedelta(microseconds=1), embora perceba que aritmética sobre objetos time não é suportada.

Atributos de instância (somente leitura):

time.hour

No intervalo range(24).

time.minute

No intervalo range(60).

time.second

No intervalo range(60).

time.microsecond

No intervalo range(1000000).

time.tzinfo

O objeto passado como argumento tzinfo para o construtor da classe time, ou None se nada foi passado.

time.fold

In [0, 1]. Used to disambiguate wall times during a repeated interval. (A repeated interval occurs when clocks are rolled back at the end of daylight saving time or when the UTC offset for the current zone is decreased for political reasons.) The values 0 and 1 represent, respectively, the earlier and later of the two moments with the same wall time representation.

Novo na versão 3.6.

time objects support equality and order comparisons, where a is considered less than b when a precedes b in time.

Naive and aware time objects are never equal. Order comparison between naive and aware time objects raises TypeError.

If both comparands are aware, and have the same tzinfo attribute, the tzinfo and fold attributes are ignored and the base times are compared. If both comparands are aware and have different tzinfo attributes, the comparands are first adjusted by subtracting their UTC offsets (obtained from self.utcoffset()).

Alterado na versão 3.3: Equality comparisons between aware and naive time instances don’t raise TypeError.

Em contextos Booleanos, um objeto time é sempre considerado como verdadeiro.

Alterado na versão 3.5: Antes do Python 3.5, um objeto time era considerado falso se ele representava meia-noite em UTC. Este comportamento era considerado obscuro e suscetível a erros, e foi removido no Python 3.5. Veja bpo-13936 para todos os detalhes.

Outro construtor:

classmethod time.fromisoformat(time_string)

Retorna um time correspondendo a time_string em qualquer formato válido de ISO 8601, com as seguintes exceções:

1. Os deslocamentos de fuso horário podem ter segundos fracionários.

2. O T inicial, normalmente exigido nos casos em que pode haver ambiguidade entre uma data e uma hora, não é necessário.

3. Segundos fracionários podem ter qualquer número de dígitos (algo além de 6 será truncado).

4. Horas e minutos fracionários não são suportados.

Exemplos:

>>> from datetime import time
>>> time.fromisoformat('04:23:01')
datetime.time(4, 23, 1)
>>> time.fromisoformat('T04:23:01')
datetime.time(4, 23, 1)
>>> time.fromisoformat('T042301')
datetime.time(4, 23, 1)
>>> time.fromisoformat('04:23:01.000384')
datetime.time(4, 23, 1, 384)
>>> time.fromisoformat('04:23:01,000384')
datetime.time(4, 23, 1, 384)
>>> time.fromisoformat('04:23:01+04:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))
>>> time.fromisoformat('04:23:01Z')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
>>> time.fromisoformat('04:23:01+00:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)

Novo na versão 3.7.

Alterado na versão 3.11: Anteriormente, este método suportava apenas formatos que podiam ser emitidos por time.isoformat().

Métodos de instância:

time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)

Retorna um time com o mesmo valor, exceto para aqueles atributos que receberam novos valores através de quaisquer argumentos nomeados que foram especificados. Perceba que tzinfo=None pode ser especificado para criar um time ingênuo a partir de um time consciente, sem conversão de dados do horário.

Alterado na versão 3.6: Adicionado o parâmetro fold.

time.isoformat(timespec='auto')

Retorna uma string representando a hora em formato ISO 8601, um destes:

• HH:MM:SS.ffffff, se microsecond não é 0

• HH:MM:SS, se microsecond é 0

• HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]], se utcoffset() não retorna None

• HH:MM:SS+HH:MM[:SS[.ffffff]], se microsecond é 0 e utcoffset() não retorna None

O argumento opcional timespec especifica o número de componentes adicionais do tempo a incluir (o padrão é 'auto'). Pode ser uma das seguintes strings:

• 'auto': O mesmo que 'seconds' se microsecond é 0, o mesmo que 'microseconds' caso contrário.

• 'hours': Inclui o atributo hour no formato de dois dígitos HH.

• 'minutes': Inclui os atributos hour e minute no formato HH:MM.

• 'seconds': Inclui os atributos hour, minute e second no formato HH:MM:SS.

• 'milliseconds': Inclui o tempo completo, mas trunca a parte fracional dos segundos em milissegundos. Formato HH:MM:SS.sss.

• 'microseconds': Inclui o tempo completo no formato HH:MM:SS.ffffff.

Nota

Componentes do tempo excluídos são truncados, não arredondados.

ValueError será levantado com um argumento timespec inválido.

Exemplo:

>>> from datetime import time
>>> time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes')
'12:34'
>>> dt = time(hour=12, minute=34, second=56, microsecond=0)
>>> dt.isoformat(timespec='microseconds')
'12:34:56.000000'
>>> dt.isoformat(timespec='auto')
'12:34:56'

Alterado na versão 3.6: Added the timespec parameter.

time.__str__()

Para um tempo t, str(t) é equivalente a t.isoformat().

time.strftime(format)

Retorna uma string representando a hora, controladas por uma string com formato explícito. Veja também strftime() and strptime() Behavior e time.isoformat().

time.__format__(format)

O mesmo que time.strftime(). Isso torna possível especificar uma string de formatação para o objeto time em literais de string formatados e ao usar str.format(). Veja também strftime() and strptime() Behavior e time.isoformat().

time.utcoffset()

Se tzinfo for None, retorna None, caso contrário retorna self.tzinfo.utcoffset(None), e levanta uma exceção se o segundo não retornar None ou um objeto timedelta com magnitude menor que um dia.

Alterado na versão 3.7: A diferença UTC não é restrita a um número completo de minutos.

time.dst()

Se tzinfo for None, retorna None, caso contrário retorna self.tzinfo.dst(None), e levanta uma exceção se o segundo não retornar None, ou um objeto timedelta com magnitude menor que um dia.

Alterado na versão 3.7: A diferença de horário de verão não é restrita a um número completo de minutos.

time.tzname()

Se tzinfo for None, retorna None, caso contrário retorna self.tzinfo.tzname(None), ou levanta uma exceção se o último caso não retornar None ou um objeto string.

Exemplos de uso: time

Exemplos para trabalhar com um objeto time:

>>> from datetime import time, tzinfo, timedelta
>>> class TZ1(tzinfo):
...     def utcoffset(self, dt):
...         return timedelta(hours=1)
...     def dst(self, dt):
...         return timedelta(0)
...     def tzname(self,dt):
...         return "+01:00"
...     def  __repr__(self):
...         return f"{self.__class__.__name__}()"
...
>>> t = time(12, 10, 30, tzinfo=TZ1())
>>> t
datetime.time(12, 10, 30, tzinfo=TZ1())
>>> t.isoformat()
'12:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'+01:00'
>>> t.strftime("%H:%M:%S %Z")
'12:10:30 +01:00'
>>> 'The {} is {:%H:%M}.'.format("time", t)
'The time is 12:10.'

Objetos tzinfo

class datetime.tzinfo

Esta é uma classe base abstrata, o que significa que esta classe não deve ser instanciada diretamente. Defina uma subclasse de tzinfo para capturar informações sobre um fuso horário em particular.

Uma instância de (uma subclasse concreta de) tzinfo pode ser passada para os construtores de objetos datetime e time. Os objetos time veem seus atributos como se estivessem em horário local, e o objeto tzinfo suporta métodos revelando a diferença da hora local a partir de UTC, o nome do fuso horário, e diferença de horário em horário de verão, todos relativos ao objeto date ou time passado para eles.

You need to derive a concrete subclass, and (at least) supply implementations of the standard tzinfo methods needed by the datetime methods you use. The datetime module provides timezone, a simple concrete subclass of tzinfo which can represent timezones with fixed offset from UTC such as UTC itself or North American EST and EDT.

Special requirement for pickling: A tzinfo subclass must have an __init__() method that can be called with no arguments, otherwise it can be pickled but possibly not unpickled again. This is a technical requirement that may be relaxed in the future.

A concrete subclass of tzinfo may need to implement the following methods. Exactly which methods are needed depends on the uses made of aware datetime objects. If in doubt, simply implement all of them.

tzinfo.utcoffset(dt)

Retorna a diferença da hora local a partir do UTC, como um objeto timedelta, que é positivo a leste do UTC. Se a hora local está a oeste do UTC, isto deve ser negativo.

Isto representa a diferença total a partir de UTC; por exemplo, se um objeto tzinfo representa fuso horário e ajustes de horário de verão, utcoffset() deve retornar a soma deles. Se a diferença UTC não é conhecida, retorna None. Caso contrário o valor retornado deve ser um objeto timedelta estritamente contido entre -timedelta(hours=24) e timedelta(hours=24) (a magnitude da diferença deve ser menor que um dia). A maior parte das implementações de utcoffset() irá provavelmente parecer com um destes dois:

return CONSTANT                 # fixed-offset class
return CONSTANT + self.dst(dt)  # daylight-aware class

Se utcoffset() não retorna None, dst() também não deve retornar None.

A implementação padrão de utcoffset() levanta NotImplementedError.

Alterado na versão 3.7: A diferença UTC não é restrita a um número completo de minutos.

tzinfo.dst(dt)

Retorna o ajuste para o horário de verão (DST - daylight saving time), como um objeto timedelta ou None se informação para o horário de verão é desconhecida.

Return timedelta(0) if DST is not in effect. If DST is in effect, return the offset as a timedelta object (see utcoffset() for details). Note that DST offset, if applicable, has already been added to the UTC offset returned by utcoffset(), so there’s no need to consult dst() unless you’re interested in obtaining DST info separately. For example, datetime.timetuple() calls its tzinfo attribute’s dst() method to determine how the tm_isdst flag should be set, and tzinfo.fromutc() calls dst() to account for DST changes when crossing time zones.

Uma instância tz de uma subclasse tzinfo que modela tanto horário padrão quanto horário de verão deve ser consistente neste sentido:

tz.utcoffset(dt) - tz.dst(dt)

must return the same result for every datetime dt with dt.tzinfo == tz. For sane tzinfo subclasses, this expression yields the time zone’s “standard offset”, which should not depend on the date or the time, but only on geographic location. The implementation of datetime.astimezone() relies on this, but cannot detect violations; it’s the programmer’s responsibility to ensure it. If a tzinfo subclass cannot guarantee this, it may be able to override the default implementation of tzinfo.fromutc() to work correctly with astimezone() regardless.

Maior parte das implementações de dst() provavelmente irá parecer com um destes dois:

def dst(self, dt):
    # a fixed-offset class:  doesn't account for DST
    return timedelta(0)

or:

def dst(self, dt):
    # Code to set dston and dstoff to the time zone's DST
    # transition times based on the input dt.year, and expressed
    # in standard local time.

    if dston <= dt.replace(tzinfo=None) < dstoff:
        return timedelta(hours=1)
    else:
        return timedelta(0)

A implementação padrão de dst() levanta NotImplementedError.

Alterado na versão 3.7: A diferença de horário de verão não é restrita a um número completo de minutos.

tzinfo.tzname(dt)

Return the time zone name corresponding to the datetime object dt, as a string. Nothing about string names is defined by the datetime module, and there’s no requirement that it mean anything in particular. For example, "GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" are all valid replies. Return None if a string name isn’t known. Note that this is a method rather than a fixed string primarily because some tzinfo subclasses will wish to return different names depending on the specific value of dt passed, especially if the tzinfo class is accounting for daylight time.

A implementação padrão de tzname() levanta NotImplementedError.

Estes métodos são chamados por um objeto datetime ou time, em resposta aos seus métodos de mesmo nome. Um objeto datetime passa a si mesmo como argumento, e um objeto time passa None como o argumento. Os métodos de uma subclasse tzinfo devem portanto estar preparados para aceitar um argumento dt com valor None, ou uma classe datetime.

Quando None é passado, cabe ao projetista da classe decidir a melhor resposta. Por exemplo, retornar None é apropriado se a classe deseja dizer que objetos time não participam nos protocolos da classe tzinfo. Pode ser mais útil para utcoffset(None) retornar a diferença UTC padrão, como não existe outra convenção para descobrir a diferença padrão.

Quando um objeto datetime é passado na resposta ao método datetime, dt.tzinfo é o mesmo objeto que self. tzinfo e os métodos podem depender disso, a não ser que o código do usuário chame métodos tzinfo diretamente. A intenção é que os métodos tzinfo interpretem dt como estando em hora local, e não precisem se preocupar com objetos em outros fusos horários.

Exste mais um método tzinfo que uma subclasse pode querer substituir:

tzinfo.fromutc(dt)

Chamado a partir da implementação padrão datetime.astimezone(). Quando chamado a partir dela, dt.tzinfo é self, e os dados de data e hora de dt devem ser vistos como se expressassem um horário UTC. O propósito de fromutc() é ajustar os dados de data e hora, retornando um datetime equivalente na hora local de self.

Most tzinfo subclasses should be able to inherit the default fromutc() implementation without problems. It’s strong enough to handle fixed-offset time zones, and time zones accounting for both standard and daylight time, and the latter even if the DST transition times differ in different years. An example of a time zone the default fromutc() implementation may not handle correctly in all cases is one where the standard offset (from UTC) depends on the specific date and time passed, which can happen for political reasons. The default implementations of astimezone() and fromutc() may not produce the result you want if the result is one of the hours straddling the moment the standard offset changes.

Ignorando o código para casos de erros, a implementação padrão fromutc() funciona como:

def fromutc(self, dt):
    # raise ValueError error if dt.tzinfo is not self
    dtoff = dt.utcoffset()
    dtdst = dt.dst()
    # raise ValueError if dtoff is None or dtdst is None
    delta = dtoff - dtdst  # this is self's standard offset
    if delta:
        dt += delta   # convert to standard local time
        dtdst = dt.dst()
        # raise ValueError if dtdst is None
    if dtdst:
        return dt + dtdst
    else:
        return dt

No seguinte arquivo tzinfo_examples.py existem alguns exemplos de classes tzinfo:

from datetime import tzinfo, timedelta, datetime

ZERO = timedelta(0)
HOUR = timedelta(hours=1)
SECOND = timedelta(seconds=1)

# A class capturing the platform's idea of local time.
# (May result in wrong values on historical times in
#  timezones where UTC offset and/or the DST rules had
#  changed in the past.)
import time as _time

STDOFFSET = timedelta(seconds = -_time.timezone)
if _time.daylight:
    DSTOFFSET = timedelta(seconds = -_time.altzone)
else:
    DSTOFFSET = STDOFFSET

DSTDIFF = DSTOFFSET - STDOFFSET

class LocalTimezone(tzinfo):

    def fromutc(self, dt):
        assert dt.tzinfo is self
        stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND
        args = _time.localtime(stamp)[:6]
        dst_diff = DSTDIFF // SECOND
        # Detect fold
        fold = (args == _time.localtime(stamp - dst_diff))
        return datetime(*args, microsecond=dt.microsecond,
                        tzinfo=self, fold=fold)

    def utcoffset(self, dt):
        if self._isdst(dt):
            return DSTOFFSET
        else:
            return STDOFFSET

    def dst(self, dt):
        if self._isdst(dt):
            return DSTDIFF
        else:
            return ZERO

    def tzname(self, dt):
        return _time.tzname[self._isdst(dt)]

    def _isdst(self, dt):
        tt = (dt.year, dt.month, dt.day,
              dt.hour, dt.minute, dt.second,
              dt.weekday(), 0, 0)
        stamp = _time.mktime(tt)
        tt = _time.localtime(stamp)
        return tt.tm_isdst > 0

Local = LocalTimezone()


# A complete implementation of current DST rules for major US time zones.

def first_sunday_on_or_after(dt):
    days_to_go = 6 - dt.weekday()
    if days_to_go:
        dt += timedelta(days_to_go)
    return dt


# US DST Rules
#
# This is a simplified (i.e., wrong for a few cases) set of rules for US
# DST start and end times. For a complete and up-to-date set of DST rules
# and timezone definitions, visit the Olson Database (or try pytz):
# http://www.twinsun.com/tz/tz-link.htm
# https://sourceforge.net/projects/pytz/ (might not be up-to-date)
#
# In the US, since 2007, DST starts at 2am (standard time) on the second
# Sunday in March, which is the first Sunday on or after Mar 8.
DSTSTART_2007 = datetime(1, 3, 8, 2)
# and ends at 2am (DST time) on the first Sunday of Nov.
DSTEND_2007 = datetime(1, 11, 1, 2)
# From 1987 to 2006, DST used to start at 2am (standard time) on the first
# Sunday in April and to end at 2am (DST time) on the last
# Sunday of October, which is the first Sunday on or after Oct 25.
DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
DSTEND_1987_2006 = datetime(1, 10, 25, 2)
# From 1967 to 1986, DST used to start at 2am (standard time) on the last
# Sunday in April (the one on or after April 24) and to end at 2am (DST time)
# on the last Sunday of October, which is the first Sunday
# on or after Oct 25.
DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
DSTEND_1967_1986 = DSTEND_1987_2006

def us_dst_range(year):
    # Find start and end times for US DST. For years before 1967, return
    # start = end for no DST.
    if 2006 < year:
        dststart, dstend = DSTSTART_2007, DSTEND_2007
    elif 1986 < year < 2007:
        dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006
    elif 1966 < year < 1987:
        dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
    else:
        return (datetime(year, 1, 1), ) * 2

    start = first_sunday_on_or_after(dststart.replace(year=year))
    end = first_sunday_on_or_after(dstend.replace(year=year))
    return start, end


class USTimeZone(tzinfo):

    def __init__(self, hours, reprname, stdname, dstname):
        self.stdoffset = timedelta(hours=hours)
        self.reprname = reprname
        self.stdname = stdname
        self.dstname = dstname

    def __repr__(self):
        return self.reprname

    def tzname(self, dt):
        if self.dst(dt):
            return self.dstname
        else:
            return self.stdname

    def utcoffset(self, dt):
        return self.stdoffset + self.dst(dt)

    def dst(self, dt):
        if dt is None or dt.tzinfo is None:
            # An exception may be sensible here, in one or both cases.
            # It depends on how you want to treat them.  The default
            # fromutc() implementation (called by the default astimezone()
            # implementation) passes a datetime with dt.tzinfo is self.
            return ZERO
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        # Can't compare naive to aware objects, so strip the timezone from
        # dt first.
        dt = dt.replace(tzinfo=None)
        if start + HOUR <= dt < end - HOUR:
            # DST is in effect.
            return HOUR
        if end - HOUR <= dt < end:
            # Fold (an ambiguous hour): use dt.fold to disambiguate.
            return ZERO if dt.fold else HOUR
        if start <= dt < start + HOUR:
            # Gap (a non-existent hour): reverse the fold rule.
            return HOUR if dt.fold else ZERO
        # DST is off.
        return ZERO

    def fromutc(self, dt):
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        start = start.replace(tzinfo=self)
        end = end.replace(tzinfo=self)
        std_time = dt + self.stdoffset
        dst_time = std_time + HOUR
        if end <= dst_time < end + HOUR:
            # Repeated hour
            return std_time.replace(fold=1)
        if std_time < start or dst_time >= end:
            # Standard time
            return std_time
        if start <= std_time < end - HOUR:
            # Daylight saving time
            return dst_time


Eastern  = USTimeZone(-5, "Eastern",  "EST", "EDT")
Central  = USTimeZone(-6, "Central",  "CST", "CDT")
Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
Pacific  = USTimeZone(-8, "Pacific",  "PST", "PDT")

Perceba que existem sutilezas inevitáveis duas vezes por ano em uma subclasse tzinfo contabilizando tanto hora normal e horário de verão, nos pontos de transição do horário de verão. Para concretude, considere a costa leste dos EUA (UTC -0500), onde o horário de verão EDT começa no minuto após 1:59 (EST, hora padrão) no segundo domingo de Março, e termina no minuto posterior a 1:59 (EDT, horário de verão) no primeiro domingo de Novembro:

  UTC   3:MM  4:MM  5:MM  6:MM  7:MM  8:MM
  EST  22:MM 23:MM  0:MM  1:MM  2:MM  3:MM
  EDT  23:MM  0:MM  1:MM  2:MM  3:MM  4:MM

start  22:MM 23:MM  0:MM  1:MM  3:MM  4:MM

  end  23:MM  0:MM  1:MM  1:MM  2:MM  3:MM

Quando o horário de verão inicia (a linha de “início”), o relógio de parede local salta de 1:59 para 3:00. Um horário de parede da forma 2:MM realmente não faz sentido nesse dia, então astimezone(Eastern) não irá entregar um resultado com hour == 2 no dia que o horário de verão começar. Por exemplo, na primavera de transição para frente em 2016, nós tivemos:

>>> from datetime import datetime, timezone
>>> from tzinfo_examples import HOUR, Eastern
>>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname())
...
05:00:00 UTC = 00:00:00 EST
06:00:00 UTC = 01:00:00 EST
07:00:00 UTC = 03:00:00 EDT
08:00:00 UTC = 04:00:00 EDT

When DST ends (the “end” line), there’s a potentially worse problem: there’s an hour that can’t be spelled unambiguously in local wall time: the last hour of daylight time. In Eastern, that’s times of the form 5:MM UTC on the day daylight time ends. The local wall clock leaps from 1:59 (daylight time) back to 1:00 (standard time) again. Local times of the form 1:MM are ambiguous. astimezone() mimics the local clock’s behavior by mapping two adjacent UTC hours into the same local hour then. In the Eastern example, UTC times of the form 5:MM and 6:MM both map to 1:MM when converted to Eastern, but earlier times have the fold attribute set to 0 and the later times have it set to 1. For example, at the Fall back transition of 2016, we get:

>>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)
...
04:00:00 UTC = 00:00:00 EDT 0
05:00:00 UTC = 01:00:00 EDT 0
06:00:00 UTC = 01:00:00 EST 1
07:00:00 UTC = 02:00:00 EST 0

Note that the datetime instances that differ only by the value of the fold attribute are considered equal in comparisons.

Applications that can’t bear wall-time ambiguities should explicitly check the value of the fold attribute or avoid using hybrid tzinfo subclasses; there are no ambiguities when using timezone, or any other fixed-offset tzinfo subclass (such as a class representing only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).

Ver também

zoneinfo

The datetime module has a basic timezone class (for handling arbitrary fixed offsets from UTC) and its timezone.utc attribute (a UTC timezone instance).

zoneinfo traz a base de dados de fusos horários IANA (também conhecida como a base de dados Olson) para o Python, e sua utilização é recomendada.

Base de dados de fusos horários IANA

O banco de dados de fuso horário (comumente chamado de tz, tzdata ou zoneinfo) contém código e dados que representam o histórico de hora local para muitas localizações representativas ao redor do globo. Ele é atualizado periodicamente para refletir mudanças feitas por corpos políticos para limites de fuso horário, diferenças UTC, e regras de horário de verão.

Objetos timezone

A classe timezone é uma subclasse de tzinfo, as instâncias de cada uma representam um fuso horário definido por uma diferença temporária fixa do UTC.

Objetos dessa classe não podem ser usados para representar informações de fuso horário nas localizações onde variadas diferenças de fuso horário são utilizadas em diferentes dias do ano, ou onde mudanças históricas foram feitas ao tempo civil.

class datetime.timezone(offset, name=None)

O argumento offset deve ser especificado como um objeto timedelta representando a diferença entre o tempo local e o UTC. Ele deve estar estritamente entre -timedelta(hours=24) e timedelta(hous=24), caso contrário a exceção ValueError será provocada.

O argumento name é opcional. Se especificado, deve ser uma string que será usada como o valor retornado pelo método datetime.tzname().

Novo na versão 3.2.

Alterado na versão 3.7: A diferença UTC não é restrita a um número completo de minutos.

timezone.utcoffset(dt)

Retorna o valor fixo especificado quando a instância timezone é construída.

O argumento dt é ignorado. O valor de retorno é uma instância timedelta equivalente à diferença entre o tempo local e o UTC.

Alterado na versão 3.7: A diferença UTC não é restrita a um número completo de minutos.

timezone.tzname(dt)

Retorna o valor fixo especificado quando a instância timezone é construída.

Se name não é passado ao construtor, o nome retornado por tzname(dt) é gerado a partir do valor de offset do seguinte modo: Se offset é timedelta(0), o nome é “UTC”, caso contrário é uma string no formato UTC±HH:MM, na qual ± é o sinal do offset, HH e MM são dois dígitos de offset.hours e offset.minutes respectivamente.

Alterado na versão 3.6: Nome gerado de offset=timedelta(0) é agora simplesmente 'UTC', não 'UTC+00:00'.

timezone.dst(dt)

Sempre retorna None.

timezone.fromutc(dt)

Retorna dt + offset. O argumento dt deve ser uma instância datetime consciente, com tzinfo definida para self.

Atributos de classe:

timezone.utc

O fuso horário UTC, timezone(timedelta(0)).

strftime() and strptime() Behavior

Todos os objetos date, datetime e time dão suporte ao método strftime(format), para criar uma string representando o tempo sob o controle de uma string de formatação explícita.

Em recíproca, o método de classe datetime.strptime() cria um objeto datetime a partir de uma string representando a data e a hora e uma string de formatação correspondente.

The table below provides a high-level comparison of strftime() versus strptime():

	strftime	strptime
Uso	Converte objeto para uma string conforme um formato fornecido	Interpreta uma string como um objeto datetime dado um formato correspondente
Tipo de método	Método de instância	Método de classe
Método de	date; datetime; time	datetime
Assinatura	strftime(format)	strptime(date_string, format)

strftime() and strptime() Format Codes

Esses métodos aceitam códigos de formato que podem ser usados para analisar e formatar datas:

>>> datetime.strptime('31/01/22 23:59:59.999999',
...                   '%d/%m/%y %H:%M:%S.%f')
datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)
>>> _.strftime('%a %d %b %Y, %I:%M%p')
'Mon 31 Jan 2022, 11:59PM'

A seguir é exibida uma lista de todos os códigos de formatação que o padrão C de 1989 requer, e eles funcionam em todas as plataformas com implementação padrão C.

Diretiva	Significado	Exemplo	Notas
%a	Dias da semana como nomes abreviados da localidade.	Sun, Mon, …, Sat (en_US); So, Mo, …, Sa (de_DE)	(1)
%A	Dia da semana como nome completo da localidade.	Sunday, Monday, …, Saturday (en_US); Sonntag, Montag, …, Samstag (de_DE)	(1)
%w	Dia da semana como um número decimal, onde 0 é domingo e 6 é sábado.	0, 1, …, 6
%d	Dia do mês como um número decimal com zeros a esquerda.	01, 02, …, 31	(9)
%b	Mês como nome da localidade abreviado.	Jan, Feb, …, Dec (en_US); Jan, Feb, …, Dez (de_DE)	(1)
%B	Mês como nome completo da localidade.	January, February, …, December (en_US); janeiro, fevereiro, …, dezembro (pt_BR)	(1)
%m	Mês como um número decimal com zeros a esquerda.	01, 02, …, 12	(9)
%y	Ano sem século como um número decimal com zeros a esquerda.	00, 01, …, 99	(9)
%Y	Ano com século como um número decimal.	0001, 0002, …, 2013, 2014, …, 9998, 9999	(2)
%H	Hora (relógio de 24 horas) como um número decimal com zeros a esquerda.	00, 01, …, 23	(9)
%I	Hora (relógio de 12 horas) como um número decimal com zeros a esquerda.	01, 02, …, 12	(9)
%p	Equivalente da localidade a AM ou PM.	AM, PM (en_US); am, pm (de_DE)	(1), (3)
%M	Minutos como um número decimal, com zeros a esquerda.	00, 01, …, 59	(9)
%S	Segundos como um número decimal, com zeros a esquerda.	00, 01, …, 59	(4), (9)
%f	Microssegundos como um número decimal, com zeros à esquerda até completar 6 dígitos.	000000, 000001, …, 999999	(5)
%z	Diferença UTC no formato ±HHMM[SS[.ffffff]] (string vazia se o objeto é ingênuo).	(vazio), +0000, -0400, +1030, +063415, -030712.345216	(6)
%Z	Nome do fuso horário (string vazia se o objeto é ingênuo).	(vazio), UTC, GMT	(6)
%j	Dia do ano como um número decimal, com zeros a esquerda.	001, 002, …, 366	(9)
%U	Número da semana do ano (Domingo como o primeiro dia da semana) como um número decimal, com zeros a esquerda. Todos os dias em um ano novo precedendo o primeiro domingo são considerados como estando na semana 0.	00, 01, …, 53	(7), (9)
%W	Número da semana do ano (Segunda-feira como o primeiro dia da semana) como um número decimal, com zeros a esquerda. Todos os dias em um ano novo precedendo a primeira segunda-feira são considerados como estando na semana 0.	00, 01, …, 53	(7), (9)
%c	Representação de data e hora apropriada da localidade.	Tue Aug 16 21:30:00 1988 (en_US); Di 16 Aug 21:30:00 1988 (de_DE)	(1)
%x	Representação de data apropriada de localidade.	08/16/88 (None); 08/16/1988 (en_US); 16.08.1988 (de_DE)	(1)
%X	Representação de hora apropriada da localidade.	21:30:00 (en_US); 21:30:00 (de_DE)	(1)
%%	Um caractere literal '%'.	%

Diversas diretivas adicionais não necessárias pelo padrão C89 são incluídas para conveniência. Estes parâmetros todos correspondem a valores de datas na ISO 8601.

Diretiva	Significado	Exemplo	Notas
%G	Ano ISO 8601 com o século representando o ano que a maior parte da semana ISO (%V).	0001, 0002, …, 2013, 2014, …, 9998, 9999	(8)
%u	Dia de semana ISO 8601 como um número decimal onde 1 é segunda-feira.	1, 2, …, 7
%V	Semana ISO 8601 como um número decimal, com segunda-feira como o primeiro dia da semana. A semana 01 é a semana contendo o dia 4 de Janeiro.	01, 02, …, 53	(8), (9)
%:z	Diferença UTC no formato ±HH:MM[:SS[.ffffff]] (string vazia se o objeto é ingênuo).	(vazio), +00:00, -04:00, +10:30, +06:34:15, -03:07:12.345216	(6)

These may not be available on all platforms when used with the strftime() method. The ISO 8601 year and ISO 8601 week directives are not interchangeable with the year and week number directives above. Calling strptime() with incomplete or ambiguous ISO 8601 directives will raise a ValueError.

The full set of format codes supported varies across platforms, because Python calls the platform C library’s strftime() function, and platform variations are common. To see the full set of format codes supported on your platform, consult the strftime(3) documentation. There are also differences between platforms in handling of unsupported format specifiers.

Novo na versão 3.6: %G, %u e %V foram adicionados.

Novo na versão 3.12: %:z foi adicionado.

Detalhes técnicos

Broadly speaking, d.strftime(fmt) acts like the time module’s time.strftime(fmt, d.timetuple()) although not all objects support a timetuple() method.

For the datetime.strptime() class method, the default value is 1900-01-01T00:00:00.000: any components not specified in the format string will be pulled from the default value. [4]

Usar datetime.strptime(date_string, format) é equivalente a:

datetime(*(time.strptime(date_string, format)[0:6]))

exceto quando a formatação inclui componentes menores que 1 segundo, ou informações de diferenças de fuso horário, as quais são suportadas em datetime.strptime, mas são descartadas por time.strptime.

For time objects, the format codes for year, month, and day should not be used, as time objects have no such values. If they’re used anyway, 1900 is substituted for the year, and 1 for the month and day.

For date objects, the format codes for hours, minutes, seconds, and microseconds should not be used, as date objects have no such values. If they’re used anyway, 0 is substituted for them.

Pela mesma razão, o tratamento de formatação de strings contendo pontos de código Unicode que não podem ser representados no conjunto de caracteres da localidade atual também é dependente da plataforma. Em algumas plataformas, tais pontos de código são preservados intactos na saída, enquanto em outros strftime pode levantar UnicodeError ou retornar uma string vazia ao invés.

Notas:

1. Como o formato depende da localidade atual, deve-se tomar cuidado ao fazer suposições sobre o valor de saída. A ordenação dos campos irá variar (por exemplo, “mês/dia/ano” versus “dia/mês/ano”) e a saída pode conter caracteres não ASCII.

2. The strptime() method can parse years in the full [1, 9999] range, but years < 1000 must be zero-filled to 4-digit width.

   Alterado na versão 3.2: In previous versions, strftime() method was restricted to years >= 1900.

   Alterado na versão 3.3: In version 3.2, strftime() method was restricted to years >= 1000.

3. When used with the strptime() method, the %p directive only affects the output hour field if the %I directive is used to parse the hour.

4. Unlike the time module, the datetime module does not support leap seconds.

5. When used with the strptime() method, the %f directive accepts from one to six digits and zero pads on the right. %f is an extension to the set of format characters in the C standard (but implemented separately in datetime objects, and therefore always available).

6. Para um objeto ingênuo, os códigos de formatação %z, %:z e %Z são substituídos por strings vazias.

   Para um objeto consciente:

   %z

   utcoffset() is transformed into a string of the form ±HHMM[SS[.ffffff]], where HH is a 2-digit string giving the number of UTC offset hours, MM is a 2-digit string giving the number of UTC offset minutes, SS is a 2-digit string giving the number of UTC offset seconds and ffffff is a 6-digit string giving the number of UTC offset microseconds. The ffffff part is omitted when the offset is a whole number of seconds and both the ffffff and the SS part is omitted when the offset is a whole number of minutes. For example, if utcoffset() returns timedelta(hours=-3, minutes=-30), %z is replaced with the string '-0330'.

   Alterado na versão 3.7: A diferença UTC não é restrita a um número completo de minutos.

   Alterado na versão 3.7: When the %z directive is provided to the strptime() method, the UTC offsets can have a colon as a separator between hours, minutes and seconds. For example, '+01:00:00' will be parsed as an offset of one hour. In addition, providing 'Z' is identical to '+00:00'.

   %:z

   Comporta-se exatamente como %z, mas possui um separador de dois pontos adicionado entre horas, minutos e segundos.

   %Z

   In strftime(), %Z is replaced by an empty string if tzname() returns None; otherwise %Z is replaced by the returned value, which must be a string.

   strptime() only accepts certain values for %Z:

   1. qualquer valor em time.tzname para a localidade da sua máquina

   2. os valores codificados UTC e GMT

   Então alguém vivendo no Japão pode ter JST, UTC, e GMT como valores válidos, mas provavelmente não EST. Isso levantará ValueError para valores inválidos.

   Alterado na versão 3.2: When the %z directive is provided to the strptime() method, an aware datetime object will be produced. The tzinfo of the result will be set to a timezone instance.

7. When used with the strptime() method, %U and %W are only used in calculations when the day of the week and the calendar year (%Y) are specified.

8. Similar to %U and %W, %V is only used in calculations when the day of the week and the ISO year (%G) are specified in a strptime() format string. Also note that %G and %Y are not interchangeable.

9. When used with the strptime() method, the leading zero is optional for formats %d, %m, %H, %I, %M, %S, %j, %U, %W, and %V. Format %y does require a leading zero.

Notas de rodapé

[1]

Se, isto é, nós ignoramos os efeitos da Relatividade

[2]

Isso combina com a definição do calendário “proléptico Gregoriano” no livro Cálculos Calendáricos de Dershowitz e Reingold, onde ele é o calendário base para todas as computações. Veja o livro para algoritmos para conversão entre ordinais proléptico Gregoriano e muitos outros sistemas de calendário.

[3]

Veja O guia para a matemática de calendário ISO 8601 de R. H. van Gent para uma boa explicação.

[4]

Passing datetime.strptime('Feb 29', '%b %d') will fail since 1900 is not a leap year.