feat(passport): add Passport validators and formatters

CHANGELOG.md

@@ -16,6 +16,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Utilitário `format_currency` [#434](https://github.com/brazilian-utils/brutils-python/pull/434)
 - Utilitário `convert_real_to_text` [#525](https://github.com/brazilian-utils/brutils-python/pull/525)
 - Utilitário `convert_uf_to_name` [#554](https://github.com/brazilian-utils/brutils-python/pull/554)
+- Utilitário `is_valid_passport` [#579](https://github.com/brazilian-utils/brutils-python/issues/579)
+- Utilitário `format_passport` [#579](https://github.com/brazilian-utils/brutils-python/issues/579)
+- Utilitário `remove_symbols_passport` [#579](https://github.com/brazilian-utils/brutils-python/issues/579)
+- Utilitário `generate_passport` [#579](https://github.com/brazilian-utils/brutils-python/issues/579)
 
 ### Deprecated
 

README.md

@@ -99,6 +99,11 @@ False
 - [Monetário](#monetário)
   - [format\_currency](#format_currency)
   - [convert\_real\_to\_text](#convert_real_to_text)
+- [Passaporte](#passaporte)
+  - [is_valid_passport](#is_valid_passport)
+  - [format_passport](#format_passport-1)
+  - [remove_symbols_passport](#remove_symbols_passport)
+  - [generate_passport](#generate_passport-1)
 
 ## CPF
 
@@ -1312,6 +1317,97 @@ Exemplo:
 >>> convert_real_to_text("invalid")
 None
 ```
+## Passaporte
+
+### is_valid_passport
+
+Validate the format of a Brazilian Passport number.  
+The input must have exactly two letters followed by six digits.  
+This function does not check if the Passport actually exists.
+
+Args:
+
+- passport (str): A Passport string.
+
+Returns:
+
+- bool: True if the format is valid, False otherwise.
+
+Example:
+
+```python
+>>> from brutils import is_valid_passport
+>>> is_valid_passport("CS265436")
+True
+>>> is_valid_passport("CS-265.436")
+False
+```
+
+### format_passport
+
+Normaliza uma string de Passaporte para exibição.
+
+Esta função recebe uma string de Passaporte (possivelmente com símbolos visuais como espaços, pontos ou traços), remove esses símbolos se necessário, e retorna a string em maiúsculas se for válida.
+
+Argumentos:
+
+- passport (str): Uma string de Passaporte com ou sem símbolos.
+
+Retorna:
+
+- str: Uma string de Passaporte em maiúsculas sem símbolos se for válida,  
+       `None` se for inválida.
+
+Exemplo:
+
+```python
+>>> from brutils import format_passport
+>>> format_passport("cs 265436")
+"CS265436"
+>>> format_passport("C-5265436")
+None
+>>> format_passport("aa123456")
+"AA123456"
+```
+
+### remove_symbols_passport
+
+Remove símbolos de formatação de uma string de Passaporte.  
+Remove `"."`, `"-"` e espaços.
+
+Argumentos:
+
+- passport (str): A string de Passaporte contendo símbolos a serem removidos.
+
+Retorna:
+
+- str: A string de Passaporte limpa com os símbolos removidos.
+
+Exemplo:
+
+```python
+>>> from brutils import remove_symbols_passport
+>>> remove_symbols_passport("CS-265.436")
+"CS265436"
+```
+
+### generate_passport
+
+Gera uma string de Passaporte sintaticamente válida de forma aleatória.  
+Cria duas letras maiúsculas seguidas de seis dígitos.  
+O Passaporte não corresponde a um documento real.
+
+Retorna:
+
+- str: Uma string de Passaporte sintaticamente válida gerada aleatoriamente.
+
+Exemplo:
+
+```python
+>>> from brutils import generate_passport
+>>> generate_passport()
+"HU546394"
+```
 
 # Novos Utilitários e Reportar Bugs
 

README_EN.md

@@ -99,6 +99,11 @@ False
 - [Monetary](#monetary)
   - [format_currency](#format_currency)
   - [convert\_real\_to\_text](#convert_real_to_text)
+- [Passport](#passport)
+  - [is_valid_passport](#is_valid_passport)
+  - [format_passport](#format_passport-1)
+  - [remove_symbols_passport](#remove_symbols_passport)
+  - [generate_passport](#generate_passport-1)
 
 ## CPF
 
@@ -1317,6 +1322,97 @@ Example:
 >>> convert_real_to_text("invalid")
 None
 ```
+## Passport
+
+### is_valid_passport
+
+Validate the format of a Brazilian Passport number.  
+The input must have exactly two letters followed by six digits.  
+This function does not check if the Passport actually exists.
+
+Args:
+
+- passport (str): A Passport string.
+
+Returns:
+
+- bool: True if the format is valid, False otherwise.
+
+Example:
+
+```python
+>>> from brutils import is_valid_passport
+>>> is_valid_passport("CS265436")
+True
+>>> is_valid_passport("CS-265.436")
+False
+```
+
+### format_passport
+
+Normalize a Passport string for display.
+
+This function takes a Passport string (possibly with visual-aid symbols such as spaces, dots, or dashes), removes those symbols if necessary, and returns an uppercase string if the input is valid.
+
+Args:
+
+- passport (str): A Passport string with or without symbols.
+
+Returns:
+
+- str: An uppercase Passport string without symbols if valid,  
+       `None` if the input is invalid.
+
+Example:
+
+```python
+>>> from brutils import format_passport
+>>> format_passport("cs 265436")
+"CS265436"
+>>> format_passport("C-5265436")
+None
+>>> format_passport("aa123456")
+"AA123456"
+```
+
+### remove_symbols_passport
+
+Remove formatting symbols from a Passport string.  
+It deletes `"."`, `"-"`, and spaces.
+
+Args:
+
+- passport (str): The Passport string containing symbols to be removed.
+
+Returns:
+
+- str: A clean Passport string with the specified symbols removed.
+
+Example:
+
+```python
+>>> from brutils import remove_symbols_passport
+>>> remove_symbols_passport("CS-265.436")
+"CS265436"
+```
+
+### generate_passport
+
+Generate a random syntactically valid Passport string.  
+It creates two uppercase letters followed by six digits.  
+The Passport does not correspond to a real document.
+
+Returns:
+
+- str: A random syntactically valid Passport string.
+
+Example:
+
+```python
+>>> from brutils import generate_passport
+>>> generate_passport()
+"HU546394"
+```
 
 # Feature Request and Bug Report
 

brutils/__init__.py

@@ -52,6 +52,20 @@
 from brutils.license_plate import is_valid as is_valid_license_plate
 from brutils.license_plate import remove_symbols as remove_symbols_license_plate
 
+# Passport Imports
+from brutils.passport import (
+    format_passport,
+)
+from brutils.passport import (
+    generate as generate_passport,
+)
+from brutils.passport import (
+    is_valid as is_valid_passport,
+)
+from brutils.passport import (
+    remove_symbols as remove_symbols_passport,
+)
+
 # Phone Imports
 from brutils.phone import (
     format_phone,
@@ -131,4 +145,9 @@
     # Currency
     "format_currency",
     "convert_real_to_text",
+    # Passport
+    "format_passport",
+    "generate_passport",
+    "is_valid_passport",
+    "remove_symbols_passport",
 ]