String Python para DateTime: Como converter strings em objetos DateTime

Introdução ao módulo datetime do Python

O módulo datetime, que vem embutido no Python, pode ser usado sempre que você precisar trabalhar com datas, horas ou intervalos de tempo para qualquer aplicativo criado com Python. Ele oferece classes e métodos práticos para representar e mexer com dados de data e hora.

Tabela 1: Resumo das classes e métodos no módulo datetime

Vamos entender as principais classes deste módulo, já que vamos convertê-las em objetos datetime:

1. datetime.date

Essa classe representa uma data (ano, mês e dia) e oferece métodos para trabalhar com datas, como calcular a diferença entre duas datas e formatar datas como strings.

Digamos que a gente tem um conjunto de dados com os preços diários das ações de uma empresa. A gente pode usar a classe date pra extrair as datas do conjunto de dados e traçar os preços das ações ao longo do tempo.

Aqui está um trecho que mostra como usar a classe ` date `:

from datetime import date

# create a date object representing March 1, 2023
start_date = date(2023, 3, 1)

# extract information such as the year, month, and day
year = start_date.year
month = start_date.month
day = start_date.day

# get the day of the week (Note: Monday is coded as 0, and Sunday as 6)
weekday = start_date.weekday()

# the date can be formatted as a string if needed
date_str = start_date.strftime('%Y-%m-%d')

2. datetime.time

Essa classe representa uma hora do dia (hora, minuto, segundo e microssegundo) e oferece métodos para trabalhar com horários, como comparar horários e formatá-los como strings.

Digamos que temos um conjunto de dados com a hora de término de uma corrida; podemos usar a classe ` time ` para pegar as horas e minutos de cada competidor que terminou a corrida.

from datetime import time

# create a time object with the microsecond granularity
end_time = time(15, 45, 30, 500000)

# get the hour and minute
hour = end_time.hour
minute = end_time.minute
second = end_time.second
microsecond = end_time.microsecond

3. datetime.datetime

Essa classe representa uma data e hora e oferece métodos para trabalhar com ambas. Combina as funcionalidades das classes de data e hora.

É normalmente usado em tarefas de análise de dados que envolvem séries temporais com alta resolução temporal, como dados por hora ou por minuto. Imagina que temos um conjunto de dados com a demanda de eletricidade por hora de uma cidade. A gente pode usar a classe ` datetime ` pra extrair a data e a hora do conjunto de dados e traçar a demanda de eletricidade ao longo do tempo.

from datetime import datetime

# create a datetime object representing March 1, 2023 at 9:30 AM
start_datetime = datetime(2023, 3, 1, 9, 30)

# get the year, month, day, hour, and minute
year = start_datetime.year
month = start_datetime.month
day = start_datetime.day
hour = start_datetime.hour
minute = start_datetime.minute

4. datetime.timedelta

Essa classe representa uma duração ou intervalo de tempo e oferece métodos para trabalhar com intervalos de tempo, como adicionar ou subtrair intervalos de tempo de datas ou horas.

Digamos que a gente tem um conjunto de dados com as horas de início e fim de um monte de eventos e quer calcular a duração total de todos eles. A gente pode usar a classe ` timedelta ` para calcular a duração de cada evento e somá-los.

from datetime import timedelta

# create a timedelta object representing 3 hours and 15 minutes
event_duration = timedelta(hours=3, minutes=15)

# get the total duration in seconds
event_duration_seconds = event_duration.total_seconds()

# add the duration to a start time to get an end time
event_start_time = datetime(2023, 3, 1, 18, 15)
event_end_time = event_start_time + event_duration

Em todos os casos que mostramos, usamos objetos ` datetime `, mas, na prática, os dados reais geralmente continuam como uma string. E converter para um objeto datetime libera todas as funcionalidades acima, que são super úteis na análise e nas aplicações de ciência de dados.

Usando datetime.strptime() para conversão de data e hora

Em Python, dá pra usar o método ` datetime.strptime() ` pra transformar uma string num objeto datetime. O método ` strptime() ` pega dois argumentos: a string que vai ser convertida e uma string de formato que diz como a string de entrada deve ficar.

A string de formato usa uma combinação de códigos de formatação para mostrar os vários componentes da data e hora. Aqui estão alguns dos códigos de formatação mais usados:

Tabela 2: Códigos comuns de formatação de data e hora

Agora que entendemos as diretivas strptime, o processo de conversão de strings em objetos datetime pode ser simplificado.

• Passo 01: Analise a sequência de data e hora que pode ser convertida para padrões que correspondam aos códigos de formatação.

• Passo 02: Crie o formato de data e hora a partir das diretivas strptime().

• Passo 03: Passa a string e o formato para a função e recebe o objeto como saída.

Vamos colocar essas etapas em prática.

Convertendo uma string num formato específico para um objeto datetime

from datetime import datetime

# Example with the standard date and time format
date_str = '2023-02-28 14:30:00'
date_format = '%Y-%m-%d %H:%M:%S'

date_obj = datetime.strptime(date_str, date_format)
print(date_obj)

# Example with a different format

date_str = '02/28/2023 02:30 PM'
date_format = '%m/%d/%Y %I:%M %p'

date_obj = datetime.strptime(date_str, date_format)
print(date_obj)

No primeiro exemplo, temos uma string que representa uma data e hora no formato “AAAA-MM-DD HH:MM:SS” e, no segundo exemplo, em um formato diferente, “MM/DD/AAAA HH:MM AM/PM”.

Nos dois casos, depois de especificarmos a string de formato correta como o segundo argumento para strptime(), recebemos o objeto datetime correto.

Convertendo uma string com informações de fuso horário em um objeto datetime

from datetime import datetime

date_str = '2023-02-28 14:30:00+05:30'
date_format = '%Y-%m-%d %H:%M:%S%z'

date_obj = datetime.strptime(date_str, date_format)
print(date_obj)

Neste exemplo, temos uma string que representa uma data e hora com informações de fuso horário no formato “AAAA-MM-DD HH:MM:SS+TZOFFSET”, onde TZOFFSET é o deslocamento do fuso horário em horas e minutos em relação ao UTC. Especificamos a string de formato como o segundo argumento para strptime(), incluindo o código de formatação %z para analisar o deslocamento do fuso horário.

Embora a função que vimos acima possa parecer fácil na teoria, ela também pode ser uma fonte de frustração quando as coisas dão errado na prática.

Analisando datas sem strings de formato usando dateutil

Outra opção flexível é a biblioteca dateutil, especialmente a função parser.parse(). Ele detecta automaticamente os formatos de data, permitindo que você analise strings sem precisar especificar uma string de formato.

from dateutil.parser import parse

# Automatically infers the format
date_obj = parse("March 1, 2023 9:30 AM")
print(date_obj)

Isso é super útil quando você está lidando com formatos de data imprevisíveis ou inconsistentes.

Lidando com fusos horários

Para lidar com datas e horas levando em conta o fuso horário, o Python tem duas opções bem conhecidas:

• pytz (muito usado e compatível com versões mais antigas)

• zoneinfo (introduzido no Python 3.9, parte da biblioteca padrão)

from datetime import datetime
from zoneinfo import ZoneInfo

# Using zoneinfo
dt = datetime(2023, 3, 1, 9, 30, tzinfo=ZoneInfo("America/New_York"))
print(dt)

# Using pytz (alternative)
import pytz
dt_pytz = datetime(2023, 3, 1, 9, 30, tzinfo=pytz.timezone("America/New_York"))
print(dt_pytz)

Essas ferramentas permitem atribuir fusos horários, fazer conversões entre eles e contabilizar automaticamente o horário de verão.

Considerações sobre o horário de verão

Quando você trabalha com datas e horas que levam em conta o fuso horário, o horário de verão pode trazer complicações, principalmente quando os relógios avançam ou atrasam.

Bibliotecas como zoneinfo e pytz cuidam das mudanças do horário de verão automaticamente quando você define o fuso horário certo:

from datetime import datetime
from zoneinfo import ZoneInfo

# Before and after DST starts
before_dst = datetime(2023, 3, 12, 1, 30, tzinfo=ZoneInfo("America/New_York"))
after_dst = datetime(2023, 3, 12, 3, 30, tzinfo=ZoneInfo("America/New_York"))

print(before_dst)
print(after_dst)

Isso garante que os cálculos de data e hora continuem precisos mesmo com as mudanças do horário de verão.

Usando pandas para conversão de data e hora

Embora o módulo datetime integrado ao Python seja poderoso, muitos cientistas de dados preferem usar a biblioteca pandas para conversões de data e hora devido à sua simplicidade e capacidade de lidar com colunas inteiras de datas de forma eficiente.

import pandas as pd

# Converting a column of strings to datetime objects
date_series = pd.to_datetime(['2023-02-28', '2023-03-01', '2023-03-02'])
print(date_series)

O Pandas descobre formatos automaticamente e lida com inconsistências comuns de forma elegante, tornando-o uma escolha óbvia quando se trabalha com dados tabulares.

Formatação de objetos datetime em strings com strftime()

Depois de converter as strings em objetos datetime e fazer as operações que você queria, talvez precise convertê-las de volta em strings. Você pode usar datetime.strftime() pra isso.

from datetime import datetime

now = datetime.now()
formatted = now.strftime('%Y-%m-%d %H:%M:%S')
print(formatted)

Esse método te dá controle total sobre como seu objeto datetime é mostrado em forma de string.

Resolução de problemas comuns do strptime()

Aqui estão alguns erros comuns que você pode encontrar e como corrigi-los:

Erro de valor: os dados de hora "date_string" não combinam com o formato "%Y-%m-%d %H:%M:%S".

O erro mais comum rola quando a string de entrada não combina com a string de formato. Dá uma conferida se a string de entrada e a string de formato estão iguais.

import datetime

# When input has two-digit year instead of four-digit year
date_str = '23-03-01'
date_obj = datetime.datetime.strptime(date_str, '%y-%m-%d')
# Raises ValueError: time data '23-03-01' does not match format '%y-%m-%d'

# When the input has missing leading zeros for hour and minute
time_str = '8:30'
time_obj = datetime.datetime.strptime(time_str, '%H:%M')
# Raises ValueError: time data '8:30' does not match format '%H:%M'

Erro de tipo: o argumento 1 da função strptime() precisa ser str, não 'int'.

O próximo erro comum rola quando você passa um número inteiro para datetime.strptime() ou time.strptime() em vez de uma string. Certifique-se de que todos os valores que você está passando para a função são strings.

# Example 1: Integer instead of string
date_int = 20230301
date_obj = datetime.datetime.strptime(date_int, '%Y%m%d')
# Raises TypeError: strptime() argument 1 must be str, not int

# Example 2: List instead of string
date_list = [2023, 3, 1]
date_obj = datetime.datetime.strptime(date_list, '%Y-%m-%d')
# Raises TypeError: strptime() argument 1 must be str, not list

Erro de valor: dados não convertidos permanecem: ':00'

Esse erro rola quando tem caracteres sobrando na string de entrada que não combinam com a string de formato. Por exemplo, esse erro vai rolar se a string de formato só especificar o ano, mês e dia, mas a string de entrada também tiver a hora do dia. Para resolver esse erro, certifique-se de que a string de formato corresponda à string de entrada inteira.

# when input string contains time of day
date_str = '2023-03-01 12:30:00'
date_obj = datetime.datetime.strptime(date_str, '%Y-%m-%d')
# Raises ValueError: unconverted data remains:  12:30:00

# When input string contains extra characters
date_str = '2023-03-01T00:00:00Z'
date_obj = datetime.datetime.strptime(date_str, '%Y-%m-%d')
# Raises ValueError: unconverted data remains: T00:00:00Z

Conclusão

É seguro dizer que o método ` datetime.strptime() ` oferece uma maneira flexível e poderosa de converter strings em objetos datetime no Python e pode ser usado para lidar com uma ampla variedade de formatos de data e hora. Que tal pegar nossa Folha de Referência com Datas e Horários pra dar uma olhada depois?

Depois de entender as datas e horários, o próximo passo é praticá-los em um projeto. Recomendamos que você escolha um desses e consolide seu aprendizado:

• Previsão financeira em Python
• Python intermediário para finanças

A gente concorda que os dados de data e hora no mundo real são complicados, mas tudo o que você precisa é entender os formatos e padrões por trás de cada tipo de data e hora que você tem nos seus dados e usar as bibliotecas que você tem com sabedoria.