Merge branch 'main' into 353-busca_cep

CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Utilitário `get_address_from_cep` [#358](https://github.com/brazilian-utils/brutils-python/pull/358)
 - Utilitário `get_cep_information_from_address` [#358](https://github.com/brazilian-utils/brutils-python/pull/358)
+- Utilitário `format_voter_id` [#221] (https://github.com/brazilian-utils/brutils-python/issues/221)
+- Utilitário `generate_voter_id` [#220](https://github.com/brazilian-utils/brutils-python/pull/220)
 
 ## [2.1.1] - 2024-01-06
 

README.md

@@ -79,12 +79,15 @@ False
   - [remove\_symbols\_pis](#remove_symbols_pis)
   - [generate\_pis](#generate_pis)
 - [Processo Jurídico](#processo-jurídico)
-- [is\_valid\_legal\_process](#is_valid_legal_process)
+  - [is\_valid\_legal\_process](#is_valid_legal_process)
   - [format\_legal\_process](#format_legal_process)
   - [remove\_symbols\_legal\_process](#remove_symbols_legal_process)
   - [generate\_legal\_process](#generate_legal_process)
-- [Titulo Eleitoral](#titulo-eleitoral)
+- [Título Eleitoral](#titulo-eleitoral)
   - [is\_valid\_voter\_id](#is_valid_voter_id)
+  - [format\_voter\_id](#format_voter_id)
+  - [generate\_voter\_id](#generate_voter_id)
+
 
 ## CPF
 
@@ -1008,20 +1011,18 @@ Exemplo:
 
 ### is_valid_voter_id
 
-Verifica se um número de título de eleitor brasileiro é válido. Não verifica se realmente existe.
+Verifica se um número de Título de Eleitor brasileiro é válido. Não verifica se realmente existe.
 
 Referências:
 
 - <https://pt.wikipedia.org/wiki/T%C3%ADtulo_de_eleitor>
 - <http://clubes.obmep.org.br/blog/a-matematica-nos-documentos-titulo-de-eleitor/>
 
 Argumentos:
-
-- voter_id (str): string representando o número do título de eleitor a ser verificado.
+  * voter_id (str): string representando o número do Título de Eleitor a ser verificado.
 
 Retorna:
-
-- bool: True se o número do título de eleitor for válido. False, caso contrário.
+  * bool: True se o número do Título de Eleitor for válido. False, caso contrário.
 
 Exemplo:
 
@@ -1033,6 +1034,54 @@ False
 True
 ```
 
+### format_voter_id
+
+Formata um número de Título de Eleitor para exibição visual.
+
+Esta função recebe uma string de Título de Eleitor contendo 
+apenas números como entrada e adiciona os espaços de formatação 
+padrão para exibição.
+
+Argumentos:
+  * voter_id (str): Uma string de Título de Eleitor contendo apenas números.
+
+Retorna:
+  * str: O Título de Eleitor formatado com os espaços, se for válido.
+         Retorna None se não for válido.
+
+Exemplo:
+
+```python
+>>> from brutils import format_voter_id
+>>> format_voter_id("246593980493")
+'2465 9398 04 93'
+>>> format_voter_id("202715292895")
+'2027 1529 28 95'
+>>> format_voter_id("739035552205")
+>>> 
+```
+
+### generate_voter_id
+
+Gera uma string de dígitos de Título de Eleitor válida aleatória a partir de um estado brasileiro informado.
+
+Args:
+  * federative_union (str): Unidade Federativa para o título de eleitor que será gerado. O valor padrão "ZZ" é usado para Títulos de Eleitor emitidos para estrangeiros.
+
+Retorna:
+  * str: Um Título de Eleitor válido gerado aleatoriamente.
+
+Exemplo:
+
+```python
+>>> from brutils import generate_voter_id
+>>> generate_voter_id()
+'183475722801'
+>>> generate_voter_id(federative_union ="MG")
+'950125640248'
+```
+
+
 # Novos Utilitários e Reportar Bugs
 
 Caso queira sugerir novas funcionalidades ou reportar bugs, basta criar

README_EN.md

@@ -79,12 +79,14 @@ False
   - [remove\_symbols\_pis](#remove_symbols_pis)
   - [generate\_pis](#generate_pis)
 - [Legal Process](#legal-process)
-- [is\_valid\_legal\_process](#is_valid_legal_process)
+  - [is\_valid\_legal\_process](#is_valid_legal_process)
   - [format\_legal\_process](#format_legal_process)
   - [remove\_symbols\_legal\_process](#remove_symbols_legal_process)
   - [generate\_legal\_process](#generate_legal_process)
 - [Voter ID](#voter-id)
   - [is\_valid\_voter\_id](#is_valid_voter_id)
+  - [format\_voter\_id](#format_voter_id)
+  - [generate\_voter\_id](#generate_voter_id)
 
 ## CPF
 
@@ -1037,6 +1039,52 @@ False
 True
 ```
 
+### format_voter_id
+
+Formats a voter ID number for visual display.
+
+This function takes a voter ID string containing only numbers as input 
+and adds the standard formatting spaces for display.
+
+Arguments:
+  - voter_id (str): A voter ID string containing only numbers.
+
+Returns:
+  - str: The formatted voter ID with spaces if valid.
+         Returns None if not valid.
+
+Example:
+
+```python
+>>> from brutils import format_voter_id
+>>> format_voter_id("246593980493")
+'2465 9398 04 93'
+>>> format_voter_id("202715292895")
+'2027 1529 28 95'
+>>> format_voter_id("739035552205")
+>>>
+```
+
+### generate_voter_id
+
+Generate a valid random Voter ID string of digits from an informed Brazilian federation union.
+
+Args:
+  - federative_union(str): federative union for the voter id that will be generated. The default value "ZZ" is used for voter IDs issued to foreigners.
+
+Returns:
+  - str: A randomly generated valid voter ID.
+
+Example:
+
+```python
+>>> from brutils import generate_voter_id
+>>> generate_voter_id()
+'183475722801'
+>>> generate_voter_id(federative_union ="MG")
+'950125640248'
+```
+
 # Feature Request and Bug Report
 
 If you want to suggest new features or report bugs, simply create

brutils/__init__.py

@@ -90,6 +90,12 @@
 from brutils.pis import (
     remove_symbols as remove_symbols_pis,
 )
+from brutils.voter_id import (
+    format_voter_id,
+)
+from brutils.voter_id import (
+    generate as generate_voter_id,
+)
 from brutils.voter_id import (
     is_valid as is_valid_voter_id,
 )

brutils/voter_id.py

@@ -1,3 +1,6 @@
+from random import randint
+
+
 def is_valid(voter_id):  # type: (str) -> bool
     """
     Check if a Brazilian voter id number is valid.
@@ -204,4 +207,88 @@ def _calculate_vd2(federative_union, vd1):  # type: (str, int) -> str
     if federative_union in ["01", "02"] and rest == 0:
         vd2 = 1
 
+    # edge case: rest == 10, declare vd2 as zero
+    if rest == 10:
+        vd2 = 0
+
     return vd2
+
+
+def generate(federative_union="ZZ") -> str:
+    """
+    Generates a random valid Brazilian voter registration.
+
+    Args:
+        federative_union(str): federative union for the voter id that will be generated. The default value "ZZ" is used for voter IDs issued to foreigners.
+
+    Returns:
+        str: A randomly generated valid voter ID for the given federative union
+    """
+    UFs = {
+        "SP": "01",
+        "MG": "02",
+        "RJ": "03",
+        "RS": "04",
+        "BA": "05",
+        "PR": "06",
+        "CE": "07",
+        "PE": "08",
+        "SC": "09",
+        "GO": "10",
+        "MA": "11",
+        "PB": "12",
+        "PA": "13",
+        "ES": "14",
+        "PI": "15",
+        "RN": "16",
+        "AL": "17",
+        "MT": "18",
+        "MS": "19",
+        "DF": "20",
+        "SE": "21",
+        "AM": "22",
+        "RO": "23",
+        "AC": "24",
+        "AP": "25",
+        "RR": "26",
+        "TO": "27",
+        "ZZ": "28",
+    }
+
+    federative_union = federative_union.upper()
+    if federative_union in (UFs):
+        sequential_number = str(randint(0, 99999999)).zfill(8)
+        uf_number = UFs[federative_union]
+        if _is_federative_union_valid(uf_number):
+            vd1 = _calculate_vd1(sequential_number, uf_number)
+            vd2 = _calculate_vd2(uf_number, vd1)
+            return f"{sequential_number}{uf_number}{vd1}{vd2}"
+
+
+def format_voter_id(voter_id):  # type: (str) -> str
+    """
+    Format a voter ID for display with visual spaces.
+
+    This function takes a numeric voter ID string as input and adds standard
+    formatting for display purposes.
+
+    Args:
+        voter_id (str): A numeric voter ID string.
+
+    Returns:
+        str: A formatted voter ID string with standard visual spacing, or None
+        if the input is invalid.
+
+    Example:
+        >>> format_voter_id("690847092828")
+        '6908 4709 28 28'
+        >>> format_voter_id("163204010922")
+        '1632 0401 09 22'
+    """
+
+    if not is_valid(voter_id):
+        return None
+
+    return "{} {} {} {}".format(
+        voter_id[:4], voter_id[4:8], voter_id[8:10], voter_id[10:12]
+    )