brutils 2.3.0__tar.gz → 2.5.0__tar.gz

{brutils-2.3.0 → brutils-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brutils
-Version: 2.3.0
+Version: 2.5.0
 Summary: Utils library for specific Brazilian businesses
 License: MIT
 License-File: LICENSE
@@ -24,17 +24,19 @@ Classifier: Topic :: Office/Business
 Classifier: Topic :: Software Development :: Internationalization
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: coverage (>=7.2.7,<8.0.0)
-Requires-Dist: holidays (>=0.58,<0.59)
+Requires-Dist: holidays (>=0.58,<0.99)
 Requires-Dist: num2words (==0.5.14)
-Project-URL: Repository, https://github.com/brazilian-utils/brutils
+Project-URL: Repository, https://github.com/brazilian-utils/python
 Description-Content-Type: text/markdown
 
+![Logo do Brazilian Utils](https://github.com/brazilian-utils/brand/raw/main/github-hero/github-hero-python.png)
+
 <div align="center">
-<h1>🇧🇷 Brazilian Utils</h1>
 
-<p>Utils library for Brazilian-specific businesses.</p>
+<p>Biblioteca de utilitários projetada para validar, gerar e manipular dados de acordo com as particularidades do Brasil</p>
 
-[![codecov](https://codecov.io/gh/brazilian-utils/brutils-python/branch/main/graph/badge.svg?token=5KNECS8JYF)](https://codecov.io/gh/brazilian-utils/brutils-python)
+[![codecov](https://codecov.io/gh/brazilian-utils/python/branch/main/graph/badge.svg)](https://codecov.io/gh/brazilian-utils/python)
+[![Check Lint](https://github.com/brazilian-utils/python/actions/workflows/check-lint.yml/badge.svg?branch=main)](https://github.com/brazilian-utils/python/actions/workflows/check-lint.yml?query=branch%3Amain)
 [![Downloads per Month](https://shields.io/pypi/dm/brutils)](https://pypistats.org/packages/brutils)
 [![Package version](https://shields.io/pypi/v/brutils)](https://pypi.org/project/brutils/)
 
@@ -71,7 +73,6 @@ False
 ```
 
 # Utilitários
-
 - [CPF](#cpf)
   - [is\_valid\_cpf](#is_valid_cpf)
   - [format\_cpf](#format_cpf)
@@ -99,6 +100,8 @@ False
   - [is\_valid\_email](#is_valid_email)
 - [Data](#date)
   - [convert\_date\_to_text](#convert_date_to_text)
+- [CNH](#cnh)
+  - [is\_valid\_cnh](#is_valid_cnh)
 - [Placa de Carro](#placa-de-carro)
   - [is\_valid\_license\_plate](#is_valid_license_plate)
   - [format\_license\_plate](#format_license_plate)
@@ -116,6 +119,8 @@ False
   - [format\_legal\_process](#format_legal_process)
   - [remove\_symbols\_legal\_process](#remove_symbols_legal_process)
   - [generate\_legal\_process](#generate_legal_process)
+- [RENAVAM](#renavam)
+  - [is_valid_renavam](#is_valid_renavam)
 - [Titulo Eleitoral](#titulo-eleitoral)
   - [is\_valid\_voter\_id](#is_valid_voter_id)
   - [format\_voter\_id](#format_voter_id)
@@ -123,6 +128,7 @@ False
 - [IBGE](#ibge)
   - [convert_code_to_uf](#convert_code_to_uf)
   - [convert_uf_to_name](#convert_uf_to_name)
+  - [convert_name_to_uf](#convert_name_to_uf)
   - [get_code_by_municipality_name](#get_code_by_municipality_name)
   - [get\_municipality\_by\_code](#get_municipality_by_code)
 - [Feriados](#feriados)
@@ -130,6 +136,15 @@ False
 - [Monetário](#monetário)
   - [format\_currency](#format_currency)
   - [convert\_real\_to\_text](#convert_real_to_text)
+- [Natureza Jurídica](#natureza-jurídica)
+  - [is_valid_legal_nature](#is_valid_legal_nature)
+  - [get_legal_nature_description](#get_legal_nature_description)
+  - [list_all_legal_nature](#list_all_legal_nature)
+- [Passaporte](#passaporte)
+  - [is_valid_passport](#is_valid_passport)
+  - [format_passport](#format_passport)
+  - [remove_symbols_passport](#remove_symbols_passport)
+  - [generate_passport](#generate_passport)
 
 ## CPF
 
@@ -229,7 +244,8 @@ Exemplo:
 
 Verifica se os dígitos de verificação do CNPJ (Cadastro Nacional da Pessoa
 Jurídica) fornecido correspondem ao seu número base. A entrada deve ser uma
-string de dígitos com o comprimento apropriado. Esta função não verifica a
+string de 14 caracteres, permitindo dígitos e letras maiúsculas nas 12
+primeiras posições e dígitos nas 2 últimas. Esta função não verifica a
 existência do CNPJ; ela só valida o formato da string.
 
 Argumentos:
@@ -301,12 +317,16 @@ Exemplo:
 
 ### generate_cnpj
 
-Gera uma string de dígitos CNPJ válida aleatória. Um número de filial
-opcional pode ser fornecido; o padrão é 1.
+Gera uma string de CNPJ válida aleatória. Um número de filial opcional pode ser
+fornecido; o padrão é 1. Use `alphanumeric=True` para gerar um CNPJ cujas 12
+primeiras posições podem conter dígitos e letras maiúsculas.
 
 Argumentos:
 
-- branch (int): Um número de filial opcional a ser incluído no CNPJ.
+- branch (int | str): Um número de filial opcional a ser incluído no CNPJ.
+  Valores de filial alfanuméricos são aceitos apenas com
+  `alphanumeric=True`.
+- alphanumeric (bool): Define se o CNPJ gerado deve ser alfanumérico.
 
 Retorna:
 
@@ -320,6 +340,13 @@ Exemplo:
 '34665388000161'
 >>> generate_cnpj(1234)
 "01745284123455"
+>>> generate_cnpj(alphanumeric=True)
+"9359QAG9000184"
+>>> generate_cnpj(branch="AB12", alphanumeric=True)
+"BR2026UTAB1290"
+>>> generate_cnpj(branch="CD34", alphanumeric=True)
+# CNPJ inválido para exemplos de validação:
+"NX9K79E2CD3400"
 ```
 
 ## CEP
@@ -695,6 +722,37 @@ None
 "Primeiro de agosto de dois mil e vinte e quatro"
 ````
 
+## CNH
+
+### is_valid_cnh
+
+Verifica se o número de registro de CNH (Carteira de Habilitação Nacional) brasileiro é válido.
+Para que um número de CNH seja considerado válido, a entrada deve ser uma string contendo
+exatamente 11 dígitos numéricos. Esta função não verifica se o número da CNH é real, apenas
+valida os dígitos verificadores.
+
+Argumentos:
+
+- cnh (str): A string contendo o número de registro de CNH a ser verificado.
+
+Retorno:
+
+- bool: True se o número de registro da CNHN for válido (11 dígitos), False caso contrário.
+
+Exemplo:
+
+```python
+>>> from brutils import is_valid_cnh
+>>> is_valid_cnh("12345678901")
+False
+>>> is_valid_cnh("A2C45678901")
+False
+>>> is_valid_cnh("98765432100")
+True
+>>> is_valid_cnh("987654321-00")
+True
+```
+
 
 ## Placa de Carro
 
@@ -1249,6 +1307,33 @@ Exemplo:
 'Rio de Janeiro'
 ```
 
+### convert_name_to_uf
+Converte o nome completo de um estado brasileiro para seu código UF.
+
+Esta função recebe o nome completo de um estado brasileiro e retorna o código UF de duas letras correspondente. A comparação ignora maiúsculas/minúsculas e acentos.
+
+Argumentos:
+  * state_name (str): O nome completo do estado (por exemplo, 'São Paulo', 'sao paulo').
+
+Retorna:
+  * str | None: O código UF se encontrado, ou None se o nome do estado for inválido.
+
+Exemplo:
+
+```python
+>>> from brutils.ibge.uf import convert_name_to_uf
+>>> convert_name_to_uf('São Paulo')
+'SP'
+>>> convert_name_to_uf('sao paulo')
+'SP'
+>>> convert_name_to_uf('Rio de Janeiro')
+'RJ'
+>>> convert_name_to_uf('rio de janeiro')
+'RJ'
+>>> convert_name_to_uf('Estado Inválido')
+>>>
+```
+
 ## Feriados
 
 ### is_holiday
@@ -1344,6 +1429,188 @@ Exemplo:
 None
 ```
 
+## Natureza Jurídica
+
+### is_valid_legal_nature
+
+Valida se o código informado existe na tabela oficial. Aceita `NNNN` ou `NNN-N`.  
+O valor é **normalizado** antes da checagem: remove espaços, mantém apenas dígitos e aceita hífen entre o 3º e 4º dígitos.
+
+**Argumentos**
+- `code (str)`: Código de 4 dígitos (ex.: `"2062"` ou `"206-2"`)
+
+**Retorna**
+- `bool`: `True` se existir na tabela, `False` caso contrário.
+
+**Exemplo**
+```python
+>>> from brutils import legal_nature
+>>> legal_nature.is_valid("2062")   
+True
+>>> legal_nature.is_valid("206-2")  
+True
+>>> legal_nature.is_valid("9999")   
+False
+```
+
+### get_legal_nature_description
+
+Retorna a **descrição oficial** do código de Natureza Jurídica. Aceita `NNNN` ou `NNN-N`. Aplica a mesma normalização do `is_valid`.
+
+**Argumentos**
+
+* `code (str)`: Código de 4 dígitos
+
+**Retorna**
+
+* `str | None`: Descrição correspondente ou `None` se o código for inválido ou inexistente.
+
+**Exemplo**
+
+```python
+>>> from brutils import legal_nature
+>>> legal_nature.get_description("2062")   
+'Sociedade Empresária Limitada'
+>>> legal_nature.get_description("101-5")  
+'Órgão Público do Poder Executivo Federal'
+>>> legal_nature.get_description("0000")   
+None
+```
+
+### list_all_legal_nature
+
+Retorna uma cópia do dicionário completo `{codigo: descricao}`.
+
+**Retorna**
+
+* `dict[str, str]`: Mapeamento de todos os códigos para suas descrições.
+
+**Exemplo**
+
+```python
+>>> from brutils import legal_nature 
+>>> data = legal_nature.list_all()
+>>> len(data) > 0               
+True
+>>> data["2062"]                 
+'Sociedade Empresária Limitada'
+```
+
+## RENAVAM
+
+### is_valid_renavam
+
+Valida se os dígitos de verificação do RENAVAM fornecido
+correspondem aos seus 10 dígitos iniciais. Esta função não verifica a existência do veículo;
+ela apenas valida o formato da string e o dígito verificador.
+
+Argumentos:
+
+- renavam (str): O RENAVAM a ser validado, uma string de 11 dígitos.
+
+Retorna:
+
+- bool: Verdadeiro se o RENAVAM for válido  
+  Falso caso contrário.
+
+Exemplo:
+
+```python
+>>> from brutils import is_valid_renavam
+>>> is_valid_renavam("86769597308")
+True
+>>> is_valid_renavam("12345678901")
+False
+```
+
+## Passaporte
+
+### is_valid_passport
+
+Verifica se um número de passaporte brasileiro é válido.
+
+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.
+
+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.
+
+Argumentos:
+- passport (str): A string contendo o número do passaporte a ser verificado.
+
+Retorna:
+- bool: True se o número do passaporte for válido (2 letras seguidas de 6 dígitos). False caso contrário.
+
+Exemplo: 
+```python
+>>> from brutils import is_valid_passport
+>>> is_valid_passport("Ab123456")
+True
+>>> is_valid_passport("12345678")
+False
+>>> is_valid_passport("DC-221345")
+False
+```
+### format_passport
+
+Formata um número de passaporte brasileiro para exibição.
+
+Esta função recebe uma string representando um número de passaporte válido e o retorna formatado (maiúsculas, sem símbolos).
+
+Argumentos:
+- passport (str | None): Um número de passaporte brasileiro (minúsculas ou maiúsculas, possivelmente incluindo símbolos)
+
+Retorna:
+- str: O número do passaporte formatado (maiúsculas, sem símbolos) ou None se a entrada for inválida
+
+Exemplo:
+```python
+>>> from brutils import format_passport
+>>> format_passport("Ab123456")
+AB123456
+>>> format_passport("Ab-123456")
+AB123456
+>>> format_passport("111111")
+None
+```
+### remove_symbols_passport
+
+Remove símbolos ('-', '.' e espaços em branco) de um número de passaporte.
+
+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.
+
+Argumentos:
+- passport (str): A string contendo um número de passaporte
+
+Retorna:
+- str: O número do passaporte com hífens (-), pontos (.) e espaços em branco ( ) removidos.
+
+Exemplo:
+```python 
+>>> from brutils import remove_symbols_passport
+>>> remove_symbols_passport("Ab123456")
+Ab123456
+>>> remove_symbols_passport("Ab-123456")
+Ab123456
+>>> remove_symbols_passport("Ab -. 123456")
+Ab123456
+```
+### generate_passport
+
+Gera uma string com um número de passaporte brasileiro válido aleatório.
+
+Esta função gera uma string com um número de passaporte brasileiro aleatório.
+
+Retorna:
+- str: Uma string com um número de passaporte válido aleatório.
+
+Exemplo:
+```python 
+>>> from brutils import generate_passport
+>>> generate_passport()
+"RY393097"
+>>> generate_passport()
+"ZS840088"
+```
+
 # Novos Utilitários e Reportar Bugs
 
 Caso queira sugerir novas funcionalidades ou reportar bugs, basta criar