🇯🇵 日本語 | 🇺🇸 English | 🇪🇸 Español | 🇵🇹 Português | 🇹🇭 ไทย | 🇨🇳 中文

Domine Datas e Horas em Python com o Módulo datetime!

Para executar Python no prompt de comando ou PowerShell no seu PC, é necessário baixar e instalar o Python.
Se ainda não o fez, consulte o artigo Instalação do Python e configuração do ambiente de desenvolvimento para instalar o Python.

Ao desenvolver sites e aplicativos, você frequentemente encontrará situações em que precisa manipular datas e horas, como "exibir a hora atual", "registrar a data de postagem de um artigo" ou "calcular o tempo restante para uma promoção". É nessas horas que o módulo datetime, integrado ao Python, se torna um grande aliado.

Neste artigo, explicaremos desde o básico do módulo datetime até algumas técnicas um pouco mais avançadas, com exemplos de código que até mesmo iniciantes podem copiar e colar para experimentar e ver "funcionar". Vamos mergulhar no mundo das datas e horas! 🚀

O Básico do Módulo datetime

Vamos começar com a preparação para usar o módulo datetime e sua funcionalidade mais básica: "obter a data e a hora atuais".

Importando o Módulo

Para usar o módulo datetime, primeiro você precisa importá-lo (carregá-lo) no início do seu código. Sem isso, o Python perguntará: "O que é datetime?".

import datetime

Obtendo a Data e Hora Atuais

Obter a data e a hora do momento atual é muito simples. Basta chamar `datetime.datetime.now()`.

import datetime

# Obter a data e hora atuais
now = datetime.datetime.now()
print(now)

# Exemplo de saída: 2025-07-11 07:42:15.123456

Se você não precisar da hora e quiser apenas a data de hoje, use `datetime.date.today()`.

import datetime

# Obter apenas a data de hoje
today = datetime.date.today()
print(today)

# Exemplo de saída: 2025-07-11

Acessando os Elementos Individuais de Data e Hora

Do objeto `datetime` que você obteve, é possível extrair informações individuais como ano, mês, dia, hora, minuto e segundo. Isso é útil, por exemplo, quando você quer exibir algo como "O ano atual é 2025".

import datetime

now = datetime.datetime.now()

print(f"Ano: {now.year}")
print(f"Mês: {now.month}")
print(f"Dia: {now.day}")
print(f"Hora: {now.hour}")
print(f"Minuto: {now.minute}")
print(f"Segundo: {now.second}")
print(f"Microssegundo: {now.microsecond}")

Criando uma Data e Hora Específicas

Claro, além de obter a hora atual, você também pode criar objetos que representam uma data e hora específicas no passado ou no futuro. Isso é usado para especificar datas como seu aniversário ou o dia de lançamento de um serviço.

import datetime

# Especificar 1 de janeiro de 2026, às 9:30:00
specific_datetime = datetime.datetime(2026, 1, 1, 9, 30, 0)
print(specific_datetime)

# Saída: 2026-01-01 09:30:00

Formatando Datas e Horas para Melhor Legibilidade

Um formato como `2025-07-11 07:42:15` não é ruim, mas em um site, você pode querer exibi-lo de forma mais clara, como "11 de julho de 2025, 07:42". É aí que o método `strftime()` entra em cena.

Convertendo para String com um Formato Personalizado usando strftime()

`strftime()` é a abreviação de "string format time" (formatar tempo para string), e ele converte um objeto `datetime` em uma string com um formato específico. Para especificar o formato, você usa "códigos de formatação" como `%Y` ou `%m`.

import datetime
import locale

# Define a localidade para português para nomes de meses e dias
# Pode exigir configuração no sistema ('pt_BR', 'pt_BR.UTF-8', 'Portuguese_Brazil.1252')
try:
    locale.setlocale(locale.LC_TIME, 'pt_BR.UTF-8')
except locale.Error:
    print("Localidade 'pt_BR.UTF-8' não suportada, usando o padrão.")

now = datetime.datetime.now()

# Converte para string especificando um formato
# '%d de %B de %Y' é um formato comum em português
formatted_string = now.strftime("%d de %B de %Y, %H:%M:%S")
print(formatted_string)

# Exemplo de saída: 11 de julho de 2025, 07:42:15

Aqui estão alguns dos códigos de formatação mais usados:

Convertendo uma String em Data e Hora com strptime()

Por outro lado, às vezes você pode querer converter dados em string como "11/07/2025" em um objeto `datetime` com o qual seu programa possa trabalhar. Nesse caso, use o método `strptime()`, que significa "string parse time" (analisar tempo de string).

Importante: Ao usar `strptime()`, é crucial que o formato da string original e o código de formato que você especifica correspondam perfeitamente. Se não corresponderem, você receberá um erro, então tome cuidado.

import datetime

date_string = "11 de julho de 2025"

# Para que o mês 'julho' seja reconhecido, você pode precisar definir a localidade
# import locale
# locale.setlocale(locale.LC_TIME, 'pt_BR.UTF-8')

# Converte a string para um objeto datetime especificando o formato
# Neste exemplo, como é apenas uma data, torna-se um objeto date
date_obj = datetime.datetime.strptime(date_string, "%d de %B de %Y").date()

print(date_obj)
print(type(date_obj))

# Saída:
# 2025-07-11
# <class 'datetime.date'>

Avançado: Vamos Fazer Cálculos com Datas e Horas!

O verdadeiro poder do módulo datetime está na sua capacidade de realizar cálculos com datas e horas facilmente. Você pode fazer operações intuitivas como "Qual será a data daqui a uma semana?" ou "Quantos dias faltam para a promoção acabar?" usando objetos `timedelta`.

Expressando Diferenças de Tempo com timedelta

Um `timedelta` é um objeto que representa uma duração, a diferença entre duas datas ou horas. Você o cria especificando dias, segundos, microssegundos, etc.

import datetime

now = datetime.datetime.now()
print(f"Hora atual: {now.strftime('%Y-%m-%d %H:%M')}")

# Calcular uma semana depois
uma_semana_depois = now + datetime.timedelta(weeks=1)
print(f"Daqui a 1 semana: {uma_semana_depois.strftime('%Y-%m-%d %H:%M')}")

# Calcular 3 dias atrás
tres_dias_atras = now - datetime.timedelta(days=3)
print(f"3 dias atrás:  {tres_dias_atras.strftime('%Y-%m-%d %H:%M')}")

# Calcular 10 horas e 30 minutos a partir de agora
dez_horas_depois = now + datetime.timedelta(hours=10, minutes=30)
print(f"Daqui a 10h 30min: {dez_horas_depois.strftime('%Y-%m-%d %H:%M')}")

Calculando a Diferença Entre Duas Datas

Quando você subtrai um objeto `datetime` de outro, o resultado é um objeto `timedelta`. Você pode usar isso para calcular o número de dias restantes até uma data específica, por exemplo.

import datetime

# Data de hoje
hoje = datetime.date.today()

# Data alvo (por exemplo, Ano Novo de 2026)
ano_novo_2026 = datetime.date(2026, 1, 1)

# Calcular a diferença entre as duas datas
delta = ano_novo_2026 - hoje

print(f"Faltam {delta.days} dias para o Ano Novo de 2026.")

Ponto de Atenção: A Armadilha do Fuso Horário

As datas e horas que manuseamos nos exemplos até agora são, na verdade, objetos "ingênuos" (naive), que não possuem informações de fuso horário. Isso não é problema para scripts simples de uso pessoal, mas ao criar um serviço web acessado por usuários do mundo todo, os fusos horários são uma questão inevitável.

Por exemplo, "11 de julho, 9:00 da manhã" no Japão e "11 de julho, 9:00 da manhã" nos Estados Unidos são momentos completamente diferentes. Para lidar com essa diferença corretamente, você precisa usar objetos "conscientes" (aware), que contêm informações de fuso horário.

A partir do Python 3.9, você pode manipular fusos horários facilmente usando o módulo `zoneinfo` da biblioteca padrão.

import datetime
from zoneinfo import ZoneInfo

# Obter a hora atual especificando um fuso horário
tz_tokyo = ZoneInfo("Asia/Tokyo")
now_tokyo = datetime.datetime.now(tz_tokyo)
print(f"Horário atual em Tóquio: {now_tokyo}")

tz_newyork = ZoneInfo("America/New_York")
now_newyork = datetime.datetime.now(tz_newyork)
print(f"Horário atual em Nova York: {now_newyork}")

# Você pode ver que a informação do fuso horário está anexada
# Exemplo de saída:
# Horário atual em Tóquio: 2025-07-11 07:42:15.123456+09:00
# Horário atual em Nova York: 2025-07-10 18:42:15.123456-04:00

Ao desenvolver serviços internacionais, certifique-se sempre de implementar com os fusos horários em mente!

[Prática] Copie, Cole e Execute! Exiba a Hora Atual em uma Página Web

Finalmente, usando o que você aprendeu, aqui está um exemplo de HTML completo que você pode copiar e colar para exibir o Horário Padrão do Japão (JST) em tempo real em uma página da web. Se você salvar este código como um arquivo HTML, ele funcionará apenas abrindo-o no seu navegador.
※Este exemplo inclui JavaScript dentro do HTML para atualizar a hora em tempo real.

Salve o código a seguir em um arquivo chamado `relogio.html` e abra-o no seu navegador.

<!DOCTYPE html>
<html lang="pt">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Exibição de Relógio em Tempo Real</title>
    <style>
        body {
            background-color: #202124;
            color: #e8eaed;
            font-family: sans-serif;
            display: flex;
            justify-content: center;
            align-items: center;
            height: 100vh;
            margin: 0;
            flex-direction: column;
        }
        h1 {
            color: #669df6;
        }
        #clock {
            font-size: 3rem;
            font-weight: bold;
            background-color: #3c4043;
            padding: 20px 40px;
            border-radius: 10px;
        }
    </style>
</head>
<body>
    <h1>Horário Atual do Japão</h1>
    <div id="clock">--:--:--</div>

    <script>
        function updateClock() {
            // Gera a hora no Horário Padrão do Japão (JST, UTC+9)
            const now = new Date();
            const jstOffset = 9 * 60; // JST é UTC+9 horas
            const localOffset = -now.getTimezoneOffset(); // Deslocamento do fuso horário local em minutos
            const jstNow = new Date(now.getTime() + (jstOffset - localOffset) * 60 * 1000);

            const hours = String(jstNow.getHours()).padStart(2, '0');
            const minutes = String(jstNow.getMinutes()).padStart(2, '0');
            const seconds = String(jstNow.getSeconds()).padStart(2, '0');
            
            document.getElementById('clock').textContent = `${hours}:${minutes}:${seconds}`;
        }

        // Atualiza o relógio a cada segundo
        setInterval(updateClock, 1000);

        // Executa na primeira vez que a página é carregada
        updateClock();
    </script>
</body>
</html>

Resumo

Neste artigo, aprendemos como manipular datas e horas usando o módulo `datetime` do Python.

Depois de dominar o módulo `datetime`, a gama de coisas que você pode criar se expande muito, incluindo carimbos de data/hora para logs, datas de registro de usuários e contagens regressivas para eventos. Sinta-se à vontade para brincar com o código deste artigo e tentar criar seus próprios programas!

Próximos Passos

Agora que você está confortável com a manipulação de datas e horas, por que não tentar as operações com arquivos e diretórios? O artigo a seguir explica como ler e escrever arquivos e criar/excluir pastas com Python.

Domine Operações de Arquivos e Diretórios com o Módulo os »

Modelos Relacionados