Validação do PIS/Pasep

[camilamaia]

Título da Issue: Validação do PIS/Pasep

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

Gostaria de validar números de PIS/Pasep, retornando um valor booleano que indica se o número é válido ou não. Isso é útil para garantir que os dados inseridos estejam corretos e possam ser utilizados em processos que exigem validação desses registros.

Descreva a solução que você gostaria

• Uma função is_valid_pis_pasep, que recebe um número de PIS/Pasep (string) e retorna True se o número for válido e False caso contrário.
• A função deve considerar todos os formatos válidos do PIS/Pasep e implementar a lógica de validação específica.
• A função deve lidar com números que tenham sido formatados com símbolos (como pontos ou traços) e garantir que a validação funcione corretamente.

Regras de Validação

A validação do PIS/Pasep é realizada da seguinte forma:

1. Formato: O PIS pode ser composto por 11 dígitos, que podem ser apresentados em formato como 123.45678.90-1 ou 12345678901. O dígito de controle é o último dígito, que é calculado com base nos 10 primeiros dígitos.

2. Cálculo do Dígito de Controle:

   • Multiplicar os 10 primeiros dígitos do PIS por uma sequência de pesos que vai de 3 a 1.
   • Somar os resultados das multiplicações.
   • Dividir a soma por 11 e considerar o resto da divisão.
   • O dígito de controle é obtido subtraindo o resto de 11. Se o resultado for maior que 9, o dígito de controle deve ser 0.

3. Validação: A função deve retornar True se o PIS/Pasep for válido de acordo com as regras acima e False caso contrário.

Descreva alternativas que você considerou

1. Seguir até o passo 8 do guia de contribuição.

2. Como parte do passo 8, criar o arquivo: brutils-python/brutils/pis.py.

   def is_valid_pis_pasep(pis_pasep):  # type: (str) -> bool
       """
       Validates a given PIS/Pasep number.
   
       This function checks if the provided PIS/Pasep number is valid according to the official
       validation rules. It returns True if the number is valid, and False otherwise.
   
       Args:
           pis_pasep (str): The PIS/Pasep number to be validated.
   
       Returns:
           bool: True if the PIS/Pasep number is valid, False otherwise.
   
       Example:
           >>> is_valid_pis_pasep('123.45678.90-1')
           True
           >>> is_valid_pis_pasep('12345678901')
           False
           >>> is_valid_pis_pasep('PIS inválido')
           False
       """
       # implementar a lógica da função aqui

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

   # PIS Imports
   from brutils.pis import (
       is_valid_pis_pasep,
   )

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

   __all__ = [
       ...
       # PIS
       'is_valid_pis_pasep',
   ]

3. Como parte do passo 9, criar o arquivo de teste: brutils-python/tests/test_pis.py.

   from unittest import TestCase
   from brutils.pis import is_valid_pis_pasep
   
   class TestPIS(TestCase):
       def test_is_valid_pis_pasep(self):
           # Testes para PIS válidos
           self.assertTrue(is_valid_pis_pasep('123.45678.90-1'))  # Formato com símbolos
           self.assertTrue(is_valid_pis_pasep('12345678901'))      # Formato sem símbolos
   
           # Testes para PIS inválidos
           self.assertFalse(is_valid_pis_pasep('1234567890'))  # Falta um dígito
           self.assertFalse(is_valid_pis_pasep(''))             # Vazio
           self.assertFalse(is_valid_pis_pasep('invalid pis'))  # Texto não numérico
           self.assertFalse(is_valid_pis_pasep('123.45678.90-0'))  # PIS com dígito de controle inválido
   
           # implementar mais casos de teste aqui se necessário

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

Contexto adicional