Adicionar método is_holiday para verificar feriados nacionais e estaduais

[camilamaia]

Seu pedido de recurso está relacionado a um problema? Por favor, descreva.

Quero verificar se uma data específica é um feriado nacional ou estadual no Brasil. O método deve aceitar uma data no formato datetime e uma unidade federativa (UF) opcional. Caso a data ou a UF seja inválida, o método deve retornar None.

Por exemplo, verificar se datetime(2024, 1, 1) é um feriado nacional e retornar True. Caso a data ou a UF seja inválida, o método deve retornar None.

Descreva a solução que você gostaria

• Uma função is_holiday, que recebe um objeto datetime obrigatório e uma string opcional uf, e retorna um booleano indicando se a data é um feriado, ou None se a data ou a UF forem inválidas.
• A função deve utilizar a biblioteca holidays para realizar a verificação.
• Deve considerar feriados nacionais e, caso seja passada uma uf válida, verificar também os feriados estaduais.
• Se a data não for válida ou a UF não corresponder a um estado brasileiro, a função deve retornar None.
• O método não lida com feriados municipais

Exemplo de Uso:

from datetime import datetime
from brutils.date import is_holiday

# Feriado nacional
data_feriado = datetime(2024, 1, 1)  # Ano Novo
resultado_feriado = is_holiday(data_feriado)
print(resultado_feriado)  # Deveria retornar True

# Dia normal
data_normal = datetime(2024, 1, 2)
resultado_normal = is_holiday(data_normal)
print(resultado_normal)  # Deveria retornar False

# Feriado estadual
data_feriado_estadual = datetime(2024, 7, 9)  # Revolução Constitucionalista (SP)
resultado_feriado_estadual = is_holiday(data_feriado_estadual, uf="SP")
print(resultado_feriado_estadual)  # Deveria retornar True

# UF inválida
data_uf_invalida = datetime(2024, 1, 1)
resultado_uf_invalida = is_holiday(data_uf_invalida, uf="XX")
print(resultado_uf_invalida)  # Deveria retornar None

# Data inválida
data_invalida = "01/01/2024"  # Formato incorreto
resultado_data_invalida = is_holiday(data_invalida)
print(resultado_data_invalida)  # Deveria retornar None

Descreva alternativas que você considerou

1. Criar o arquivo: brutils-python/brutils/date.py.

from datetime import datetime

def is_holiday(date: datetime, uf: str = None) -> bool | None:
    """
    Checks if the given date is a national or state holiday in Brazil.

    This function takes a date as a `datetime` object and an optional UF (Unidade Federativa), 
    returning a boolean value indicating whether the date is a holiday or `None` if the date or 
    UF are invalid.

    The method does not handle municipal holidays.

    Args:
        date (datetime): The date to be checked.
        uf (str, optional): The state abbreviation (UF) to check for state holidays. 
                            If not provided, only national holidays will be considered.

    Returns:
        bool | None: Returns `True` if the date is a holiday, `False` if it is not, 
                     or `None` if the date or UF are invalid.

    Note:
        The function logic should be implemented using the `holidays` library.
        For more information, refer to the documentation at: https://pypi.org/project/holidays/

    Usage Examples:
        >>> from datetime import datetime
        >>> is_holiday(datetime(2024, 1, 1))
        True

        >>> is_holiday(datetime(2024, 1, 2))
        False

        >>> is_holiday(datetime(2024, 3, 2), uf="SP")
        False

        >>> is_holiday(datetime(2024, 12, 25), uf="RJ")
        True
    """
    # Adicionar lógica aqui
    pass

2. Importar a nova função no arquivo brutils-python/brutils/__init__.py.

   # Date Imports    
   from brutils.date import is_holiday

3. Adicionar o nome da nova função na lista __all__ do mesmo arquivo brutils-python/brutils/__init__.py:

   __all__ = [
       ...
       # Date
       'is_holiday'
   ]

4. Criar o arquivo de teste: brutils-python/tests/test_date.py.

   from unittest import TestCase
   from datetime import datetime
   from brutils.date import is_holiday
   
   class TestDate(TestCase):
       def test_is_holiday(self):
           # Testes com feriados válidos
           self.assertTrue(is_holiday(datetime(2024, 1, 1)))  # Ano Novo
           self.assertTrue(is_holiday(datetime(2024, 7, 9), uf="SP"))  # Revolução Constitucionalista (SP)
   
           # Testes com dias normais
           self.assertFalse(is_holiday(datetime(2024, 1, 2)))  # Dia normal
           self.assertFalse(is_holiday(datetime(2024, 7, 9), uf="RJ"))  # Dia normal no RJ
   
           # Testes com data inválida
           self.assertIsNone(is_holiday("2024-01-01"))  # Formato incorreto
           self.assertIsNone(is_holiday(None))  # Data None
   
           # Testes com UF inválida
           self.assertIsNone(is_holiday(datetime(2024, 1, 1), uf="XX"))  # UF inválida
   
           # Testes com limite de datas
           self.assertTrue(is_holiday(datetime(2024, 12, 25)))  # Natal
           self.assertTrue(is_holiday(datetime(2024, 11, 15)))  # Proclamação da República
   
           # Testar outros feriados e casos de borda

Edge Cases:

1. Data no formato inválido: Deve retornar None.

2. UF inválida ou não existente: Deve retornar None.

3. Data sem UF fornecida: Deve considerar apenas feriados nacionais.

4. Data nos limites de feriados (véspera de feriados, como 24/12 e 31/12): Testar comportamento.

5. Feriado em ano bissexto: Verificar comportamento em anos como 2024.

6. Primeiro feriado do ano e último feriado do ano: Testar como o código lida com extremos.

7. Datas passadas ou futuras além do calendário anual atual: Testar comportamento com datas fora do ano atual.

8. Seguir os passos seguintes do guia de contribuição.

Contexto adicional

• A verificação deve considerar tanto feriados nacionais quanto estaduais quando fornecida a uf.
• Edge cases como datas inválidas e UFs incorretas devem retornar None.

[laistdomiciano]

Bora!

[github-actions[bot]]

Issue 423 atribuida a laistdomiciano :rocket:" "Verifique o guia de contribuição para mais informações sobre como submeter sua Pull Request."

[BeneBr]

Opa, se precisar de uma ajuda, estou a inteira disposição.