Python datetime

Quantos dias faltam para o Natal? Quando vence um boleto pago hoje com prazo de 30 dias? Quantos anos tem quem nasceu em 20/10/2000? A que horas em Lisboa começa uma reunião marcada para as 15h em São Paulo? Fazer essas contas "na mão" é cheio de armadilhas: meses de 28, 30 e 31 dias, anos bissextos, fusos horários. O módulo datetime ("data e hora"), que vem com o Python, já sabe tudo isso.

Todos os programas desta aula rodaram no Python 3.14 do computador fictício da Ana (usuária ana, computador notebook, fuso de São Paulo), na pasta pessoal dela, com python3 arquivo.py. Os que usam a data de "hoje" rodaram em 18/10/2026; no seu computador, essas saídas vão mostrar o seu dia e a sua hora.

A ideia: o calendário e o relógio da parede

Na cozinha da Ana há um calendário (que mostra o dia: 18 de outubro de 2026) e um relógio (que mostra a hora: 14h30). Juntando os dois, ela sabe o momento exato: 18/10/2026 às 14h30. E quando ela diz "o bolo leva 40 minutos" ou "o boleto vence em 30 dias", ela fala de uma duração, um pedaço de tempo que dá para somar a um momento.

Os quatro moram no módulo datetime (aula Módulos e import). O jeito mais prático é importar só o que você vai usar: from datetime import date, timedelta.

1. Uma data: date

from datetime import date

natal = date(2026, 12, 25)
print(natal)
print(natal.day, natal.month, natal.year)
print(natal.weekday())
print(type(natal))

$ python3 criar.py
2026-12-25
25 12 2026
4                                « 0 = segunda, 1 = terça… 4 = sexta-feira
<class 'datetime.date'>

from datetime import date

Do módulo datetime, traz o tipo date.

date(2026, 12, 25)

Cria a data. A ordem é sempre ano, mês, dia (do maior para o menor), ao contrário do nosso costume de escrever 25/12/2026. Os números vão sem zero na frente: date(2026, 8, 5), nunca 08 (veja Quando dá errado).

print(natal)

Mostra no formato internacional AAAA-MM-DD (ano-mês-dia). O formato brasileiro vem na seção 3.

.day, .month, .year

As partes da data, como números inteiros: dia, mês, ano.

.weekday()

O dia da semana como número: 0 é segunda-feira e 6 é domingo. O Natal de 2026 cai numa sexta.

No modo interativo, uma data aparece de um jeito um pouco diferente: o >>> mostra o valor "como se escreve em Python", e o print mostra o valor "para gente ler":

$ python3 -q
>>> from datetime import date, timedelta
>>> natal = date(2026, 12, 25)
>>> natal
datetime.date(2026, 12, 25)
>>> print(natal)
2026-12-25
>>> timedelta(days=30)
datetime.timedelta(days=30)
>>> natal - date(2026, 10, 18)
datetime.timedelta(days=68)
>>> date(2026, 10, 18) < natal
True
>>> exit()

As duas últimas linhas já mostram o que vem a seguir: subtrair datas dá uma duração, e datas se comparam com <, > e == como números (a data anterior é a "menor").

2. Agora: today() e now()

from datetime import date, datetime

print(date.today())
print(datetime.now())

$ python3 hoje.py
2026-10-18
2026-10-18 12:18:48.599638          « horas:minutos:segundos.microssegundos

• date.today() é a data de hoje, segundo o relógio do computador.
• datetime.now() é a data e a hora deste instante, até os microssegundos (milionésimos de segundo).

from datetime import date, datetime

print("Hoje:", date.today())
print("Agora:", datetime.now())

3. O formato brasileiro: strftime

Para mostrar uma data do jeito que a gente escreve, use o método strftime (de string format time, "formatar o tempo como texto"). Você passa um molde, em que cada código com % vira uma parte da data:

from datetime import datetime

consulta = datetime(2026, 11, 3, 14, 30)
print(consulta)
print(consulta.strftime("%d/%m/%Y"))
print(consulta.strftime("%d/%m/%Y às %H:%M"))
print(consulta.strftime("%d/%m/%y"))
print(f"Consulta: {consulta:%d/%m/%Y %H:%M}")
print(consulta.isoformat())

$ python3 formato.py
2026-11-03 14:30:00
03/11/2026
03/11/2026 às 14:30
03/11/26                         « %y: o ano com 2 dígitos
Consulta: 03/11/2026 14:30       « o mesmo molde dentro de uma f-string
2026-11-03T14:30:00              « o formato internacional (ISO 8601)

Tudo o que não começa com % (as barras, o "às", os espaços) é copiado como está. O mesmo molde funciona dentro de uma f-string, depois dos dois-pontos: {consulta:%d/%m/%Y}.

from datetime import date

natal = date(2026, 12, 25)
print("Natal:", natal)

from datetime import date

natal = date(2026, 12, 25)
print("Natal:", natal.strftime("%d/%m/%Y"))

4. Lendo uma data digitada: strptime

O caminho contrário: a pessoa digita 25/12/2026 (um texto) e o programa precisa de uma data. Para isso existe datetime.strptime (de string parse time, "interpretar o texto como tempo"), com o mesmo molde:

from datetime import datetime

texto = input("Data do vencimento (dd/mm/aaaa): ")
vencimento = datetime.strptime(texto, "%d/%m/%Y").date()
print("Entendi:", vencimento)
print("Dia da semana (0 = segunda):", vencimento.weekday())

$ python3 ler_data.py
Data do vencimento (dd/mm/aaaa): 25/12/2026
Entendi: 2026-12-25
Dia da semana (0 = segunda): 4

datetime.strptime(texto, "%d/%m/%Y")

Lê o texto seguindo o molde e devolve um datetime (com a hora 00:00, porque o texto não tinha hora).

.date()

Fica só com a data, sem a hora. Útil quando a hora não interessa.

O molde tem de bater exatamente com o texto. Se a pessoa digitar com traços:

$ python3 ler_data.py
Data do vencimento (dd/mm/aaaa): 25-12-2026
Traceback (most recent call last):
  File "/home/ana/ler_data.py", line 4, in <module>
    vencimento = datetime.strptime(texto, "%d/%m/%Y").date()
                 ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/_strptime.py", line 815, in _strptime_datetime_datetime
    tt, fraction, gmtoff_fraction = _strptime(data_string, format)
                                    ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/_strptime.py", line 555, in _strptime
    raise ValueError("time data %r does not match format %r" %
                     (data_string, format))
ValueError: time data '25-12-2026' does not match format '%d/%m/%Y'

O traceback é comprido porque o erro acontece dentro do módulo (_strptime.py, um arquivo do próprio Python). Leia a primeira parte (a sua linha 4) e a última: ValueError: time data '25-12-2026' does not match format '%d/%m/%Y', "o texto '25-12-2026' não bate com o molde '%d/%m/%Y'". Num programa de verdade, você trata esse erro com try e except e pede a data de novo.

5. Contas com datas: timedelta

Quantos dias faltam

Subtrair duas datas dá uma duração, um timedelta. O número de dias está em .days:

from datetime import date

hoje = date(2026, 10, 18)
natal = date(2026, 12, 25)
falta = natal - hoje
print(falta)
print(type(falta))
print(f"Faltam {falta.days} dias para o Natal.")

$ python3 dias.py
68 days, 0:00:00                 « 68 dias e 0 horas
<class 'datetime.timedelta'>
Faltam 68 dias para o Natal.

Se a data já passou, a diferença é negativa. Um boleto que venceu em 10/10:

from datetime import date

hoje = date(2026, 10, 18)
vencimento = date(2026, 10, 10)
diferenca = vencimento - hoje
print(diferenca)
print(diferenca.days)
if vencimento < hoje:
    print(f"Boleto vencido há {-diferenca.days} dias.")
else:
    print(f"Faltam {diferenca.days} dias para o vencimento.")

$ python3 boleto.py
-8 days, 0:00:00
-8
Boleto vencido há 8 dias.

from datetime import date

hoje = date(2026, 10, 18)
aniversario = date(2026, 11, 30)
print("Faltam ? dias para o aniversário.")

from datetime import date

hoje = date(2026, 10, 18)
aniversario = date(2026, 11, 30)
falta = aniversario - hoje
print(f"Faltam {falta.days} dias para o aniversário.")

Somar um prazo

Para "daqui a 30 dias", some uma duração criada com timedelta(days=30). O datetime cuida da virada do mês (e do ano):

from datetime import date, timedelta

compra = date(2026, 10, 18)
vence = compra + timedelta(days=30)
print("Compra:", compra.strftime("%d/%m/%Y"))
print("Vence: ", vence.strftime("%d/%m/%Y"))
print("Uma semana antes:", (vence - timedelta(weeks=1)).strftime("%d/%m/%Y"))

$ python3 vencimento.py
Compra: 18/10/2026
Vence:  17/11/2026               « outubro tem 31 dias: o Python sabe
Uma semana antes: 10/11/2026

O timedelta aceita weeks (semanas), days (dias), hours (horas), minutes (minutos) e seconds (segundos), sozinhos ou juntos. Com horas, use datetime (data e hora):

from datetime import datetime, timedelta

inicio = datetime(2026, 10, 18, 22, 15)
filme = timedelta(hours=2, minutes=20)
fim = inicio + filme
print("O filme acaba:", fim.strftime("%d/%m/%Y %H:%M"))
print(filme)
print(filme.total_seconds(), "segundos")

$ python3 duracao.py
O filme acaba: 19/10/2026 00:35  « passou da meia-noite: virou o dia
2:20:00
8400.0 segundos

E a diferença entre dois momentos do mesmo dia dá horas e minutos. A Ana conferiu o expediente:

from datetime import datetime

entrada = datetime(2026, 10, 18, 8, 0)
saida = datetime(2026, 10, 18, 17, 45)
trabalhado = saida - entrada
print(trabalhado)
print(trabalhado.total_seconds() / 3600, "horas")

$ python3 expediente.py
9:45:00
9.75 horas                       « 3600 segundos = 1 hora

from datetime import date, timedelta

compra = date(2026, 10, 18)
print("Compra:", compra.strftime("%d/%m/%Y"))

from datetime import date, timedelta

compra = date(2026, 10, 18)
print("Compra:", compra.strftime("%d/%m/%Y"))
vence = compra + timedelta(days=45)
print("Vence:", vence.strftime("%d/%m/%Y"))

6. A idade a partir da data de nascimento

Parece fácil: ano de hoje menos ano do nascimento. Mas quem ainda não fez aniversário este ano tem um ano a menos. A regra completa:

from datetime import date, datetime

hoje = date(2026, 10, 18)
texto = input("Data de nascimento (dd/mm/aaaa): ")
nascimento = datetime.strptime(texto, "%d/%m/%Y").date()
idade = hoje.year - nascimento.year
if (hoje.month, hoje.day) < (nascimento.month, nascimento.day):
    idade -= 1
print(f"Você tem {idade} anos.")

$ python3 idade.py
Data de nascimento (dd/mm/aaaa): 20/10/2000
Você tem 25 anos.                « faz 26 só daqui a dois dias
$ python3 idade.py
Data de nascimento (dd/mm/aaaa): 18/10/2000
Você tem 26 anos.                « aniversário hoje: já conta
$ python3 idade.py
Data de nascimento (dd/mm/aaaa): 03/05/1990
Você tem 36 anos.

hoje.year - nascimento.year

A conta "de cabeça": 2026 − 2000 = 26.

(hoje.month, hoje.day)

Uma tupla com o mês e o dia de hoje: (10, 18).

< (nascimento.month, nascimento.day)

Tuplas se comparam item por item: primeiro o mês; se o mês empata, o dia. (10, 18) < (10, 20) é True: o aniversário deste ano ainda não chegou.

idade -= 1

Então tira um ano.

from datetime import date

hoje = date(2026, 10, 18)
nascimento = date(2000, 10, 20)
dias = (hoje - nascimento).days
print(dias, "dias")
print("Idade (dias // 365):", dias // 365)

$ python3 idade_errada.py
9494 dias
Idade (dias // 365): 26          « errado: faltam 2 dias para os 26

7. Só a hora: time

O tipo time guarda uma hora do dia, sem data, como o horário em que a padaria abre. Com datetime.combine, você junta uma data e uma hora num momento:

from datetime import date, time, datetime

abre = time(6, 30)
print(abre)
print(abre.hour, abre.minute)
print(abre.strftime("%H:%M"))
dia = date(2026, 10, 19)
print(datetime.combine(dia, abre))

$ python3 hora.py
06:30:00
6 30
06:30
2026-10-19 06:30:00

Um time sozinho não aceita somar durações (não sabe o que fazer quando passa da meia-noite). Para contas com horas, use datetime, como no filme da seção 5.

8. Fusos horários: zoneinfo

Às 15h em São Paulo, que horas são em Lisboa? Depende da época do ano, por causa do horário de verão de lá. O módulo zoneinfo (desde o Python 3.9) conhece as regras de cada lugar do mundo, pelo nome oficial do fuso, como "America/Sao_Paulo":

from datetime import datetime
from zoneinfo import ZoneInfo

sp = ZoneInfo("America/Sao_Paulo")
reuniao = datetime(2026, 10, 18, 15, 0, tzinfo=sp)
print(reuniao)
print("Lisboa:", reuniao.astimezone(ZoneInfo("Europe/Lisbon")))
print("Tóquio:", reuniao.astimezone(ZoneInfo("Asia/Tokyo")))
print("Manaus:", reuniao.astimezone(ZoneInfo("America/Manaus")).strftime("%H:%M"))

$ python3 fuso.py
2026-10-18 15:00:00-03:00        « -03:00: três horas atrás do horário universal
Lisboa: 2026-10-18 19:00:00+01:00
Tóquio: 2026-10-19 03:00:00+09:00   « em Tóquio já é o dia seguinte
Manaus: 14:00

ZoneInfo("America/Sao_Paulo")

O fuso de São Paulo (o horário de Brasília). Os nomes são do tipo "Continente/Cidade", em inglês e com sublinhado no lugar do espaço.

tzinfo=sp

Diz a que fuso pertence esse momento. Um datetime com fuso é chamado de "consciente" (aware); sem fuso, de "ingênuo" (naive).

-03:00

A diferença para o horário universal (UTC). O Brasil não tem horário de verão desde 2019, então São Paulo fica em −03:00 o ano todo. Lisboa, em outubro de 2026, ainda está no horário de verão (+01:00).

.astimezone(outro_fuso)

O mesmo instante, visto no relógio de outro lugar.

Para pegar a hora de agora já com o fuso, passe o fuso para o now(). Sem fuso, o now() devolve um momento ingênuo:

from datetime import datetime
from zoneinfo import ZoneInfo

agora = datetime.now(ZoneInfo("America/Sao_Paulo"))
print(agora.strftime("%d/%m/%Y %H:%M %Z"))
print(datetime.now().tzinfo)

$ python3 fuso_agora.py
18/10/2026 12:18 -03             « %Z: o nome curto do fuso
None                             « sem fuso: tzinfo é None

from datetime import datetime
from zoneinfo import ZoneInfo

chamada = datetime(2026, 10, 18, 10, 0, tzinfo=ZoneInfo("America/Sao_Paulo"))
print("São Paulo:", chamada.strftime("%H:%M"))

from datetime import datetime
from zoneinfo import ZoneInfo

chamada = datetime(2026, 10, 18, 10, 0, tzinfo=ZoneInfo("America/Sao_Paulo"))
print("São Paulo:", chamada.strftime("%H:%M"))
lisboa = chamada.astimezone(ZoneInfo("Europe/Lisbon"))
print("Lisboa:", lisboa.strftime("%H:%M"))

9. Nomes de dia e mês em português

Os códigos %A (dia da semana) e %B (mês) mostram nomes. Mas, sem configuração, eles saem em inglês, mesmo num computador em português:

from datetime import date

d = date(2026, 10, 18)
print(d.strftime("%A, %d de %B de %Y"))

$ python3 nomes_ingles.py
Sunday, 18 de October de 2026

O Python começa sempre com o "idioma neutro" (o locale C). Para usar o idioma configurado no sistema, que no computador da Ana é o português do Brasil (pt_BR.UTF-8), chame locale.setlocale no começo do programa:

import locale
from datetime import date

locale.setlocale(locale.LC_ALL, "")
d = date(2026, 10, 18)
print(d.strftime("%A, %d de %B de %Y"))
print(d.strftime("%a %d/%b"))

$ python3 nomes_locale.py
domingo, 18 de outubro de 2026
dom 18/out

import locale

O módulo das configurações regionais (idioma, moeda, formato de números).

locale.setlocale(locale.LC_ALL, "")

LC_ALL = "todas as categorias"; o texto vazio "" quer dizer "use o que o sistema está usando". No terminal da Ana, isso é o pt_BR.UTF-8.

Quando o programa precisa mostrar português em qualquer computador (e no editor), o jeito mais seguro é ter a sua própria lista de nomes e usar o número do dia e do mês como posição (aula Acessando Itens):

from datetime import date

DIAS = ["segunda-feira", "terça-feira", "quarta-feira", "quinta-feira",
        "sexta-feira", "sábado", "domingo"]
MESES = ["janeiro", "fevereiro", "março", "abril", "maio", "junho", "julho",
         "agosto", "setembro", "outubro", "novembro", "dezembro"]
d = date(2026, 10, 18)
print(f"{DIAS[d.weekday()]}, {d.day} de {MESES[d.month - 1]} de {d.year}")

$ python3 nomes_lista.py
domingo, 18 de outubro de 2026

d.weekday() vai de 0 (segunda) a 6 (domingo), a mesma ordem da lista DIAS. Os meses vão de 1 a 12, mas as posições da lista começam em 0: por isso o - 1. O editor mostrou a mesma linha.

Formas diferentes de mostrar e de ler datas

Quando dá errado

import datetime

print(datetime.now())

$ python3 erro_modulo.py
Traceback (most recent call last):
  File "/home/ana/erro_modulo.py", line 3, in <module>
    print(datetime.now())
          ^^^^^^^^^^^^
AttributeError: module 'datetime' has no attribute 'now'

from datetime import date

print(date(2026, 2, 30))

$ python3 erro_dia.py
Traceback (most recent call last):
  File "/home/ana/erro_dia.py", line 3, in <module>
    print(date(2026, 2, 30))
          ~~~~^^^^^^^^^^^^^
ValueError: day 30 must be in range 1..28 for month 2 in year 2026

$ python3 erro_mes.py
Traceback (most recent call last):
  File "/home/ana/erro_mes.py", line 3, in <module>
    print(date(2026, 13, 1))
          ~~~~^^^^^^^^^^^^^
ValueError: month must be in 1..12, not 13

from datetime import date

print(date(2026, 08, 5))

$ python3 erro_zero.py
  File "/home/ana/erro_zero.py", line 3
    print(date(2026, 08, 5))
                     ^
SyntaxError: leading zeros in decimal integer literals are not permitted; use an 0o prefix for octal integers

from datetime import datetime

print(datetime.strptime("25/12/2026 10:00", "%d/%m/%Y"))

$ python3 erro_sobra.py
Traceback (most recent call last):
  File "/home/ana/erro_sobra.py", line 3, in <module>
    print(datetime.strptime("25/12/2026 10:00", "%d/%m/%Y"))
          ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/_strptime.py", line 815, in _strptime_datetime_datetime
    tt, fraction, gmtoff_fraction = _strptime(data_string, format)
                                    ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/_strptime.py", line 558, in _strptime
    raise ValueError("unconverted data remains: %s" %
                      data_string[found.end():])
ValueError: unconverted data remains:  10:00

from datetime import date

print(date(2026, 10, 18) + 30)

$ python3 erro_soma.py
Traceback (most recent call last):
  File "/home/ana/erro_soma.py", line 3, in <module>
    print(date(2026, 10, 18) + 30)
          ~~~~~~~~~~~~~~~~~~~^~~~
TypeError: unsupported operand type(s) for +: 'datetime.date' and 'int'

$ python3 erro_meses.py
Traceback (most recent call last):
  File "/home/ana/erro_meses.py", line 3, in <module>
    print(timedelta(months=1))
          ~~~~~~~~~^^^^^^^^^^
TypeError: __new__() got an unexpected keyword argument 'months'

from datetime import datetime

consulta = datetime(2026, 11, 3, 14, 30)
print(consulta.strftime("%d/%M/%Y"))

$ python3 erro_minuto.py
03/30/2026                       « 30 é o minuto, não o mês!

from zoneinfo import ZoneInfo

print(ZoneInfo("America/SaoPaulo"))

$ python3 erro_fuso_nome.py
Traceback (most recent call last):
  File "/usr/lib/python3.14/zoneinfo/_common.py", line 12, in load_tzdata
    path = resources.files(package_name).joinpath(resource_name)
           ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
…                                « (linhas de dentro da biblioteca, cortadas aqui)
ModuleNotFoundError: No module named 'tzdata'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/ana/erro_fuso_nome.py", line 3, in <module>
    print(ZoneInfo("America/SaoPaulo"))
          ~~~~~~~~^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/zoneinfo/_common.py", line 29, in load_tzdata
    raise ZoneInfoNotFoundError(f"No time zone found with key {key}")
zoneinfo._common.ZoneInfoNotFoundError: 'No time zone found with key America/SaoPaulo'

from datetime import datetime
from zoneinfo import ZoneInfo

prazo = datetime(2026, 10, 18, 18, 0)
agora = datetime(2026, 10, 18, 15, 0, tzinfo=ZoneInfo("America/Sao_Paulo"))
print(agora < prazo)

$ python3 erro_naive.py
Traceback (most recent call last):
  File "/home/ana/erro_naive.py", line 6, in <module>
    print(agora < prazo)
          ^^^^^^^^^^^^^
TypeError: can't compare offset-naive and offset-aware datetimes

Referência rápida

Exercícios

Missão final: a idade certa

from datetime import date, datetime

hoje = date(2026, 10, 18)
texto = input("Data de nascimento (dd/mm/aaaa): ")
nascimento = datetime.strptime(texto, "%d/%m/%Y").date()
idade = (hoje - nascimento).days // 365
print(f"Você tem {idade} anos.")

from datetime import date, datetime

hoje = date(2026, 10, 18)
texto = input("Data de nascimento (dd/mm/aaaa): ")
nascimento = datetime.strptime(texto, "%d/%m/%Y").date()
idade = hoje.year - nascimento.year
if (hoje.month, hoje.day) < (nascimento.month, nascimento.day):
    idade -= 1
print(f"Você tem {idade} anos.")

Depois de cumprir, troque a entrada por 18/10/2000 (aniversário "hoje": 26 anos) e por 29/02/2000, uma data que só existe em ano bissexto. E, no seu terminal, troque date(2026, 10, 18) por date.today() para ter a idade de verdade.

Resumo

• O módulo datetime tem quatro tipos: date (data), time (hora), datetime (data e hora) e timedelta (duração). Importe com from datetime import ….
• Datas se criam na ordem ano, mês, dia, sem zeros na frente: date(2026, 8, 5).
• date.today() e datetime.now() mudam a cada execução: use datas fixas para testar.
• strftime("%d/%m/%Y") mostra no formato brasileiro; strptime(texto, "%d/%m/%Y") lê. O molde tem de bater com o texto. %m é mês, %M é minuto.
• Data menos data dá um timedelta (.days); data mais timedelta(days=30) dá outra data. Não existe timedelta de meses.
• Idade: ano menos ano, e menos 1 se o aniversário deste ano ainda não chegou. Dividir os dias por 365 erra.
• Fusos: ZoneInfo("America/Sao_Paulo"), tzinfo=… e .astimezone(…). Não misture momentos com e sem fuso.
• Nomes de mês e dia saem em inglês; locale.setlocale(locale.LC_ALL, "") usa o idioma do sistema (no terminal; no editor, não). Para português em qualquer lugar, use a sua lista de nomes.