Cálculo da Diferença Entre Datas Descartando Finais de Semana em Python

O cálculo preciso de intervalos entre duas datas é uma necessidade frequente em sistemas de automação, relatórios financeiros e gestão de acordos de nível de serviço (SLAs). Em muitos cenários operacionais, a simples subtração entre dois momentos não reflete o tempo útil trabalhado, pois contabiliza sábados e domingos. Para resolver esse desafio, a linguagem Python oferece soluções eficientes, variando desde funções vetorizadas de alta performance em bibliotecas numéricas até implementações nativas com o módulo padrão.

A escolha da melhor abordagem depende do volume de dados processados e da tolerância a dependências externas no projeto. A seguir, são detalhadas as duas principais metodologias para calcular dias úteis descontando finais de semana.

1. Abordagem de Alta Performance com NumPy (numpy.busday_count)

Quando o objetivo é obter a contagem exata de dias úteis com máxima eficiência computacional e código conciso, a utilização da biblioteca NumPy se destaca como o padrão da indústria. Através da função numpy.busday_count, é possível calcular diretamente o número de dias úteis entre dois objetos de data sem a necessidade de laços de repetição em Python.

Como documentado nas discussões técnicas de manipulação de datas, os objetos de data e hora do módulo nativo datetime podem ter suas strings convertidas via datetime.strptime() e seus componentes de data extraídos via .date() para alimentar diretamente a função do NumPy.

from datetime import datetime
import numpy as np

# Strings de entrada representando a data inicial e final
create_date = "2017-08-29 10:47:00"
resolve_date = "2017-09-23 16:56:00"

# Conversão de string para objeto datetime
create_datetime = datetime.strptime(create_date, '%Y-%m-%d %H:%M:%S')
resolve_datetime = datetime.strptime(resolve_date, '%Y-%m-%d %H:%M:%S')

# Cálculo total de dias corridos vs. dias úteis (busday_count)
dias_corridos = (resolve_datetime - create_datetime).days
dias_uteis = np.busday_count(create_datetime.date(), resolve_datetime.date())

print(f"Diferença em dias corridos: {dias_corridos}")
print(f"Diferença em dias úteis (NumPy): {dias_uteis}")

Nessa implementação, enquanto a subtração direta de objetos datetime retorna a diferença total de dias corridos (por exemplo, 25 dias), a função np.busday_count avalia o intervalo e retorna apenas os dias de semana (19 dias úteis), desconsiderando automaticamente os sábados e domingos contidos no período.

2. Abordagem Nativa sem Dependências Nacionais (datetime e isoweekday / weekday)

Em projetos onde a inclusão de dependências externas pesadas como o NumPy não é viável, é possível construir uma solução utilizando exclusivamente a biblioteca padrão de Python. O módulo datetime, em conjunto com geradores ou compreensões de lista, permite iterar pelos dias do intervalo e filtrar apenas os dias úteis.

A verificação do dia da semana pode ser feita através do método isoweekday(), no qual a segunda-feira corresponde a 1 e o domingo a 7 (considerando dias úteis valores menores ou iguais a 5), ou pelo método weekday(), no qual os dias úteis variam de 0 (segunda-feira) a 4 (sexta-feira) e os finais de semana são representados por 5 (sábado) e 6 (domingo).

from datetime import datetime, timedelta

def calcular_dias_uteis_nativos(data_inicio, data_fim):
    # Calcula o número total de dias corridos no intervalo
    dias_totais = (data_fim - data_inicio).days
    
    # Soma 1 para cada dia em que o dia da semana não é sábado (5) nem domingo (6)
    dias_uteis = sum(
        (data_inicio + timedelta(days=i)).weekday() not in (5, 6)
        for i in range(dias_totais + 1)
    )
    return dias_uteis

# Exemplo de execução
create_date = "2017-08-29 10:47:00"
resolve_date = "2017-09-23 16:56:00"

s = datetime.strptime(create_date, '%Y-%m-%d %H:%M:%S')
e = datetime.strptime(resolve_date, '%Y-%m-%d %H:%M:%S')

total_dias_uteis = calcular_dias_uteis_nativos(s, e)
print(f"Diferença em dias úteis (Python Nativo): {total_dias_uteis}")

Alternativamente, a lógica pode ser construída criando um conjunto de datas filtradas onde isoweekday() <= 5, permitindo iterar dia a dia e calcular a extensão total de dias úteis válidos no intervalo definido por timedelta.

3. Comparativo Técnico entre as Soluções

A escolha do método ideal varia de acordo com as restrições e requisitos da aplicação. A tabela abaixo sintetiza as principais características de cada abordagem.

4. Considerações Finais e Boas Práticas

Para pipelines de engenharia de dados e análises em larga escala, a utilização de numpy.busday_count oferece uma vantagem de performance significativa e código mais limpo. Por outro lado, para pequenos scripts de automação ou ambientes com restrições severas de instalação de pacotes, a solução nativa utilizando datetime.timedelta e a checagem de weekday() garante total portabilidade sem comprometer a clareza do código.