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

Ver também:

  Módulo "calendar"
     Funções gerais relacionadas ao calendário.

  Módulo "time"
     Acesso de hora e conversões.

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


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".
   "MAXYER" é "9999".


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 "date",
   "time" ou "datetime" para resolução de microssegundos.

class datetime.tzinfo

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

class datetime.timezone

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

   Novo na versão 3.2.

Objetos desse tipo são imutáveis.

Relacionamentos de subclasse:

   object
       timedelta
       tzinfo
           timezone
       time
       date
           datetime


Propriedades Comuns
-------------------

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

* Objetos desse tipo são imutáveis.

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

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


Determinando se um Objeto é Consciente ou Ingênuo
-------------------------------------------------

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

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

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

1. "d.tzinfo" não é "None"

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

Caso contrário, *d* é ingênuo.

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

1. "t.tzinfo" não é "None"

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

Caso contrário, *t* é ingênuo.

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


Objetos "timedelta"
===================

O objeto "timedelta" representa uma duração, a diferença entre duas
datas ou horas.

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 *dias*, *segundos* e *microssegundos* são armazenados
   internamente. Os argumentos são convertidos para essas unidades:

   * Um milissegundo é convertido em 1000 microssegundos.

   * Um minuto é convertido em 60 segundos.

   * Uma hora é convertida em 3600 segundos.

   * Uma semana é convertida para 7 dias.

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

   * "0 <= microseconds < 1000000"

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

   * "-999999999 <= days <= 999999999"

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

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

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

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

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

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

Atributos de classe:

timedelta.min

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

timedelta.max

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

timedelta.resolution

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

Observe que, devido à normalização, "timedelta.max" >
"-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 //    | O piso é calculado e o restante (se houver) é   |
| t3"                              | 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 0 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
verdadeira divisão e multiplicação de um objeto "timedelta" por um
objeto "float" agora são suportadas.

Comparações de objetos "timedelta" são suportadas, com algumas
ressalvas.

As comparações "==" ou "!=" *sempre* retornam um "bool", não importa o
tipo do objeto comparado:

   >>> from datetime import timedelta
   >>> delta1 = timedelta(seconds=57)
   >>> delta2 = timedelta(hours=25, seconds=2)
   >>> delta2 != delta1
   True
   >>> delta2 == 5
   False

Para todas as outras comparações (tais como "<" e ">"), quando um
objeto "timedelta" é comparado a um objeto de um tipo diferente,
"TypeError" é levantada:

   >>> delta2 > delta1
   True
   >>> delta2 > 5
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   TypeError: '>' not supported between instances of 'datetime.timedelta' and 'int'

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

Métodos de instância:

timedelta.total_seconds()

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

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

   Novo na versão 3.2.


Exemplos de uso: "timedelta"
----------------------------

Um exemplo adicional de normalização:

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

Exemplos de aritmética com "timedelta":

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


Objetos "date"
==============

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

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

class datetime.date(year, month, day)

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

   * "MINYEAR <= year <= MAXYEAR"

   * "1 <= month <= 12"

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

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

Outros construtores, todos os métodos de classe.

classmethod date.today()

   Retorna a data local atual.

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

classmethod date.fromtimestamp(timestamp)

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

   Isso pode levantar "OverflowError", se o timestamp 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
   timestamp, os segundos bissextos são ignorados por
   "fromtimestamp()".

   Alterado na versão 3.3: Levanta "OverflowError" ao invés de
   "ValueError" se o timestamp 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* fornecido no
   formato "YYYY-MM-DD":

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

   Isto é o inverso de "date.isoformat()". Ele suporta apenas o
   formato "YYYY-MM-DD".

   Novo na versão 3.7.

classmethod date.fromisocalendar(year, week, day)

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

   Novo na versão 3.8.

Atributos de classe:

date.min

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

date.max

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

date.resolution

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

Atributos de instância (somente leitura):

date.year

   Entre "MINYEAR" e "MAXYEAR" incluindo extremos.

date.month

   Entre 1 e 12 incluindo extremos.

date.day

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

Operações suportadas:

+---------------------------------+------------------------------------------------+
| Operação                        | Resultado                                      |
|=================================|================================================|
| "date2 = date1 + timedelta"     | *date2*  é "timedelta.days" dias removidos de  |
|                                 | *date1*. (1)                                   |
+---------------------------------+------------------------------------------------+
| "date2 = date1 - timedelta"     | Computa *date2* de modo que "date2 + timedelta |
|                                 | == date1". (2)                                 |
+---------------------------------+------------------------------------------------+
| "timedelta = date1 - date2"     | (3)                                            |
+---------------------------------+------------------------------------------------+
| "date1 < date2"                 | *date1* é considerada menor que *date2*        |
|                                 | quando *date1* precede *date2* no tempo. (4)   |
+---------------------------------+------------------------------------------------+

Notas:

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

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

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

4. Em outras palavras, "date1 < date2" se e somente se
   "date1.toordinal() < date2.toordinal()". Comparação de dadas
   levanta "TypeError" se o outro comparando não é também um objeto
   "date". Entretanto, "NotImplemented" é retornado ao invés se o
   outro comparando tem um atributo "timetuple()". Esse gancho fornece
   a outros tipos de objetos de datas uma chance de implementar
   comparações de tipo misto. Se não, quando um objeto "date" é
   comparado com um objeto de tipo diferente, "TypeError" é levantado
   a não ser que a comparação seja "==" ou "!=". Os últimos casos
   retornam "False" ou "True", respectivamente.

Em contextos booleanos, todo objeto "date" é considerado verdadeiro.

Métodos de instância:

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

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

   Exemplo:

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

date.timetuple()

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

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

   "d.timetuple()" é equivalente a:

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

   no qual "yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1"
   é o número do dia dentro do 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()

   Return a 3-tuple, (ISO year, ISO week number, ISO 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()
      (2004, 1, 1)
      >>> date(2004, 1, 4).isocalendar()
      (2004, 1, 7)

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'

   Esse é o inverso do método "date.isoformat()".

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. Para uma lista completa de
   diretivas de formatação, veja Comportamento de strftime() e
   strptime().

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()". Para uma lista completa de
   diretivas de formatação, veja Comportamento de strftime() e
   strptime().


Exemplos de uso: "date"
-----------------------

Exemplo de contagem de dias para um evento:

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

Mais exemplos de uso da classe "date":

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

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

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

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


Objetos "datetime"
==================

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

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

Construtor:

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

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

   * "MINYEAR <= year <= MAXYEAR",

   * "1 <= month <= 12",

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

   * "0 <= hour < 24",

   * "0 <= minute < 60",

   * "0 <= second < 60",

   * "0 <= microsecond < 1000000",

   * "fold in [0, 1]".

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

   Novo na versão 3.6: Adicionado o argumento "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 timestamp "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)".

classmethod datetime.fromtimestamp(timestamp, tz=None)

   Retorna a data e hora local correspondente ao timestamp POSIX, como
   é retornado por "time.time()". Se o argumento opcional *tz* é
   "None" ou não especificado, o timestamp é 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 timestamp é convertido para o fuso horário de
   *tz*.

   "fromtimestamp()" pode levantar "OverflowError", se o timestamp
   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 timestamp,
   segundos bissextos são ignorados por "fromtimestamp()", e então é
   possível ter dois timestamps 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 timestamp 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 timestamp POSIX, com
   "tzinfo" setado para "None". (O objeto resultante é ingênuo.)

   Isso pode levantar "OverflowError", se o timestamp 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 timestamp 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 timestamp 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()".

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=self.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.

   Para qualquer objeto "datetime" *d*, "d ==
   datetime.combine(d.date(), d.time(), d.tzinfo)". Se date é um
   objeto "datetime", seus componentes de hora e atributos "tzinfo"
   são ignorados.

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

classmethod datetime.fromisoformat(date_string)

   Retorna um "datetime" correspondente ao *date_string* em um dos
   formatos emitidos pelo "date.isoformat()" e "datetime.isoformat()".

   Especificamente, essa função dá suporte a strings nesse formato:

      YYYY-MM-DD[*HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]]

   em que "*" pode corresponder a qualquer caractere único.

   Cuidado:

     Isso *não* suporta a análise de strings ISO 8601 arbitrárias -
     serve apenas como a operação inversa do "datetime.isoformat()".
     Um analisador sintático ISO 8601 mais completo,
     "dateutil.parser.isoparse", está disponível no pacote externo
     dateutil.

   Exemplos:

      >>> from datetime import datetime
      >>> datetime.fromisoformat('2011-11-04')
      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-04 00:05:23.283')
      datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)
      >>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')
      datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc)
      >>> datetime.fromisoformat('2011-11-04T00:05:23+04:00')   
      datetime.datetime(2011, 11, 4, 0, 5, 23,
          tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))

   Novo na versão 3.7.

classmethod datetime.fromisocalendar(year, week, day)

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

   Novo na versão 3.8.

classmethod datetime.strptime(date_string, format)

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

   This is equivalent to:

      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. Para uma lista completa de
   diretivas de formatação, veja Comportamento de strftime() e
   strptime().

Atributos de classe:

datetime.min

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

datetime.max

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

datetime.resolution

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

Atributos de instância (somente leitura):

datetime.year

   Entre "MINYEAR" e "MAXYEAR" incluindo extremos.

datetime.month

   Entre 1 e 12 incluindo extremos.

datetime.day

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

datetime.hour

   No intervalo "range(24)".

datetime.minute

   No intervalo "range(60)".

datetime.second

   No intervalo "range(60)".

datetime.microsecond

   No intervalo "range(1000000)".

datetime.tzinfo

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

datetime.fold

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

   Novo na versão 3.6.

Operações suportadas:

+-----------------------------------------+----------------------------------+
| Operação                                | Resultado                        |
|=========================================|==================================|
| "datetime2 = datetime1 + timedelta"     | (1)                              |
+-----------------------------------------+----------------------------------+
| "datetime2 = datetime1 - timedelta"     | (2)                              |
+-----------------------------------------+----------------------------------+
| "timedelta = datetime1 - datetime2"     | (3)                              |
+-----------------------------------------+----------------------------------+
| "datetime1 < datetime2"                 | Compara um "datetime" a um       |
|                                         | "datetime". (4)                  |
+-----------------------------------------+----------------------------------+

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

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

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

   Se ambos são ingênuos, ou ambos são conscientes e 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 tem 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. *datetime1* é considerado menor que *datetime2* quando *datetime1*
   precede *datetime2* no tempo.

   Se um comparando é ingênuo e o outro é consciente, "TypeError" é
   levantado ao tentar uma comparação de ordem. Para comparações de
   igualdade, instâncias ingênuas nunca são iguais a instâncias
   conscientes.

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

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

   Nota:

     Para impedir comparações de caírem de volta no esquema padrão de
     comparação de endereços de objetos, comparações de datetimes
     normalmente levantam "TypeError" se o outro comparando não é
     também um objeto "datetime". Entretanto, "NotImplemented" é
     retornado ao invés se o outro comparando tem um atributo
     "timetuple()". Este gancho dá a outros tipos de objetos de data a
     chance de implementar comparações de tipo misto. Se não, quando
     um objeto "datetime" é comparado com um objeto de tipo diferente,
     "TypeError" é levantado a não ser que a comparação seja "==" ou
     "!=". Os últimos casos retornam "False" ou "True",
     respectivamente.

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.

   Novo na versão 3.6: Adicionado o argumento "fold".

datetime.astimezone(tz=None)

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

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

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

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

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

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

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

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

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

datetime.utcoffset()

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

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

datetime.dst()

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

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

datetime.tzname()

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

datetime.timetuple()

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

   "d.timetuple()" é equivalente a:

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

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

datetime.utctimetuple()

   Se a instância "datetime" *d* é ingênua, isto é o mesmo que
   "d.timetuple()" exceto que "tm_isdst" é forçado para 0 independente
   do que "d.dst()" retorna. DST nunca é afetado por um horário UTC.

   Se *d* é consciente, *d* é normalizado para horário UTC, subtraindo
   "d.utcoffset()", e uma "time.struct_time" para a hora normalizada é
   retornado. "tm_isdst" é forçado para 0. Perceba que um
   "OverflowError" pode ser levantado se *d*.year for "MINYEAR" ou
   "MAXYEAR" e os ajustes UTC ultrapassarem o limite de um ano.

   Aviso:

     Por causa que objetos "datetime" ingênuos são tratados por muitos
     métodos "datetime" como hora local, é preferido usar datetimes
     conscientes para representar horários em UTC; como resultado,
     usar "utcfromtimetuple" 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 timestamp POSIX correspondente a instância "datetime". O
   valor de retorno é um "float" similar aquele retornado por
   "time.time()".

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

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

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

   Novo na versão 3.3.

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

   Nota:

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

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

     ou calculando o timestamp 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()

   Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The
   same as "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'

   Novo na versão 3.6: Argumento *timespec* adicionado.

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. Para uma lista completa de diretivas
   de formatação, veja Comportamento de strftime() e strptime().

datetime.__format__(format)

   O mesmo que "datetime.strftime()". Isto torna possível especificar
   uma string de formatação para um objeto "datetime" em literais de
   string formatados e ao usar "str.format()". Para uma lista completa
   de diretivas de formatação, veja Comportamento de strftime() e
   strptime().


Exemplos de uso: "datetime"
---------------------------

Exemplos de uso de objetos "datetime":

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

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

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

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

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

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

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

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

   from datetime import timedelta, datetime, tzinfo, timezone

   class KabulTz(tzinfo):
       # Kabul 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"
==============

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

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

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

   * "0 <= hour < 24",

   * "0 <= minute < 60",

   * "0 <= second < 60",

   * "0 <= microsecond < 1000000",

   * "fold in [0, 1]".

   Se um argumento fora desses intervalos é fornecido, "ValueError" é
   levantado. Todos tem como padrão o valor "0" exceto *tzinfo*, o
   qual tem o valor padrão "None".

Atributos de classe:

time.min

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

time.max

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

time.resolution

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

Atributos de instância (somente leitura):

time.hour

   No intervalo "range(24)".

time.minute

   No intervalo "range(60)".

time.second

   No intervalo "range(60)".

time.microsecond

   No intervalo "range(1000000)".

time.tzinfo

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

time.fold

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

   Novo na versão 3.6.

Objetos "time" suportam comparação de "time" e "time", onde *a* é
considerado menor que *b* quando *a* precede *b* no tempo. Se um
comparando é ingênuo e o outro é consciente, "TypeError" é levantado
ao tentar uma comparação. Para comparações de igualdade, instâncias
ingênuas nunca são iguais a instâncias conscientes.

Se ambos os comparandos são conscientes, e tem o mesmo atributo
"tzinfo", o atributo comum "tzinfo" é ignorado e os horários base são
comparados. Se ambos os comparandos são conscientes e tem atributos
"tzinfo" diferentes, os comparandos são primeiro ajustados subtraindo
sua diferença relativa a UTC (obtida a partir de "self.utcoffset()").
Para impedir comparações de tipo misto de cair novamente na comparação
padrão por endereço de objeto, quando um objeto "time" é comparado com
um objeto de tipo diferente, "TypeError" é levantado a não ser que a
comparação seja "==" ou "!=". O último caso retorna "False" ou "True",
respectivamente.

Alterado na versão 3.3: Comparações de igualdade entre instâncias
conscientes e ingênuas "time" não levantam "TypeError".

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

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

Outro construtor:

classmethod time.fromisoformat(time_string)

   Retorna um "time" correspondendo a *time_string* em um dos formatos
   emitidos por "time.isoformat()". Especificamente, esta função
   suporta strings no formato:

      HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]

   Cuidado:

     Isto *não* suporta interpretar strings ISO 8601 arbitrárias. Ela
     só é projetada para uso como a operação inversa de
     "time.isoformat()".

   Exemplos:

      >>> from datetime import time
      >>> time.fromisoformat('04:23:01')
      datetime.time(4, 23, 1)
      >>> 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)))

   Novo na versão 3.7.

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.

   Novo na versão 3.6: Adicionado o argumento "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'

   Novo na versão 3.6: Argumento *timespec* adicionado.

time.__str__()

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

time.strftime(format)

   Retorna uma string representando o tempo, controlado por uma
   formatação explícita de string. Para uma lista completa de
   diretivas de formatação, veja Comportamento de strftime() e
   strptime().

time.__format__(format)

   O mesmo que "time.strftime()". Isto torna possível especificar uma
   string de formatação para um objeto "time" em literais de string
   formatados e quando usamos "str.format()". Para uma lista completa
   de diretivas de formatação, veja Comportamento de strftime() e
   strptime().

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.

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

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

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

tzinfo.utcoffset(dt)

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

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

      return CONSTANT                 # 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.

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

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

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

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

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

      def dst(self, dt):
          # 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)

   Retorna o fuso horário correspondente para o objeto "datetime"
   *dt*, como uma string. Nada a respeito de nomes das string é
   definido pelo módulo "datetime", e não existe requisito que ele
   signifique qualquer coisa em particular. Por exemplo, "GMT", "UTC",
   "-500", "-5:00", "EDT", "US/Eastern", "America/New York" são todos
   retornos válidos. Retorna "None" se o nome da string não é
   conhecido. Perceba que isto é um método ao invés de uma string
   fixa, primariamente porque algumas subclasses "tzinfo" desejarão
   retornar diferentes nomes dependendo do valor específico de *dt*
   passado, especialmente se a classe "tzinfo" estiver contabilizando
   horário de verão.

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

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

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

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

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

tzinfo.fromutc(dt)

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

   Maioria das subclasses "tzinfo" deve ser capaz de herdar a
   implementação padrão "fromutc()" sem problemas. É forte o
   suficiente para manipular fuso horários com diferença fixa, e fuso
   horários contabilizando tanto hora padrão como horário de verão, e
   o segundo mesmo se a transição para horário de verão for diferente
   em anos diferentes. Um exemplo de um fuso horário onde a
   implementação padrão "fromutc()" pode acabar não lidando
   corretamente todos os casos, é quando a diferença padrão (a partir
   do UTC) depende da data e hora específica passada, a qual pode
   ocorrer por razões políticas. As implementações padrões de
   "astimezone()" e "fromutc()" podem não produzir o resultado
   desejado se o resultado é uma das horas do momento que a diferença
   padrão muda.

   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
   # http://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

Quando o horário de verão termina (o "fim" da linha), existe um
problema potencialmente pior: existe uma hora que não pode ser
pronunciada inequivocamente em hora local na parede: a última hora do
horário de verão. No oriente, essa hora é na forma de 5:MM UTC no dia
que o horário de verão acaba. A hora local na parede salta de 1:59
(horário de verão) de volta para 1:00 (hora padrão) de novo. Horário
local na forma 1:MM são ambíguos. "astimezone()" então imita o
comportamento do relógio local através do mapeamento de duas horas UTC
adjacentes na mesma hora local. No ocidente por exemplo, horas UTC da
forma 5:MM e 6:MM ambas mapeiam para 1:MM quando convertidas para
ocidente, mas horas anteriores tem o atributo "fold" definido para 0 e
horas posteriores tem o mesmo definido para 1. Por exemplo, na
transição de volta para o outono de 2016, nós obtivemos:

   >>> 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 que instâncias "datetime" que se diferenciam apenas pelo valor do
atributo "fold" são consideradas iguais em comparações.

Aplicações que não podem suportar horário na parede com ambiguidades
devem explicitamente verificar o valor do atributo "fold" ou evitar o
uso de subclasses "tzinfo" híbridas; não existem ambiguidades ao usar
"timezone", ou qualquer outra subclasse "tzinfo" com diferença fixa
(tal como uma classe representando apenas o horário padrão na costa
leste EST (diferença fixa de -5 horas), ou apenas o horário de verão
na costa leste EDT (diferença fixa de -4 horas)).

Ver também:

  dateutil.tz
     O módulo "datetime" possui uma classe "timezone" básica (para o
     tratamento de diferenças temporárias fixas arbitrárias do UTC) e
     seu atributo "timezone.utc" (uma instância do fuso horário UTC).

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

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


Objetos "timezone"
==================

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

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

class datetime.timezone(offset, name=None)

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

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

   Novo na versão 3.2.

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

timezone.utcoffset(dt)

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

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

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

timezone.tzname(dt)

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

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

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

timezone.dst(dt)

   Sempre retorna "None".

timezone.fromutc(dt)

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

Atributos de classe:

timezone.utc

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


Comportamento de "strftime()" e "strptime()"
============================================

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

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

O tabela abaixo fornece uma comparação de alto nível de "strftime()"
versus "strptime()":

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


Códigos de formatação para "strftime()" e "strptime()"
------------------------------------------------------

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

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

O conjunto completo de códigos de formatação suportados varia através
de plataformas, porque o Python chama a função C "strftime()" da
biblioteca na plataforma, e variações de plataforma são comuns. Para
ver o conjunto completo de códigos de formatação suportados na sua
plataforma, consulte a documentação de *strftime(3)*.

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


Detalhes técnicos
-----------------

Falando de forma abrangente, "d.strftime(fmt)" atua como
"time.strftime(fmt, d.timetuple())" do módulo "time", apesar que nem
todos os objetos suportam um método "timetuple()".

Para o método de classe "datetime.strptime()", o valor padrão é
"1900-01-01T00:00:00.000": quaisquer componentes não especificados no
formato da string serão puxados do valor padrão. [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".

Para objetos "time", o código de formatação para ano, mês, e dia não
deve ser usado, devido ao fato que objetos "time" não possuem tais
valores. Se eles forem usados de mesmo assim, "1900" é substituído
pelo ano, e "1" pelo mês e dia.

Para objetos "date", os códigos de formatação para horas, minutos,
segundos, e microssegundos não devem ser usados, como objetos "date"
não tem tais valores. Se eles forem mesmo assim, "0" é substituído no
lugar deles.

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. Devido ao fato que o formato depende da localidade atual, deve-se
   tomar cuidado ao fazer suposições sobre o valor na saída.
   Ordenamento de campos irá variar (por exemplo, "mês/dia/ano" versus
   "dia/mês/ano"), e a saída pode conter caracteres Unicode que foram
   codificados usando a codificação padrão da localidade (por exemplo,
   se a localidade atual é "ja_JP", a codificação padrão pode ser
   qualquer uma dentre "eucJP", "SJIS", ou "utf-8"; utilize
   "locale.getlocale()" para determinar a codificação atual da
   localidade).

2. O método "strptime()" pode interpretar anos no intervalo [1, 9999],
   mas anos < 1000 devem ser preenchidos com 0 para ter 4 dígitos de
   extensão.

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

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

3. Quando usado com o método "strptime()", a diretiva "%p" apenas
   afeta as horas na saída se a diretiva "%I" é usada para analisar a
   hora.

4. Ao contrário do módulo "time", o módulo "datetime" não suporta
   segundos bissextos.

5. Quando usado com o método "strptime()", a diretiva "%f" aceita de 1
   a 6 dígitos, e nenhum preenchimento a direita. "%f" é uma extensão
   para o conjunto de formatação de caracteres no padrão C (mas
   implementado separadamente em objetos datetime, e portando sempre
   disponível).

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

   Para um objeto consciente:

   "%z"
      "utcoffset()" é transformado em uma string no formato
      "±HHMM[SS[.ffffff]]", onde "HH" é uma string de 2 dígitos
      fornecendo a diferença de UTC em horas, "MM" é uma string de 2
      dígitos fornecendo a diferença de UTC em minutos, "SS" é uma
      string de 2 dígitos fornecendo a diferença de UTC em segundos e
      "ffffff" é uma string de 6 dígitos fornecendo a diferença de UTC
      em micro segundos. A parte "ffffff" é omitida quando a diferença
      é um número inteiro de segundos, e as partes "ffffff" e "SS" são
      omitidas quando a diferença é um número inteiro de minutos. Por
      exemplo, se "utcoffset()" retorna "timedelta(hours=-3,
      minutes=-30)", "%z" é substituído pela string "'-0330'".

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

   Alterado na versão 3.7: Quando a diretiva "%z" é fornecida para o
   método "strptime()", as diferenças UTC podem ter um separador de
   vírgula como um separador entre horas, minutos e segundos. Por
   exemplo, "'+01:00:00'" será interpretado como uma diferença de uma
   hora. Adicionalmente, fornecer "'Z'" é idêntico a "'+00:00'".

   "%Z"
      If "tzname()" returns "None", "%Z" is replaced by an empty
      string. Otherwise "%Z" is replaced by the returned value, which
      must be a string.

   Alterado na versão 3.2: Quando a diretiva "%z" é fornecida para o
   método "strptime()", um objeto consciente "datetime" será
   produzido. O "tzinfo" do resultado será definido para uma instância
   "timezone".

7. Quando for usado com o método "strptime()", "%U" e "%W" são usados
   apenas em cálculos quando o dia da semana e o ano do calendário
   ("%Y") são especificados.

8. Similar a "%U" e "%W", "%V" é usado apenas em cálculos quando o dia
   da semana e o ano ISO ("%G") são especificados em uma string de
   formatação "strptime()". Perceba também que "%G" e "%Y" não são
   intercambiáveis.

9. Quando for usado com o método "strptime()", o zero precedente é
   opcional para formatos "%d", "%m", "%H", "%I", "%M", "%S", "%J",
   "%U", "%W", e "%V". O formato "%y" não requer um zero precedente.

-[ Notas de Rodapé ]-

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

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

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

[4] Passar "datetime.strptime('Feb 29', '%b %d')" irá falhar como
    "1900" não é um ano bissexto.
