Skip to content

Commit b801843

Browse files
erickcpassosniltonpimentel02
erickcpassos
and
niltonpimentel02
authored
feat: adiciona utilitários para lidar com passaportes brasileiros (#699)
* Adicionando utilitário de passaporte * Corrige table of contents do README * Corrige table of contents do README_EN * Adiciona novos utilitários no changelog * Corrige espaçamento do README * Corrige espaçamento no README_EN * Formata READMEs para o padrão * Retoma READMEs anteriores * Corrige título utilitários do README * Corrige atualização do changelog --------- Co-authored-by: Nilton Pimentel <63605485+niltonpimentel02@users.noreply.github.com>
1 parent f862129 commit b801843

6 files changed

Lines changed: 373 additions & 2 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1515
- Utilitário `list_all_legal_nature` [#653](https://github.com/brazilian-utils/python/pull/653)
1616
- Utilitário `is_valid_cnh` [#651](https://github.com/brazilian-utils/brutils-python/pull/651)
1717
- Utilitário `is_valid_renavam` [#652](https://github.com/brazilian-utils/brutils-python/pull/652)
18+
- Utilitário `is_valid_passport` [#699](https://github.com/brazilian-utils/python/pull/699)
19+
- Utilitário `generate_passport` [#699](https://github.com/brazilian-utils/python/pull/699)
20+
- Utilitário `format_passport` [#699](https://github.com/brazilian-utils/python/pull/699)
21+
- Utilitário `remove_symbols_passport` [#699](https://github.com/brazilian-utils/python/pull/699)
1822

1923
### Fixed
2024

‎README.md‎

Lines changed: 95 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,6 @@ False
4141
```
4242

4343
# Utilitários
44-
4544
- [CPF](#cpf)
4645
- [is\_valid\_cpf](#is_valid_cpf)
4746
- [format\_cpf](#format_cpf)
@@ -109,6 +108,11 @@ False
109108
- [is_valid_legal_nature](#is_valid_legal_nature)
110109
- [get_legal_nature_description](#get_legal_nature_description)
111110
- [list_all_legal_nature](#list_all_legal_nature)
111+
- [Passaporte](#passaporte)
112+
- [is_valid_passport](#is_valid_passport)
113+
- [format_passport](#format_passport)
114+
- [remove_symbols_passport](#remove_symbols_passport)
115+
- [generate_passport](#generate_passport)
112116

113117
## CPF
114118

@@ -1446,6 +1450,8 @@ Retorna uma cópia do dicionário completo `{codigo: descricao}`.
14461450
True
14471451
>>> data["2062"]
14481452
'Sociedade Empresária Limitada'
1453+
```
1454+
14491455
## RENAVAM
14501456

14511457
### is_valid_renavam
@@ -1473,6 +1479,94 @@ True
14731479
False
14741480
```
14751481

1482+
## Passaporte
1483+
1484+
### is_valid_passport
1485+
1486+
Verifica se um número de passaporte brasileiro é válido.
1487+
1488+
Para ser considerado válido, a entrada deve ser uma string contendo exatamente dois caracteres alfabéticos seguidos de exatamente seis dígitos numéricos.
1489+
1490+
Esta função não verifica se a entrada é um número de passaporte real, pois não existem dígitos verificadores para o passaporte brasileiro.
1491+
1492+
Argumentos:
1493+
- passport (str): A string contendo o número do passaporte a ser verificado.
1494+
1495+
Retorna:
1496+
- bool: True se o número do passaporte for válido (2 letras seguidas de 6 dígitos). False caso contrário.
1497+
1498+
Exemplo:
1499+
```python
1500+
>>> from brutils import is_valid_passport
1501+
>>> is_valid_passport("Ab123456")
1502+
True
1503+
>>> is_valid_passport("12345678")
1504+
False
1505+
>>> is_valid_passport("DC-221345")
1506+
False
1507+
```
1508+
### format_passport
1509+
1510+
Formata um número de passaporte brasileiro para exibição.
1511+
1512+
Esta função recebe uma string representando um número de passaporte válido e o retorna formatado (maiúsculas, sem símbolos).
1513+
1514+
Argumentos:
1515+
- passport (str | None): Um número de passaporte brasileiro (minúsculas ou maiúsculas, possivelmente incluindo símbolos)
1516+
1517+
Retorna:
1518+
- str: O número do passaporte formatado (maiúsculas, sem símbolos) ou None se a entrada for inválida
1519+
1520+
Exemplo:
1521+
```python
1522+
>>> from brutils import format_passport
1523+
>>> format_passport("Ab123456")
1524+
AB123456
1525+
>>> format_passport("Ab-123456")
1526+
AB123456
1527+
>>> format_passport("111111")
1528+
None
1529+
```
1530+
### remove_symbols_passport
1531+
1532+
Remove símbolos ('-', '.' e espaços em branco) de um número de passaporte.
1533+
1534+
Esta função recebe uma string com um número de passaporte como entrada e remove todas as ocorrências dos caracteres '.', '-' e espaço em branco.
1535+
1536+
Argumentos:
1537+
- passport (str): A string contendo um número de passaporte
1538+
1539+
Retorna:
1540+
- str: O número do passaporte com hífens (-), pontos (.) e espaços em branco ( ) removidos.
1541+
1542+
Exemplo:
1543+
```python
1544+
>>> from brutils import remove_symbols_passport
1545+
>>> remove_symbols_passport("Ab123456")
1546+
Ab123456
1547+
>>> remove_symbols_passport("Ab-123456")
1548+
Ab123456
1549+
>>> remove_symbols_passport("Ab -. 123456")
1550+
Ab123456
1551+
```
1552+
### generate_passport
1553+
1554+
Gera uma string com um número de passaporte brasileiro válido aleatório.
1555+
1556+
Esta função gera uma string com um número de passaporte brasileiro aleatório.
1557+
1558+
Retorna:
1559+
- str: Uma string com um número de passaporte válido aleatório.
1560+
1561+
Exemplo:
1562+
```python
1563+
>>> from brutils import generate_passport
1564+
>>> generate_passport()
1565+
"RY393097"
1566+
>>> generate_passport()
1567+
"ZS840088"
1568+
```
1569+
14761570
# Novos Utilitários e Reportar Bugs
14771571

14781572
Caso queira sugerir novas funcionalidades ou reportar bugs, basta criar

‎README_EN.md‎

Lines changed: 94 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,6 @@ False
4040
```
4141

4242
# Utilities
43-
4443
- [CPF](#cpf)
4544
- [is\_valid\_cpf](#is_valid_cpf)
4645
- [format\_cpf](#format_cpf)
@@ -108,6 +107,11 @@ False
108107
- [is_valid_legal_nature](#is_valid_legal_nature)
109108
- [get_legal_nature_description](#get_legal_nature_description)
110109
- [list_all_legal_nature](#list_all_legal_nature)
110+
- [Passport](#passport)
111+
- [is_valid_passport](#is_valid_passport)
112+
- [format_passport](#format_passport)
113+
- [remove_symbols_passport](#remove_symbols_passport)
114+
- [generate_passport](#generate_passport)
111115

112116
## CPF
113117

@@ -1476,6 +1480,95 @@ Example:
14761480
True
14771481
>>> is_valid_renavam("12345678901")
14781482
False
1483+
```
1484+
1485+
## Passport
1486+
1487+
### is_valid_passport
1488+
1489+
Checks if a Brazilian passport number is valid.
1490+
1491+
To be considered valid, the input must be a string containing exactly two alphabetical characters followed by exactly six numerical digits.
1492+
1493+
This function does not verify is the input is a real passport number, as there are no checksums for the Brazilian passport.
1494+
1495+
Args:
1496+
- passport (str): The string containing the passport number to be checked.
1497+
1498+
Returns:
1499+
- bool: True if the passport number is valid (2 letters followed by 6 digits). False otherwise.
1500+
1501+
Example:
1502+
```python
1503+
>>> from brutils import is_valid_passport
1504+
>>> is_valid_passport("Ab123456")
1505+
True
1506+
>>> is_valid_passport("12345678")
1507+
False
1508+
>>> is_valid_passport("DC-221345")
1509+
False
1510+
```
1511+
### format_passport
1512+
1513+
Formats a Brazilian passport number for display.
1514+
1515+
This function takes a string representing a valid passport number and returns it formatted (uppercase, without symbols).
1516+
1517+
Args:
1518+
- passport (str | None): A Brazilian passport number (lower or uppercase, possibly including symbols)
1519+
1520+
Returns:
1521+
- str: The formatted passport number (uppercase, without symbols) or None if the input is invalid
1522+
1523+
Example:
1524+
```python
1525+
>>> format_passport("Ab123456")
1526+
AB123456
1527+
>>> format_passport("Ab-123456")
1528+
AB123456
1529+
>>> format_passport("111111")
1530+
None
1531+
```
1532+
1533+
### remove_symbols_passport
1534+
1535+
Removes symbols ('-', '.', and whitespaces) from a passport number.
1536+
1537+
This function takes a passport number string as input and removes all occurrences of
1538+
the '.', '-', and whitespace characters from it.
1539+
1540+
Args:
1541+
- passport (str): The string containing a passport number
1542+
1543+
Returns:
1544+
- str: The passport numbers with dashes (-), dots (.), and whitespaces ( ) removed.
1545+
1546+
Example:
1547+
```python
1548+
>>> remove_symbols_passport("Ab123456")
1549+
Ab123456
1550+
>>> remove_symbols_passport("Ab-123456")
1551+
Ab123456
1552+
>>> remove_symbols_passport("Ab -. 123456")
1553+
Ab123456
1554+
```
1555+
1556+
### generate_passport
1557+
1558+
Generate a random valid Brazilian passport number string.
1559+
1560+
This function generates a random Brazilian passport number string.
1561+
1562+
Returns:
1563+
- str: A random valid passport number string.
1564+
1565+
Example:
1566+
```python
1567+
>>> generate()
1568+
"RY393097"
1569+
>>> generate()
1570+
"ZS840088"
1571+
```
14791572

14801573
# Feature Request and Bug Report
14811574

‎brutils/__init__.py‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,12 @@
6464
from brutils.license_plate import is_valid as is_valid_license_plate
6565
from brutils.license_plate import remove_symbols as remove_symbols_license_plate
6666

67+
# Passport Imports
68+
from brutils.passport import format_passport
69+
from brutils.passport import generate as generate_passport
70+
from brutils.passport import is_valid as is_valid_passport
71+
from brutils.passport import remove_symbols as remove_symbols_passport
72+
6773
# Phone Imports
6874
from brutils.phone import (
6975
format_phone,
@@ -155,4 +161,9 @@
155161
"is_valid_legal_nature",
156162
"get_natureza_legal_nature",
157163
"list_all_legal_nature",
164+
# Passport
165+
"is_valid_passport",
166+
"remove_symbols_passport",
167+
"format_passport",
168+
"generate_passport",
158169
]

‎brutils/passport.py‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
import random
2+
import re
3+
import string
4+
5+
6+
def is_valid(passport: str) -> bool:
7+
"""
8+
Checks if a Brazilian passport number is valid.
9+
10+
To be considered valid, the input must be a string containing exactly two alphabetical characters followed by exactly six numerical digits.
11+
12+
This function does not verify is the input is a real passport number, as there are no checksums for the Brazilian passport.
13+
14+
Args:
15+
passport (str): The string containing the passport number to be checked.
16+
17+
Returns:
18+
bool: True if the passport number is valid (2 letters followed by 6 digits). False otherwise.
19+
20+
Example:
21+
>>> is_valid("Ab123456")
22+
True
23+
>>> is_valid("12345678")
24+
False
25+
>>> is_valid("DC-221345")
26+
False
27+
"""
28+
29+
if not isinstance(passport, str):
30+
return False
31+
32+
pattern = re.compile("^[A-Z]{2}[0-9]{6}$")
33+
match = re.match(pattern, passport)
34+
return match is not None
35+
36+
37+
def remove_symbols(passport: str) -> str:
38+
"""
39+
Removes symbols ('-', '.', and whitespaces) from a passport number.
40+
41+
This function takes a passport number string as input and removes all occurrences of
42+
the '.', '-', and whitespace characters from it.
43+
44+
Args:
45+
passport (str): The string containing a passport number
46+
47+
Returns:
48+
str: The passport numbers with dashes (-), dots (.), and whitespaces ( ) removed.
49+
50+
Example:
51+
>>> remove_symbols("Ab123456")
52+
Ab123456
53+
>>> remove_symbols("Ab-123456")
54+
Ab123456
55+
>>> remove_symbols("Ab -. 123456")
56+
Ab123456
57+
"""
58+
59+
return "".join(filter(lambda c: c not in ".- ", passport))
60+
61+
62+
def format_passport(passport: str) -> str | None:
63+
"""
64+
Formats a Brazilian passport number for display.
65+
66+
This function takes a string representing a valid passport number and returns it formatted (uppercase, without symbols).
67+
68+
Args:
69+
passport (str | None): A Brazilian passport number (lower or uppercase, possibly including symbols)
70+
71+
Returns:
72+
str: The formatted passport number (uppercase, without symbols) or None if the input is invalid
73+
74+
Example:
75+
>>> format_passport("Ab123456")
76+
AB123456
77+
>>> format_passport("Ab-123456")
78+
AB123456
79+
>>> format_passport("111111")
80+
None
81+
"""
82+
83+
passport = remove_symbols(passport.upper())
84+
85+
return passport if is_valid(passport) else None
86+
87+
88+
def generate() -> str:
89+
"""
90+
Generate a random valid Brazilian passport number string.
91+
92+
This function generates a random Brazilian passport number string.
93+
94+
Returns:
95+
str: A random valid passport number string.
96+
97+
Example:
98+
>>> generate()
99+
"RY393097"
100+
>>> generate()
101+
"ZS840088"
102+
"""
103+
104+
letters = "".join(random.choices(string.ascii_uppercase, k=2))
105+
digits = "".join(random.choices(string.digits, k=6))
106+
107+
return f"{letters}{digits}"

0 commit comments

Comments
 (0)