# `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.

Pacote DateType

  Biblioteca de terceiros que apresenta tipos estáticos distintos para, 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

  O menor número de ano permitido em um objeto `date` ou `datetime`. `MINYEAR` é 1.

datetime.MAXYEAR

  O maior número de ano permitido no objeto `date` ou `datetime`. `MAXYEAR` é 9999.

datetime.UTC

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

  Adicionado 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.

  Adicionado 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)

  Todos os argumentos são opcionais e o padrão é 0. Os argumentos podem ser números inteiros ou ponto flutuantes, e podem ser positivos ou negativos.

  Apenas days, seconds e microseconds 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 days, seconds e microseconds 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
      ... )
      >>> # sá restam dias, segundos e microssegundos
      >>> 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, a exceção `OverflowError` é levantada.

  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)`.

Observe que, devido à normalização, `timedelta.max` é maior que `-timedelta.min`. `-timedelta.max` não é representável como um objeto `timedelta`.

Atributos de instância (somente leitura):

timedelta.days

  Entre -999.999.999 e 999.999.999 inclusive

timedelta.seconds

  Entre 0 e 86.399 inclusive.

  Cuidado

  É um bug relativamente comum utilizar este atributo de forma não intencional quando, na verdade, o objetivo é obter o valor de `total_seconds()`:

      >>> from datetime import timedelta
      >>> duration = timedelta(seconds=11235813)
      >>> duration.days, duration.seconds
      (130, 3813)
      >>> duration.total_seconds()
      11235813.0

timedelta.microseconds

  Entre 0 e 999.999 inclusive.

Operações suportadas:

Operação | Resultado
--- | ---
`t1 = t2 + t3` | Soma de `t2` e `t3`. Depois `t1 - t2 == t3` e `t1 - t3 == t2` são verdadeiros. (1)
`t1 = t2 - t3` | Diferença de `t2` e `t3`. Depois `t1 == t2 - t3` e `t2 == t1 + t3` são verdadeiros (1)(6)
`t1 = t2 * i or t1 = i * t2` | Delta multiplicado por um número inteiro. Depois `t1 // i == t2` é verdadeiro, desde que `i != 0`.
| Em geral, `t1 * i == t1 * (i-1) + t1` é verdadeiro. (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` | Divisão (3) da duração total `t2` por unidade de intervalo `t3`. Retorna um objeto `float`.
`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` ou `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 resto: `q = t1 // t2` (3) e `r = t1 % t2`. `q` é um inteiro e `r` é um objeto `timedelta`.
`+t1` | Retorna um objeto `timedelta` com o mesmo valor. (2)
`-t1` | Equivalente a `timedelta(-t1.days, -t1.seconds, -t1.microseconds)` e a `t1 * -1`. (1)(4)
`abs(t)` | Equivalente a `+t` quando `t.days >= 0` e a `-t` quando `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. A divisão por zero levanta `ZeroDivisionError`.

4. `-timedelta.max` não é representável como um objeto `timedelta`.

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 divisão verdadeira 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.

  Adicionado na versão 3.2.

### Exemplos de uso: `timedelta`

Um exemplo adicional de normalização:

    >>> # Os componentes de outro_ano somam exatamente 365 dias
    >>> from datetime import timedelta
    >>> year = timedelta(days=365)
    >>> outro_ano = timedelta(weeks=40, days=84, hours=23,
    ...                       minutes=50, seconds=600)
    >>> year == outro_ano
    True
    >>> year.total_seconds()
    31536000.0

Exemplos de aritmética com `timedelta`:

    >>> from datetime import timedelta
    >>> ano = timedelta(days=365)
    >>> dez_anos = 10 * ano
    >>> dez_anos
    datetime.timedelta(days=3650)
    >>> dez_anos.days // 365
    10
    >>> nove_anos = dez_anos - ano
    >>> nove_anos
    datetime.timedelta(days=3285)
    >>> três_anos = nove_anos // 3
    >>> três_anos, três_anos.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, a exceção `ValueError` é levantada.

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)

  Adicionado 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()`.

  Adicionado 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` terá `timedelta.days` dias após `date1`. (1)
`date2 = date1 - timedelta` | Calcula `date2` de modo que `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. A exceção `OverflowError` é levantada se `date2.year` for menor que `MINYEAR` ou maior que `MAXYEAR`.

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

3. Isso é exato e não pode estourar. `timedelta.seconds` e `timedelta.microseconds` são 0, e `date2 + timedelta == date1` depois.

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

   Objetos `date` que não são também instâncias `datetime` nunca são iguais a objetos `datetime`, mesmo que representem 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()`.

   A comparação de ordem entre um objeto `date` que não é também uma instância `datetime` e um objeto `datetime` levanta `TypeError`.

Alterado na versão 3.13: A comparação entre o objeto `datetime` e uma instância da subclasse `date` que não é uma subclasse `datetime` não converte mais a última para `date`, ignorando o parte horária e o fuso horário. O comportamento padrão pode ser alterado substituindo os métodos especiais de comparação nas subclasses.

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)

  Objetos `date` também são suportados pela função genérica `copy.replace()`.

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))

  sendo `yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1` o número do dia no ano atual, começando com 1 para 1º de janeiro.

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 um 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 Comportamento de strftime() e strptime() 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 Comportamento de strftime() e strptime() e `date.isoformat()`.

### Exemplos de uso: `date`

Exemplo de contagem de dias para um evento:

    >>> import time
    >>> from datetime import date
    >>> hoje = date.today()
    >>> hoje
    datetime.date(2007, 12, 5)
    >>> hoje == date.fromtimestamp(time.time())
    True
    >>> meu_aniversário = date(hoje.year, 6, 24)
    >>> if meu_aniversário < hoje:
    ...     meu_aniversário = meu_aniversário.replace(year=hoje.year + 1)
    ...
    >>> meu_aniversário
    datetime.date(2008, 6, 24)
    >>> tempo_até_aniversário = abs(meu_aniversário - hoje)
    >>> tempo_até_aniversário.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` presume o atual calendário Gregoriano estendido em ambas as direções; assim como um objeto `time`, `datetime` presume 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, a exceção `ValueError` é levantada.

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

Outros construtores, todos os métodos de classe.

classmethod datetime.today()

  Retorna a data e hora local atual, com o atributo `tzinfo` definido 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()`.

  Nota

  Chamadas subsequentes para `datetime.now()` podem retornar o mesmo instante, dependendo da precisão do relógio subjacente.

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)`.

  Descontinuado 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()`.

  Descontinuado 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)))

  Adicionado 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()`.

  Adicionado 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 Comportamento de strftime() e strptime() e `datetime.fromisoformat()`.

  Alterado na versão 3.13: Se format especificar um dia do mês sem um ano, um `DeprecationWarning` agora é emitido. Isso é para evitar um bug de ano bissexto quadrienal no código que busca analisar apenas um mês e dia, pois o ano padrão usado na ausência de um no formato não é um ano bissexto. Esses valores de format podem gerar um erro a partir do Python 3.15. A solução alternativa é sempre incluir um ano em seu format. Se estiver analisando valores de date_string que não têm um ano, adicione explicitamente um ano que seja um ano bissexto antes da análise:

      >>> from datetime import datetime
      >>> date_string = "02/29"
      >>> when = datetime.strptime(f"{date_string};1984", "%m/%d;%Y")  # Avoids leap year bug.
      >>> when.strftime("%B %d")
      'February 29'

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

  Entre `[0, 1]`. Usado para desambiguar tempos reais durante um intervalo repetido. (Um intervalo repetido ocorre quando relógios são atrasados ao final do horário de verão ou quando a diferença UTC para o fuso horário atual é reduzida por razões políticas.) Os valores 0 e 1 representam, respectivamente, o primeiro e o segundo dos dois momentos com a mesma representação de tempo real.

  Adicionado 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` representa a duração de `timedelta` removido de `datetime1`, movendo o tempo para frente se `timedelta.days > 0`, ou para trás se `timedelta.days < 0`. O resultado tem o mesmo atributo `tzinfo` que o datetime de entrada, e `datetime2 - datetime1 == timedelta` após. `OverflowError` é levantada se `datetime2.year` fosse menor que `MINYEAR` ou maior que `MAXYEAR`. Perceba que nenhum ajuste no fuso horário é feito mesmo se a entrada é um objeto consciente disso.

2. Computa o `datetime2` tal que `datetime2 + timedelta == datetime1`. Assim como para adição, o resultado tem o mesmo atributo `tzinfo` que datetime de entrada, e nenhum ajuste de fuso horário é feito mesmo que a entrada seja consciente disso.

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 tiverem 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` tivessem sido primeiro convertidos para datetimes ingênuas em UTC. O resultado é `(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset())` exceto que a implementação nunca estoura.

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

   Objetos `datetime` ingênuos e conscientes nunca são iguais.

   Se ambos os comparandos forem conscientes e tiverem o mesmo atributo `tzinfo`, os atributos `tzinfo` e `fold` serão ignorados e os datetimes base serão comparados. Se ambos os comparandos forem conscientes e tiverem atributos `tzinfo` diferentes, a comparação atua como se os comparandos fossem primeiro convertidos para datetimes UTC, exceto que a implementação nunca estoura. Instâncias `datetime` em um intervalo repetido nunca são iguais a instâncias `datetime` em outro fuso horário.

5. datetime1 é considerado menor que datetime2 quando datetime1 precede datetime2 no tempo. levando em consideração o fuso horário.

   A comparação de ordens entre objetos `datetime` ingênuos e conscientes levanta `TypeError`.

   Se ambos os comparandos forem conscientes e tiverem o mesmo atributo `tzinfo`, os atributos `tzinfo` e `fold` serão ignorados e os datetimes base serão comparados. Se ambos os comparandos forem conscientes e tiverem atributos `tzinfo` diferentes, a comparação atua como se os comparandos fossem primeiro convertidos para datetimes UTC, exceto que a implementação nunca estoura.

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

Alterado na versão 3.13: A comparação entre o objeto `datetime` e uma instância da subclasse `date` que não é uma subclasse `datetime` não converte mais a última para `date`, ignorando o parte horária e o fuso horário. O comportamento padrão pode ser alterado substituindo os métodos especiais de comparação nas subclasses.

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.

  Objetos `datetime` também são suportados pela função genérica `copy.replace()`.

  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 é presumido 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 `timezone` 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 `timezone` 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
          # Converte self para UTC e anexa o novo objeto timezone.
          utc = (self - self.utcoffset()).replace(tzinfo=tz)
          # Converte o horário local de UTC para tz.
          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))

  onde `yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1` é o número de dias dentro do ano atual, começando com 1 para 1º de janeiro. O sinalizador `tm_isdst` do resultado é definido conforme o método `dst()`: `tzinfo` é `None` ou `dst()` retorna `None`, `tm_isdst` é definido para `-1`; caso contrário se `dst()` retornar um valor diferente de zero, `tm_isdst` é definido para 1; caso contrário `tm_isdst` é definido para 0.

datetime.utctimetuple()

  Se a instância `datetime` `d` é ingênua, isto é o mesmo que `d.timetuple()`, exceto que `tm_isdst` é forçado para 0, independentemente do que `d.dst()` retornar. O horário de verão nunca é afetado por um horário UTC.

  Se `d` é consciente, `d` é normalizado para horário UTC, subtraindo `d.utcoffset()`, e um `time.struct_time` para o horário normalizado é retornado. `tm_isdst` é forçado para 0. Observe que uma exceção `OverflowError` pode ser levantada se `d.year` for `MINYEAR` ou `MAXYEAR` e os ajustes UTC ultrapassar o limite de um ano.

  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()`.

  Presume-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()

  Adicionado 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):
      ...     """Um fuso horário com uma posição arbitrária constante de -06:39."""
      ...     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: Adicionado o parâmetro timespec.

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 Comportamento de strftime() e strptime() 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 Comportamento de strftime() e strptime() e `datetime.isoformat()`.

### Exemplos de uso: `datetime`

Exemplos para trabalhar com objetos `datetime`:

    >>> 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 usou +4 até 1945, quando eles moveram para +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):
                # Um intervalo de meia hora ambíguo ("imaginário") representando
                # um 'fold' no tempo por causa da troca de +4 para +4:30.
                # Se dt cair no intervalo imaginário, usa a fold para decidir como
                # para resolver. Veja PEP495.
                return timedelta(hours=4, minutes=(30 if dt.fold else 0))
            else:
                return timedelta(hours=4, minutes=30)

        def fromutc(self, dt):
            # Segue as mesmas validações como em datetime.tzinfo
            if not isinstance(dt, datetime):
                raise TypeError("fromutc() requer um argumento datetime")
            if dt.tzinfo is not self:
                raise ValueError("dt.tzinfo não é self")

            # Uma implementação personalizada é necessária para fromutc
            # como a entrada para esta função é um datetime com valores utc
            # mas com um tzinfo definido para self.
            # Veja datetime.astimezone ou 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 não tem horário de verão.
            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 antes da alteração
    >>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
    >>> print(dt1.utcoffset())
    4:00:00

    >>> # Datetime após a alteração
    >>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
    >>> print(dt2.utcoffset())
    4:30:00

    >>> # Converte datetime para outro fuso horário
    >>> 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`

Um objeto `time` representa a hora (local) do dia, independente de qualquer dia em particular, e sujeito a ajustes através de um objeto `tzinfo`.

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]`.

  Se um argumento fora desses intervalos é fornecido, `ValueError` é levantada. Todos tem como padrão o valor 0 exceto tzinfo, o qual tem o valor padrão `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

  Entre `[0, 1]`. Usado para desambiguar tempos reais durante um intervalo repetido. (Um intervalo repetido ocorre quando relógios são atrasados ao final do horário de verão ou quando a diferença UTC para o fuso horário atual é reduzida por razões políticas.) Os valores 0 e 1 representam, respectivamente, o primeiro e o segundo dos dois momentos com a mesma representação de tempo real.

  Adicionado na versão 3.6.

Objetos `time` oferecem suporte para comparações de igualdade e ordem, onde `a` é considerado menor que `b` quando `a` precede `b` no tempo.

Objetos `time` ingênuos e conscientes nunca são iguais. A comparação de ordem entre objetos `time` ingênuos e conscientes levanta `TypeError`.

Se ambos os comparandos são conscientes, e tem o mesmo atributo `tzinfo`, os atributos `tzinfo` e `fold` são ignorados e os tempos base são comparados. Se ambos os comparandos são conscientes e tem atributos `tzinfo` diferentes, os comparandos são primeiro ajustados subtraindo sua diferença em UTC (obtida através de `self.utcoffset()`).

Alterado na versão 3.3: Comparações de igualdade entre instâncias de `time` conscientes e nativas não levantam `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)

  Adicionado 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.

  Objetos `time` também são suportados pela função genérica `copy.replace()`.

  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: Adicionado o parâmetro timespec.

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 Comportamento de strftime() e strptime() 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 Comportamento de strftime() e strptime() 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'
    >>> 'A {} é {:%H:%M}.'.format("hora", t)
    'A hora é 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.

  Você precisa derivar uma subclasse concreta, e (pelo menos) fornecer implementações dos métodos padrões de `tzinfo` necessários pelos métodos `datetime` que você usa. O módulo `datetime` fornece `timezone`, uma subclasse concreta simples de `tzinfo`, que pode representar fusos horários com diferença fixa a partir de UTC, tais como o próprio UTC, ou EST (Eastern Standard Time ou Horário padrão oriental) e EDT (Eastern Daylight Time ou Horário de verão oriental) na América do Norte.

  Requisito especial para preservação: uma subclasse `tzinfo` deve ter um método `__init__()` que pode ser chamado sem nenhum argumento, caso contrário ele pode ser conservado, mas não alterado novamente. Isso é um requisito técnico que pode ser relaxado no futuro.

  Uma subclasse concreta de `tzinfo` pode precisar implementar os seguintes métodos. Exatamente quais métodos são necessários depende do uso feito de objetos `datetime` conscientes. Se estiver em dúvida, simplesmente implemente todos eles.

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                 # classe de posição fixa
      return CONSTANT + self.dst(dt)  # classe consciente de horário de verão

  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.

  Retorna `timedelta(0)` se o horário de verão não estiver ativo. Se o horário de verão estiver ativo, retorna a diferença como um objeto `timedelta` (veja `utcoffset()` para detalhes). Perceba que a diferença do horário de verão, se aplicável, já foi adicionada a diferença UTC retornada por `utcoffset()`, então não existe necessidade de consultar `dst()` a não ser que você esteja interessado em obter a informação de horário de verão separadamente. Por exemplo, `datetime.timetuple()` chama o método `dst()` do seu atributo `tzinfo` para determinar como o flag `tm_isdst` deve ser definido, e `tzinfo.fromutc()` chama `dst()` para contabilizar as mudanças de horário de verão quando ocorrem mudanças de fuso horário.

  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)`

  deve retornar o mesmo resultado para cada `datetime` dt com `dt.tzinfo == tz` para subclasses `tzinfo` sãs, esta expressão produz a “diferença padrão” do fuso horário, a qual não deve depender de data ou hora, mas apenas de localização geográfica. A implementação de `datetime.astimezone()` depende disso, mas não pode detectar violações; é responsabilidade do programador garantir isso. Se uma subclasse `tzinfo` não pode garantir isso, ele pode ser capaz de substituir a implementação padrão de `tzinfo.fromutc()` para funcionar corretamente com `astimezone()` independente disso.

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

      def dst(self, dt):
          # uma classe de posição fixa: não levam em conta DST
          return timedelta(0)

  ou:

      def dst(self, dt):
          # Código para definir dston e dstoff para os horários
          # de transição do horário de versão com base
          # no dt.year de entrada e expresso no horário local padrão.

          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)

  Retorna o nome do fuso horário correspondente ao objeto `datetime` dt, como uma string. Nada sobre nomes de strings é definido pelo módulo `datetime`, e não há nenhuma exigência de que signifique algo em particular. Por exemplo, `"GMT"`, `"UTC"`, `"-500"`, `"-5:00"`, `"EDT"`, `"US/Eastern"`, `"America/New York"` são todas respostas válidas. Retorna `None` se um nome de string não for conhecido. Observe que este é um método em vez de uma string fixa, principalmente porque algumas subclasses `tzinfo` desejarão retornar nomes diferentes dependendo do valor específico de dt passado, especialmente se a classe `tzinfo` estiver contabilizando o horário de verão.

  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 em resposta a um método `datetime`, `dt.tzinfo` é o mesmo objeto que self. Os métodos `tzinfo` podem confiar nisso, a menos que o código do usuário chame métodos `tzinfo` diretamente. A intenção é que os métodos `tzinfo` interpretem dt como estando no horário local, e não precisem se preocupar com objetos em outros fusos horários.

Existe mais um método `tzinfo` que uma subclasse pode desejar substituição:

tzinfo.fromutc(dt)

  Isto é chamado a partir do padrão implementação de `datetime.astimezone()`. Quando chamado a partir dele, `dt.tzinfo` é self, e os dados de data e hora de dt devem ser vistos como expressando um Horário Universal Coordenado (UTC). O propósito de `fromutc()` é ajustar os dados de data e hora, retornando um datetime equivalente na hora local de self.

  A maioria das subclasses de `tzinfo` deve ser capaz de herdar a implementação padrão de `fromutc()` sem problemas. Ela é robusta o suficiente para lidar com fusos horários de deslocamento fixo, e fusos horários que contabilizam tanto o horário padrão quanto o horário de verão, sendo que este último é tratado mesmo que os horários de transição do horário de verão sejam diferentes em anos distintos. Um exemplo de fuso horário que a implementação padrão de `fromutc()` pode não lidar corretamente em todos os casos é aquele onde o deslocamento padrão (de UTC) depende da data e hora específicas passadas, o que pode acontecer por razões políticas. As implementações padrão de `astimezone()` e `fromutc()` podem não produzir o resultado desejado se o resultado estiver entre as horas que abrangem o momento em que o deslocamento padrão muda.

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

      def fromutc(self, dt):
          # levanta o erro ValueError se dt.tzinfo não é o self
          dtoff = dt.utcoffset()
          dtdst = dt.dst()
          # levanta ValueError se dtoff é None ou dtdst é None
          delta = dtoff - dtdst  # este é o deslocamento padrão do self
          if delta:
              dt += delta   # converter para hora local padrão
              dtdst = dt.dst()
              # levanta ValueError se dtdst é 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)

    # Uma classe que captura a ideia da plataforma sobre o horário local.
    # (Pode resultar em valores errados em horários históricos em fusos horários
    #  onde o deslocamento UTC e/ou as regras de horário de verão
    #  foram alteradas no passado.)
    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()

    # Uma implementação completa das regras atuais do horário de verão para os principais fusos horários dos EUA.

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

    # Regras do horário de verão dos EUA
    #
    # Este é um conjunto simplificado (ou seja, incorreto em alguns casos)
    # de regras para os horários de início e término do horário de verão dos EUA.
    # Para um conjunto completo e atualizado de regras de horário de verão
    # e definições de fuso horário, visite o Olson Database (ou tente pytz):
    # http://www.twinsun.com/tz/tz-link.htm
    # https://sourceforge.net/projects/pytz/ (pode não estar atualizado)
    #
    # Nos EUA, desde 2007, o horário de verão começa às 2h (horário padrão) no
    # segundo domingo de março, que é o primeiro domingo em ou após 8 de março.
    DSTSTART_2007 = datetime(1, 3, 8, 2)
    # e termina às 2h (horário de verão) no primeiro domingo de novembro.
    DSTEND_2007 = datetime(1, 11, 1, 2)
    # De 1987 a 2006, o horário de verão costumava começar às 2h
    # (horário padrão) no primeiro domingo de abril e terminar às 2h
    # (horário de verão) no último Domingo de outubro, que é o primeiro
    # domingo em ou após 25 de outubro.
    DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
    DSTEND_1987_2006 = datetime(1, 10, 25, 2)
    # De 1967 a 1986, o horário de verão costumava começar às 2h
    # (horário padrão) no último domingo de abril (aquele em ou após
    # 24 de abril) e terminar às 2h (horário de verão) no último domingo
    # de outubro, que é o primeiro domingo em ou após 25 de outubro.
    DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
    DSTEND_1967_1986 = DSTEND_1987_2006

    def us_dst_range(year):
        # Encontra os horários de início e fim do horário de verão dos EUA.
        # Para anos anteriores a 1967, retorne start = end para nenhum horário
        # de verão.
        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:
                # Uma exceção pode ser sensata aqui, em um ou ambos os casos.
                # Depende de como você quer tratá-las. A implementação padrão
                # fromutc() (chamada pela implementação padrão astimezone()) passa
                # um datetime com dt.tzinfo é self.
                return ZERO
            assert dt.tzinfo is self
            start, end = us_dst_range(dt.year)
            # Não é possível comparar objetos ingênuos com objetos conscientes,
            # então retira o fuso horário de dt primeiro.
            dt = dt.replace(tzinfo=None)
            if start + HOUR <= dt < end - HOUR:
                # Horário de verão está em vigor.
                return HOUR
            if end - HOUR <= dt < end:
                # Fold (uma hora ambígua): usa dt.fold para desambiguar.
                return ZERO if dt.fold else HOUR
            if start <= dt < start + HOUR:
                # Intervalo (uma hora inexistente): inverta a regra da dobra.
                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:
                # Hora repetida
                return std_time.replace(fold=1)
            if std_time < start or dst_time >= end:
                # Horário padrão
                return std_time
            if start <= std_time < end - HOUR:
                # Horário de verão
                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

Quando o horário de verão termina (a linha “end”), há um problema potencialmente pior: existe uma hora que não pode ser expressa de forma inequívoca no horário local: a última hora do horário de verão. No fuso Eastern, isso corresponde a horários no formato 5:MM UTC no dia em que o horário de verão termina. O relógio de parede local salta de 1:59 (horário de verão) para 1:00 (horário padrão) novamente. Horários locais no formato 1:MM são ambíguos. `astimezone()` imita o comportamento do relógio local mapeando então duas horas UTC adjacentes para a mesma hora local. No exemplo do fuso Eastern, horários UTC no formato 5:MM e 6:MM ambos se transformam em 1:MM quando convertidos para o fuso Eastern, mas os horários anteriores têm o atributo `fold` definido como 0 e os horários posteriores têm o atributo definido como 1. Por exemplo, na transição de retorno de 2016, obtemos:

    >>> 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

Observe que as instâncias de `datetime` que diferem apenas pelo valor do atributo `fold` são consideradas iguais nas comparações.

Aplicações que não suportam ambiguidades de tempo devem verificar explicitamente o valor do atributo `fold` ou evitar utilizar subclasses híbridas `tzinfo`; não há ambiguidades ao usar `timezone` ou qualquer outra subclasse `tzinfo` de deslocamento fixo (como uma classe que representa apenas EST (deslocamento fixo de -5 horas) ou apenas EDT (deslocamento fixo de -4 horas)).

Ver também

> `zoneinfo`

>   O módulo `datetime` possui uma classe básica `timezone` (para lidar com deslocamentos fixos arbitrários do UTC) e seu atributo `timezone.utc` (uma instância UTC `timezone` ).

>   `zoneinfo` traz o banco de dados de fuso horário IANA (também conhecido como banco de dados Olson) para Python, e seu uso é recomendado.

Banco de dados de fuso horário da 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`, cada instância da qual representa um fuso horário definido por um deslocamento fixo do UTC.

Objetos desta classe não podem ser usados ​para representar informações de fuso horário em locais onde diferentes deslocamentos são usados ​em diferentes dias do ano ou onde mudanças históricas foram feitas no horário 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()`.

  Adicionado 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))`.

## Comportamento de `strftime()` e `strptime()`

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.

A tabela abaixo fornece uma comparação de alto nível entre `strftime()` e `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)`

### Códigos de formato `strftime()` e `strptime()`

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)

Eles podem não estar disponíveis em todas as plataformas quando usados ​com o método `strftime()`. As diretivas de ano e semana da ISO 8601 e ISO 8601 não são intercambiáveis ​com as diretivas ano e número da semana acima. Chamar `strptime()` com diretivas ISO 8601 incompletas ou ambíguas levantará um `ValueError`.

O conjunto completo de códigos de formato suportados varia entre as plataformas, porque o Python chama a função `strftime()` da biblioteca C da plataforma, e variações de plataforma são comuns. Para ver o conjunto completo de códigos de formato suportados em sua plataforma, consulte a documentação strftime(3). Também existem diferenças entre plataformas no tratamento de especificadores de formato não suportados.

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

Adicionado na versão 3.12: `%:z` foi adicionado.

### Detalhes técnicos

Em termos gerais, `d.strftime(fmt)` age como `time.strftime(fmt, d.timetuple())` do módulo `time`, embora nem todos os objetos suportem um método `timetuple()`.

Para o método de classe `datetime.strptime()`, o valor padrão é `1900-01-01T00:00:00.000`: quaisquer componentes não especificados na string de formato serão extraídos do valor padrão. [4]

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

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

exceto quando o formato inclui componentes de sub-segundos ou informações de deslocamento de fuso horário, que são suportados em `datetime.strptime` mas são descartados por `time.strptime`.

Para objetos `time`, os códigos de formato para ano, mês e dia não devem ser usados, pois objetos `time` não têm tais valores. Se forem usados ​de qualquer forma, o ano é substituído por 1900, e o mês e dia por 1.

Para objetos `date`, os códigos de formato para horas, minutos, segundos e microssegundos não devem ser usados, pois objetos `date` não têm tais valores. Se forem usados ​de qualquer forma, são substituídos por 0.

Pela mesma razão, o tratamento de formato 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. O método `strptime()` pode analisar anos no intervalo completo de [1, 9999], mas anos < 1000 devem ser preenchidos com zeros até uma largura de 4 dígitos.

   Alterado na versão 3.2: Em versões anteriores, o método `strftime()` era limitado a anos >= 1900.

   Alterado na versão 3.3: Na versão 3.2, o método `strftime()` era limitado a anos >= 1000.

3. Quando usado com o método `strptime()`, a diretiva `%p` afeta somente o campo de hora de saída se a diretiva `%I` for usada para analisar a hora.

4. Ao contrário do módulo `time`, o módulo `datetime` não oferece suporte para segundos intercalares.

5. Quando usado com o método `strptime()`, a diretiva `%f` aceita de um a seis dígitos e zeros à direita. `%f` é uma extensão do conjunto de caracteres de formato no padrão do C (mas implementado separadamente em objetos datetime e, portanto, sempre disponível).

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()` é transformado em uma string do formato `±HHMM[SS[.ffffff]]`, onde `HH` é uma string de 2 dígitos que fornece o número de horas de deslocamento UTC, `MM` é uma string de 2 dígitos que fornece o número de minutos de deslocamento UTC, `SS` é uma string de 2 dígitos que fornece o número de segundos de deslocamento UTC e `ffffff` é uma string de 6 dígitos que fornece o número de microssegundos de deslocamento UTC. A parte `ffffff` é omitida quando o deslocamento é um número inteiro de segundos e tanto a parte `ffffff` quanto a parte `SS` são omitidas quando o deslocamento é um número inteiro de minutos. Por exemplo, se `utcoffset()` retornar `timedelta(hours=-3, minutes=-30)`, `%z` será substituído pela 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: Quando a diretiva `%z` é fornecida ao método `strptime()`, os deslocamentos UTC podem ter dois pontos como separador entre horas, minutos e segundos. Por exemplo, `'+01:00:00'` será analisado como um deslocamento de uma hora. Além disso, fornecer `'Z'` é idêntico a `'+00:00'`.

   `%:z`

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

   `%Z`

     Em `strftime()`, `%Z` é substituído por uma string vazia se `tzname()` retornar `None`; caso contrário, `%Z` é substituído pelo valor retornado, que deve ser uma string.

     `strptime()` aceita apenas certos valores para `%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: Quando a diretiva `%z` é fornecida ao método `strptime()`, um objeto `datetime` consciente será produzido. O `tzinfo` do resultado será definido para uma instância `timezone`.

7. Quando utilizados ​com o método `strptime()`, `%U` e `%W` são usados ​somente em cálculos quando o dia da semana e o ano (`%Y`) são especificados.

8. Semelhante a `%U` e `%W`, `%V` é usado apenas em cálculos quando o dia da semana e o ano ISO (`%G`) são especificados em um formato de string `strptime()`. Observe também que `%G` e `%Y` não são intercambiáveis.

9. Quando usado com o método `strptime()`, o zero à esquerda é opcional para os formatos `%d`, `%m`, `%H`, `%I`, `%M`, `%S`, `%j`, `%U`, `%W` e `%V`. O formato `%y` requer um zero à esquerda.

10. Ao analisar um mês e dia usando `strptime()`, sempre inclua um ano no formato. Se o valor que você precisa analisar não possui um ano, adicione um ano bissexto fictício de forma explícita. Caso contrário, seu código levantará uma exceção ao encontrar o dia bissexto, porque o ano padrão usado pelo analisador sintático não é um ano bissexto. Os usuários encontram esse bug a cada quatro anos…

        >>> month_day = "02/29"
        >>> datetime.strptime(f"{month_day};1984", "%m/%d;%Y")  # Sem bug de ano bissexto.
        datetime.datetime(1984, 2, 29, 0, 0)

    Deprecated since version 3.13, will be removed in version 3.15: Chamadas ao método `strptime()` usando uma string de formato contendo um dia do mês sem um ano agora emitem um `DeprecationWarning`. Na versão 3.15 ou posterior, podemos mudar isso para um erro ou mudar o ano padrão para um ano bissexto. Consulte gh-70647.

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 ]

Passar `datetime.strptime('Feb 29', '%b %d')` irá falhar porque 1900 não é um ano bissexto.