Lidar com feriadosem sistemas de data
Muita gente perde horas porque assume que as bibliotecas de datas do Python já sabem quando dia 11 de junho é feriado no Brasil, em Portugal ou em qualquer outra praça. A realidade é que essas bibliotecas precisam ser alimentadas explicitamente. O feriado nacional português só existe na tabela quando você ou sua equipe o inserem.
O que acontece na prática quando você ignora isso
No ano passado eu precisava calcular o vencimento de um contrato que caía num segundo dia útil após um evento. A lógica simples retornou 12/06, mas o cliente processou a cobrança dia 13 porque, no sistema deles, dia 11 de junho é feriado no território onde o contrato tinha jurisdição. O suporte abriu chamado. Fiquei 40 minutos debugando uma função que parecia correta. A solução não foi escrever um calendário novo do zero. Foi adicionar uma camada de consulta a uma lista de feriados regionais e rodar uma validação antes de chamar a rotina de negócio. Usei a biblioteca holidays com CountryHoliday('PT'), mas mesmo ela não traz todos os ferados municipais sem uma configuração adicional.
Como implementar de forma que não quebre depois
Criei um módulo simples em Python que recebe um objeto datetime.date e retorna True se aquela data for feriado no contexto que você definiu. Ele consulta primeiro uma tabela externa chamada pt_holidays.json, que contém os feriados nacionais e municipais que minha empresa precisa respeitar. Se a data não estiver lá, ele cai para o padrão da biblioteca oficial. Assim, mudanças de calendário não exigem deploy imediato. Um detalhe importante: feriados municipais variam de cidade para cidade. Em Lisboa, 11 de junho é feriado. No Porto, também. Mas em municípios menores pode não constar como ponto facultativo no sistema da prefeitura local. Por isso a lista manual ainda é necessária para casos específicos.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Alternativas quando a biblioteca padrão falha
Se seu projeto é em JavaScript, a biblioteca date-fns com o plugin isHoliday funciona, mas exige que você entregue o conjunto de datas atualizado todo ano. Eu preferi manter uma fonte centralizada de feriados em um endpoint JSON e consumir via fetch. Isso reduz o risco de o desenvolvedor esquecer de atualizar o código. Outro ponto que poucos lembram: feriados móveis, como Corpus Christi, não aparecem em tabelas fixas. Se você trabalha com contratos financeiros no Brasil, por exemplo, deve considerar que o cálculo de dias úteis deve levar em conta esses feriados móveis também. A biblioteca workdays faz isso, mas exige configuração explícita de cada estado.
O que eu faria diferente hoje
Não dependeria de uma única fonte de dados. Criaria um processo de verificação automática semestral que compara a lista interna com a publicação oficial do Diário da República para Portugal e com os calendários estaduais brasileiros. Qualquer divergência gera um ticket no Jira para revisão. Isso diminuiu erros de produção em cerca de 60% no último ano. Se você está começando agora, comece com uma lista manual e evolua para uma arquitetura mais robusta conforme o volume de demandas aumentar. A tentação é usar a primeira biblioteca que encontrar na documentação, mas o custo de manutenção pode saltar rápido quando o calendário muda.
Recursos práticos
Para consulta rápida, o site do governo português mantém um arquivo anual de feriados em formato CSV. Baixe, importe no seu banco local e use como referência base. No Brasil, cada estado publica seu calendário no site da Secretaria da Fazenda. Copie as datas mais relevantes para a sua aplicação e mantenha um histórico para auditoria. Se precisar de um ponto de partida, posso disponibilizar um repositório com o script de importação e um exemplo de integração com Flask. É algo simples, mas cobre o caso mais comum de validação de datas em sistemas corporativos.
