Datetime no Python

Para trabalhar com datas e horários, você terá como aliado a biblioteca Datetime no Python. Ela fornece uma ampla gama de funções para manipulação de datas e horários, como formatação de datas, cálculo de diferenças de tempo, conversão de fusos horários e muito mais.

Ao trabalhar com datas e horários em Python, é importante estar ciente de como as datas e horários são representados e manipulados.

Neste artigo, vamos explorar a biblioteca datetime em detalhes e mostrar como usá-la para trabalhar com datas e horários em Python. Bora lá!

Mão no Código

O Que é Datetime No Python

Datetime é a biblioteca padrão do Python para trabalhar com datas e horários. Com ela, é possível criar, manipular e formatar datas e horários de forma fácil e eficiente.

A biblioteca datetime possui três classes principais: date, time e datetime. A classe date é utilizada para trabalhar com datas, enquanto a classe time é utilizada para trabalhar com horários. Já a classe datetime é utilizada para trabalhar com ambos os formatos juntos.

Cada uma dessas classes possui diversos métodos e atributos que permitem realizar diversas operações com datas e horários. Por exemplo, é possível criar uma data a partir de uma string utilizando o método strptime, ou formatar uma data utilizando o método strftime.

Além disso, a biblioteca datetime também possui diversas constantes que podem ser utilizadas para representar dias da semana, meses do ano, fusos horários, entre outros.

Como Importar Datetime No Python

É muito fácil importar o módulo datetime no Python, bastando usar a seguinte sintaxe:

import datetime

Após a importação, você pode usar as classes do módulo datetime, como date, time e datetime.

Por exemplo, para criar um objeto datetime, você pode usar o seguinte código:

import datetime

data_hora = datetime.datetime(2023, 10, 4, 14, 30, 0)
print(data_hora) # imprime 2023-10-04 14:30:00

Este código cria um objeto datetime com a data e hora especificadas e imprime o resultado na tela.

Você também pode usar a classe date para trabalhar apenas com datas:

import datetime

data = datetime.date(2023, 10, 4)
print(data) # imprime 2023-10-04

Este código cria um objeto date com a data especificada e imprime o resultado na tela.

Além disso, o módulo datetime fornece várias funções úteis para trabalhar com datas e horas, como strftime e strptime. A função strftime permite formatar uma data ou hora como uma string, enquanto a função strptime permite converter uma string em um objeto datetime.

Trabalhando Com Data e Hora Atuais

Quando se trabalha com data e hora em Python, é importante entender como a linguagem lida com esses valores. Felizmente, a biblioteca padrão do Python oferece muitas ferramentas úteis.

Para obter a data e hora atuais, podemos usar o módulo datetime. O método datetime.now() retorna um objeto datetime que representa a data e hora atuais. Por exemplo:

import datetime

agora = datetime.datetime.now()
print(agora) # imprime a data e hora atuais, ex: 2023-10-16 18:10:40.596070

Este código exibirá a data e hora atuais no formato YYYY-MM-DD HH:MM:SS.mmmmmm.

Se você precisar apenas da data atual ou da hora atual, pode usar os métodos date() e time(), respectivamente. Por exemplo:

import datetime

hoje = datetime.date.today()
print(hoje) # imprime a data atual, ex.: 2023-10-16

agora = datetime.datetime.now().time()
print(agora) # imprime a hora atual, ex: 18:14:04.420863

Outra ferramenta útil para trabalhar com datas e horas é o módulo calendar. Este módulo oferece funções para trabalhar com calendários, como determinar o dia da semana para uma determinada data. Por exemplo:

import calendar

dia_da_semana = calendar.weekday(2023, 10, 4)
print(dia_da_semana)

Este código exibirá o número do dia da semana para a data especificada (0 para segunda-feira, 1 para terça-feira, etc.):

Número Retornado	Dia da Semana
0	Segunda
1	Terça
2	Quarta
3	Quinta
4	Sexta
5	Sábado
6	Domingo

Formatando Data e Hora

Formatar a data e hora é uma tarefa muito comum em muitos projetos de programação. O Python oferece uma variedade de métodos para essa tarefa.

O módulo datetime do Python inclui a classe datetime que permite formatar datas e horas. O método strftime é usado para formatar a data e hora. Ele recebe um argumento de formato que define como a data e hora deve ser formatada.

A tabela abaixo mostra os códigos de formato mais comuns que podem ser usados para formatar a data e hora:

Código	Descrição	Exemplo
%Y	Ano com 4 dígitos	2023
%y	Ano com 2 dígitos	23
%m	Mês com 2 dígitos	10
%B	Nome completo do mês	October
%b	Nome abreviado do mês	Oct
%d	Dia do mês com 2 dígitos	23
%A	Nome completo do dia da semana	Monday
%a	Nome abreviado do dia da semana	Mon
%H	Hora com 2 dígitos, formando 24 horas	18
%I	Hora no formato 12 horas	06
%p	AM ou PM	PM
%M	Minutos com 2 dígitos	30
%S	Segundos com 2 dígitos	59

Por exemplo, o código abaixo mostra como formatar a data e hora no formato “dd/mm/aaaa hh:mm”:

from datetime import datetime

data_hora_atual = datetime.now()
data_hora_formatada = data_hora_atual.strftime("%d/%m/%Y %H:%M:%S")
print(data_hora_formatada)

Este código irá imprimir a data e hora atual formatada no formato “dd/mm/aaaa hh:mm”.

Formatando Data e Hora para o Locale Brasileiro

Ao formatar a data e hora, é importante lembrar que o formato pode variar dependendo da localização geográfica do usuário final. Portanto, é recomendável usar o módulo locale do Python para definir a localização do usuário e formatar a data e hora de acordo com a localização.

Para isso, basta usar o locale da seguinte forma:

import datetime
import locale

# Configura o local para o Brasil
locale.setlocale(locale.LC_TIME, 'pt_BR.UTF-8')

# Obtém a data e hora atual
agora = datetime.datetime.now()

# Formata a data 
data_formatada = agora.strftime('%A, %d de %B de %Y')

# Exibe a data e hora formatadas
print(data_formatada) # Imprime a data atual, ex: Segunda Feira, 16 de Outubro de 2023

Intervalos de Tempo

Um intervalo de tempo é simplesmente a diferença entre duas datas ou horas – e por vezes são uma parte fundamental do trabalho com data e hora. Em Python, existem várias maneiras de trabalhar com intervalos de tempo, também incluindo na biblioteca datetime.

Existem vários tipos de intervalos de tempo que podem ser usados em Python. Alguns dos mais comuns incluem:

Timedelta

O timedelta é um objeto que representa uma duração entre duas datas ou horas. Ele pode ser usado para adicionar ou subtrair um intervalo de tempo de uma data ou hora.

Para criar um objeto timedelta em Python, basta subtrair uma data ou hora de outra. Por exemplo:

import datetime

data1 = datetime.datetime(2023, 10, 4, 10, 30)
data2 = datetime.datetime(2023, 10, 3, 9, 0)

diferenca = data1 - data2

print(diferenca) # imprime: 1 day, 1:30:00

Este código criará um objeto timedelta que representa a diferença de tempo entre as duas datas. Ele pode ser usado para adicionar ou subtrair um intervalo de tempo de uma data ou hora.

Relativedelta

O relativedelta é um objeto que representa um intervalo de tempo relativo a uma data ou hora específica. Ele pode ser usado para adicionar ou subtrair um intervalo de tempo de uma data ou hora, levando em consideração fatores como meses e anos bissextos.

from dateutil.relativedelta import relativedelta
import datetime

data1 = datetime.datetime(2023, 10, 4, 10, 30)

nova_data = data1 + relativedelta(months=+3)

print(nova_data) # Imprime 2024-01-04 10:30:00

Este código criará um novo objeto datetime que representa a data e hora três meses após a data original.

Diferença Entre Datas

Como explicamos anteriormente, para calcular a diferença entre duas datas, basta subtrair uma data da outra. Isso retornará um objeto timedelta que representa a diferença entre as duas datas em dias, segundos e microssegundos.

Por exemplo, para calcular a diferença entre as datas 01/01/2023 e 31/12/2023, pode-se usar o seguinte código:

from datetime import date

data1 = date(2023, 1, 1)
data2 = date(2023, 12, 31)

diferenca = data2 - data1

print(diferenca.days) # Imprime 364

O código acima cria duas datas, data1 e data2, e calcula a diferença entre elas. A diferença é então impressa na tela.

Observe que a diferença é retornada em dias. Se você precisar da diferença em outras unidades, como horas, minutos ou segundos, pode-se converter o objeto timedelta para a unidade desejada.

A tabela abaixo mostra os métodos disponíveis para converter um objeto timedelta para outras unidades:

Método	Descrição
days	Retorna a diferença em dias
seconds	Retorna a diferença em segundos
microseconds	Retorna a diferença em microssegundos
total_seconds()	Retorna a diferença total em segundos

Calendários e Datas Futuras

O módulo datetime também possui classes para trabalhar com deltas de tempo e fusos horários.

Para trabalhar com datas futuras, a classe datetime pode ser usada em conjunto com a classe timedelta. A classe timedelta representa uma duração de tempo, como dias, horas, minutos e segundos.

Para adicionar uma duração de tempo a uma data, basta criar um objeto timedelta com a duração desejada e adicioná-lo à data usando o operador de adição (+).

Por exemplo, para calcular a data de um evento que ocorrerá daqui a 30 dias, pode-se criar um objeto timedelta com 30 dias e adicioná-lo à data atual:

from datetime import datetime, timedelta

data_atual = datetime.now()
dias_futuros = timedelta(days=30)
data_evento = data_atual + dias_futuros

Agora, a variável data_evento contém a data do evento que ocorrerá daqui a 30 dias.

Erros Comuns e Como Evitá-los

Ao trabalhar com datetime em Python, é comum encontrar erros que podem ser evitados com algumas práticas simples. Nesta seção, serão apresentados alguns dos erros mais comuns e como evitá-los.

1. Formatação incorreta

Um erro comum é a formatação incorreta de datas e horários. É importante lembrar que a formatação deve seguir um padrão específico, caso contrário, o código não funcionará corretamente. Para evitar esse erro, é recomendado utilizar as diretivas de formatação corretas ao utilizar a função strftime().

2. Fusos horários

Outro erro comum é o uso incorreto de fusos horários. É importante lembrar que as datas e horários podem variar de acordo com o fuso horário em que estão sendo utilizados. Para evitar esse erro, é recomendado utilizar a biblioteca pytz para lidar com fusos horários.

3. Conversão de tipos

A conversão de tipos também pode ser um problema ao trabalhar com datetime em Python. É importante lembrar que as datas e horários são objetos diferentes de outros tipos de dados, como strings e números. Para evitar esse erro, é recomendado utilizar as funções de conversão corretas, como strptime() e strftime(), ao lidar com datetime.

Principais Funções e Exemplos

Vamos resumir as principais funções na biblioteca datetime do Python que vimos até agora na manipulação de datas e horas. São elas:

Função Now

A função now() retorna a data e hora atuais. É útil para obter a data e hora atual do sistema.

Exemplo:

from datetime import datetime

agora = datetime.now()

print("Data e hora atual:", agora)

Saída:

Data e hora atual: 2023-10-04 14:30:15.123456

Função Strftime

A função strftime() é usada para formatar uma data e hora em uma string. É útil para exibir uma data e hora em um formato específico.

Exemplo:

from datetime import datetime

agora = datetime.now()

data_formatada = agora.strftime("%d/%m/%Y %H:%M:%S")

print("Data formatada:", data_formatada)

Saída:

Data formatada: 04/10/2023 14:30:15

Função Strptime

A função strptime() é usada para converter uma string em uma data e hora. É útil para converter uma data e hora em um formato específico em um objeto datetime.

Exemplo:

from datetime import datetime

data_string = "04/10/2023 14:30:15"

data_hora = datetime.strptime(data_string, "%d/%m/%Y %H:%M:%S")

print("Data e hora:", data_hora)

Saída:

Data e hora: 2023-10-04 14:30:15

Função Timedelta

A função timedelta() é usada para manipular datas e horas. É útil para adicionar ou subtrair dias, horas, minutos, segundos e microssegundos de um objeto datetime.

Exemplo:

from datetime import datetime, timedelta

data_hora_atual = datetime.now()

um_dia = timedelta(days=1)
um_ano = timedelta(weeks=52)

data_hora_futura = data_hora_atual + um_dia + um_ano

print("Data e hora futura:", data_hora_futura)

Saída:

Data e hora futura: 2024-10-05 14:30:15.123456

Adição de datas

Para adicionar um número específico de dias a uma data, pode-se usar o método timedelta. Por exemplo, para adicionar 10 dias a uma data, pode-se fazer o seguinte:

import datetime

data = datetime.date(2023, 10, 4)
nova_data = data + datetime.timedelta(days=10)

Para adicionar meses ou anos, pode-se usar o método relativedelta do módulo dateutil. Por exemplo, para adicionar 6 meses a uma data, pode-se fazer o seguinte:

import datetime
from dateutil.relativedelta import relativedelta

data = datetime.date(2023, 10, 4)
nova_data = data + relativedelta(months=6)

Observe que o método relativedelta leva em consideração o número exato de dias em cada mês, então o resultado será preciso mesmo se a data inicial estiver no final de um mês.

Também é possível adicionar anos usando o mesmo método, como mostrado abaixo:

import datetime
from dateutil.relativedelta import relativedelta

data = datetime.date(2023, 10, 4)
nova_data = data + relativedelta(years=2)

Em resumo, adicionar dias, meses ou anos a uma data é fácil e pode ser feito com o módulo datetime e o método timedelta, ou com o módulo dateutil e o método relativedelta.

Subtração de datas

Para subtrair a data de hoje (04/10/2023) da data de 10 dias atrás (24/09/2023), basta fazer:

from datetime import date, timedelta

data_atual = date(2023, 10, 4)
data_anterior = data_atual - timedelta(days=10)

print(data_anterior) # 2023-09-24

No exemplo acima, foi utilizada a classe timedelta do módulo datetime para subtrair os 10 dias da data atual. É importante lembrar que a subtração de datas retorna um objeto do tipo timedelta.

Também é possível realizar a subtração de datas diretamente a partir de strings formatadas. Por exemplo, para subtrair a data de 10/09/2023 da data de 04/10/2023, basta fazer:

data_atual = date(2023, 10, 4)
data_anterior = date.fromisoformat('2023-09-10')

diferenca = data_atual - data_anterior

print(diferenca.days) # 24

No exemplo acima, foi utilizada a função date.fromisoformat para criar um objeto do tipo date a partir de uma string formatada. Em seguida, foi realizada a subtração entre as duas datas e o resultado foi obtido através do atributo days do objeto timedelta.

Como extrair parte de uma data

Extrair parte de uma data é uma tarefa comum ao trabalhar com datetime em Python. É possível extrair o dia, mês, ano, hora, minuto, segundo, microssegundo e até mesmo o timezone de uma data.

Extraindo o dia, mês e ano

Para extrair o dia, mês e ano de uma data, basta utilizar os métodos day, month e year, respectivamente. Por exemplo:

import datetime

data = datetime.datetime(2023, 10, 4, 14, 30, 0)

dia = data.day
mes = data.month
ano = data.year

print(f"{dia}/{mes}/{ano}")  # Imprime 4/10/2023

Extraindo a hora, minuto e segundo

Para extrair a hora, minuto e segundo de uma data, basta utilizar os métodos hour, minute e second, respectivamente. Por exemplo:

import datetime

data = datetime.datetime(2023, 10, 4, 14, 30, 0)

hora = data.hour
minuto = data.minute
segundo = data.second

print(f"{hora}:{minuto}:{segundo}")  # Imprime 14:30:0

Extraindo o microssegundo

Para extrair o microssegundo de uma data, basta utilizar o método microsecond. Por exemplo:

import datetime

data = datetime.datetime(2023, 10, 4, 14, 30, 0, 500000)

microssegundo = data.microsecond

print(microssegundo)  # Output: 500000

Extraindo o timezone

Para extrair o timezone de uma data, basta utilizar o método tzinfo. Por exemplo:

import datetime

data = datetime.datetime(2023, 10, 4, 14, 30, 0, tzinfo=datetime.timezone.utc)

timezone = data.tzinfo

print(timezone)  # Output: UTC

UTC, BRT, Timezones, Timestamp, Epoch: O que significa?

Quando se trata de lidar com datas e horas em programação, é importante entender alguns conceitos e siglas comuns relacionadas. Vamos entender alguns termos:

Timezones

Timezones, ou zonas horárias, são regiões geográficas que compartilham o mesmo horário. Cada zona horária é geralmente identificada por um nome, como BRT, e é medida em relação ao UTC. Existem muitas zonas horárias diferentes em todo o mundo, e os programadores devem estar cientes dessas diferenças ao trabalhar com datas e horas em diferentes locais.

UTC

UTC significa Coordinated Universal Time. É um padrão de tempo global que é usado como referência para outras zonas horárias. O UTC não está vinculado a nenhuma localização geográfica específica, mas é baseado em relógios atômicos e é considerado o tempo padrão em todo o mundo.

BRT

BRT significa Horário de Brasília. É a zona horária padrão usada no Brasil. O BRT está três horas atrás do UTC durante o horário de verão e duas horas atrás do UTC durante o horário padrão.

Timestamp

Um timestamp é uma representação numérica de uma data e hora específicas. Por exemplo, a data Mon Oct 16 2023 21:59:08 é representada pelo timestamp 1697493548.

É frequentemente usado em programação para registrar quando um evento ocorreu. Os timestamps são geralmente medidos em segundos ou milissegundos desde o Epoch.

Epoch

O Epoch é um ponto de referência comum usado para medir timestamps. É definido como a meia-noite (00:00:00) de 1º de janeiro de 1970, no horário UTC. Os timestamps são medidos em relação a esse ponto de referência. O Epoch é frequentemente usado em programação para calcular a diferença entre duas datas ou para converter timestamps em um formato legível para humanos.

Como definir o Timezone de uma data para São Paulo?

Para definir o Timezone de uma data para São Paulo, é necessário utilizar a biblioteca pytz do Python. Esta biblioteca contém informações sobre os fusos horários de várias cidades do mundo, incluindo São Paulo.

Para definir o Timezone de uma data para São Paulo, primeiro é preciso importar a biblioteca pytz:

import pytz

Em seguida, é possível definir o Timezone de São Paulo da seguinte forma:

sao_paulo_tz = pytz.timezone('America/Sao_Paulo')

Com o Timezone de São Paulo definido, é possível criar uma data com este Timezone:

from datetime import datetime

data = datetime(2023, 10, 4, 12, 0, 0, tzinfo=sao_paulo_tz)

Neste exemplo, foi criada uma data com o dia 4 de outubro de 2023, às 12 horas, no Timezone de São Paulo.

É importante lembrar que, ao criar uma data com um Timezone específico, é preciso utilizar o parâmetro tzinfo da classe datetime. Caso contrário, a data será criada com o Timezone padrão do sistema operacional.

Com estas informações, é possível definir o Timezone de uma data para São Paulo de forma simples e precisa.

Conclusão

A manipulação de datas e horas é uma tarefa comum em muitos projetos de programação. A biblioteca datetime do Python oferece uma ampla gama de ferramentas para lidar com esse tipo de tarefa, desde a criação de objetos de data e hora até a realização de operações aritméticas e formatação de saída.

Embora a biblioteca datetime seja poderosa e flexível, é importante lembrar que a manipulação de datas e horas pode ser complicada e propensa a erros. É importante ter cuidado ao trabalhar com datas e horas e testar cuidadosamente seu código para garantir que ele esteja funcionando corretamente.

Links Úteis

• Documentação oficial do Python sobre datetime
• Tutorial sobre datetime no Python