# `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
      ... )
      >>> # Only days, seconds, and microseconds remain
      >>> delta
      datetime.timedelta(days=64, seconds=29156, microseconds=10)

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

  Se o valor normalizado de dias estiver fora do intervalo indicado, 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):

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

Operações suportadas:

Operação | Resultado
--- | ---
`t1 = t2 + t3` | 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` or `t1 = t2 // t3` | O piso é calculado e o restante (se houver) é jogado fora. No segundo caso, um número inteiro é retornado. (3)
`t1 = t2 % t3` | O restante é calculado como um objeto `timedelta`. (3)
`q, r = divmod(t1, t2)` | Calcula o quociente e o restante: `q = t1 // t2` (3) e `r = t1 % t2`. q é um número inteiro e r é um objeto `timedelta`.
`+t1` | Retorna um objeto `timedelta` com o mesmo valor. (2)
`-t1` | 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:

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

Exemplos de aritmética com `timedelta`:

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

## Objetos `date`

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

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

class datetime.date(year, month, day)

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

  - `MINYEAR <= year <= MAXYEAR`

  - `1 <= month <= 12`

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

  Se um argumento fora desses intervalos for fornecido, 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 uma data d, `str(d)` é equivalente a `d.isoformat()`.

date.ctime()

  Retorna uma string representando a data:

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

  `d.ctime()` é equivalente a:

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

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

date.strftime(format)

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

date.__format__(format)

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

### Exemplos de uso: `date`

Exemplo de contagem de dias para um evento:

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

Mais exemplos de uso da classe `date`:

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

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

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

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

## Objetos `datetime`

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

Assim como um objeto `date`, `datetime` 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 o datetime local atual, com o atributo `tzinfo` setado para `None`.

  Equivalente a:

      datetime.fromtimestamp(time.time())

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

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

classmethod datetime.now(tz=None)

  Retorna a data e hora local atual.

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

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

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

classmethod datetime.utcnow()

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

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

  Aviso

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

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

classmethod datetime.fromtimestamp(timestamp, tz=None)

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

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

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

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

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

classmethod datetime.utcfromtimestamp(timestamp)

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

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

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

      datetime.fromtimestamp(timestamp, timezone.utc)

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

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

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

  Aviso

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

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

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

classmethod datetime.fromordinal(ordinal)

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

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

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

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

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

classmethod datetime.fromisoformat(date_string)

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

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

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

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

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

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

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

  Exemplos:

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

  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 strftime() and strptime() Behavior e `datetime.fromisoformat()`.

  Alterado na versão 3.13: If format specifies a day of month without a year a `DeprecationWarning` is now emitted. This is to avoid a quadrennial leap year bug in code seeking to parse only a month and day as the default year used in absence of one in the format is not a leap year. Such format values may raise an error as of Python 3.15. The workaround is to always include a year in your format. If parsing date_string values that do not have a year, explicitly add a year that is a leap year before parsing:

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

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

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

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

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

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

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

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

   Naive and aware `datetime` objects are never equal.

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

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

   Order comparison between naive and aware `datetime` objects raises `TypeError`.

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

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

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.

  `datetime` objects are also supported by generic function `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 de fuso horário tz a um datetime dt sem ajustes de dados de data e hora, use `dt.replace(tzinfo=tz)`. Se você meramente quer remover o objeto de fuso horário de um datetime consciente dt sem conversão de dados de data e hora, use `dt.replace(tzinfo=None)`.

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

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

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

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

datetime.utcoffset()

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

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

datetime.dst()

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

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

datetime.tzname()

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

datetime.timetuple()

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

  `d.timetuple()` é equivalente a:

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

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

datetime.utctimetuple()

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

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

  Aviso

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

datetime.toordinal()

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

datetime.timestamp()

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

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

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

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

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

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

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

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

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

  Nota

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

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

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

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

datetime.__str__()

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

datetime.ctime()

  Retorna uma string representando a data e hora:

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

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

  `d.ctime()` é equivalente a:

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

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

datetime.strftime(format)

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

datetime.__format__(format)

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

### Exemplos de uso: `datetime`

Examples of working with `datetime` objects:

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

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

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

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

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

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

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

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

    from datetime import timedelta, datetime, tzinfo, timezone

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

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

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

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

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

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

Uso de `KabulTz` mostrado acima:

    >>> tz1 = KabulTz()

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

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

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

## Objetos `time`

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

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

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

  - `0 <= hour < 24`,

  - `0 <= minute < 60`,

  - `0 <= second < 60`,

  - `0 <= microsecond < 1000000`,

  - `fold in [0, 1]`.

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

Atributos de classe:

time.min

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

time.max

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

time.resolution

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

Atributos de instância (somente leitura):

time.hour

  No intervalo `range(24)`.

time.minute

  No intervalo `range(60)`.

time.second

  No intervalo `range(60)`.

time.microsecond

  No intervalo `range(1000000)`.

time.tzinfo

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

time.fold

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

  Adicionado na versão 3.6.

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

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

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

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

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

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

Outro construtor:

classmethod time.fromisoformat(time_string)

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

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

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

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

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

  Exemplos:

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

  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.

  `time` objects are also supported by generic function `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: Added the timespec parameter.

time.__str__()

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

time.strftime(format)

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

time.__format__(format)

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

time.utcoffset()

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

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

time.dst()

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

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

time.tzname()

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

### Exemplos de uso: `time`

Exemplos para trabalhar com um objeto `time`:

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

## Objetos `tzinfo`

class datetime.tzinfo

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

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

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

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

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

tzinfo.utcoffset(dt)

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

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

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

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

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

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

tzinfo.dst(dt)

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

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

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

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

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

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

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

  or:

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

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

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

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

tzinfo.tzname(dt)

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

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

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

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

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

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

tzinfo.fromutc(dt)

  This is called from the default `datetime.astimezone()` implementation. When called from that, `dt.tzinfo` is self, and dt’s date and time data are to be viewed as expressing a UTC time. The purpose of `fromutc()` is to adjust the date and time data, returning an equivalent datetime in self’s local time.

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

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

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

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

    from datetime import tzinfo, timedelta, datetime

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

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

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

    DSTDIFF = DSTOFFSET - STDOFFSET

    class LocalTimezone(tzinfo):

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

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

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

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

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

    Local = LocalTimezone()

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

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

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

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

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

    class USTimeZone(tzinfo):

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

        def __repr__(self):
            return self.reprname

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ver também

> `zoneinfo`

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

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

Base de dados de fusos horários IANA

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

## Objetos `timezone`

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

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

class datetime.timezone(offset, name=None)

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

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

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

## `strftime()` and `strptime()` Behavior

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

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

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

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

### `strftime()` and `strptime()` Format Codes

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

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

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

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

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

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

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

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

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

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

### Detalhes técnicos

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

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

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

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

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

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

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

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

Notas:

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

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

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

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

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

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

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

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

   Para um objeto consciente:

   `%z`

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

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

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

   `%:z`

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

   `%Z`

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

     `strptime()` only accepts certain values for `%Z`:

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

     2. os valores codificados `UTC` e `GMT`

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

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

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

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

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

10. When parsing a month and day using `strptime()`, always include a year in the format. If the value you need to parse lacks a year, append an explicit dummy leap year. Otherwise your code will raise an exception when it encounters leap day because the default year used by the parser is not a leap year. Users run into this bug every four years…

        >>> month_day = "02/29"
        >>> datetime.strptime(f"{month_day};1984", "%m/%d;%Y")  # No leap year bug.
        datetime.datetime(1984, 2, 29, 0, 0)

    Descontinuado desde a versão 3.13, será removido na versão 3.15: `strptime()` calls using a format string containing a day of month without a year now emit a `DeprecationWarning`. In 3.15 or later we may change this into an error or change the default year to a leap year. See 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]

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