brutils


Namebrutils JSON
Version 2.2.0 PyPI version JSON
download
home_pagehttps://github.com/brazilian-utils/brutils
SummaryUtils library for specific Brazilian businesses
upload_time2024-09-12 19:35:13
maintainerNone
docs_urlNone
authorThe Brazilian Utils Organization
requires_python<4.0.0,>=3.8.1
licenseMIT
keywords cpf cnpj cep document validation brazil brazilian
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            <div align="center">
<h1>🇧🇷 Brazilian Utils</h1>

<p>Utils library for Brazilian-specific businesses.</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)
[![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/)

### [Looking for the english version?](README_EN.md)

</div>

# Introdução

Brazilian Utils é uma biblioteca com foco na resolução de problemas que enfrentamos diariamente no
desenvolvimento de aplicações para o business Brasileiro.

- [Instalação](#instalação)
- [Utilização](#utilização)
- [Utilitários](#utilitários)
- [Novos Utilitários e Reportar Bugs](#novos-utilitários-e-reportar-bugs)
- [Dúvidas? Ideias?](#dúvidas-ideias)
- [Contribuindo com o Código do Projeto](#contribuindo-com-o-código-do-projeto)

# Instalação

```bash
pip install brutils
```

# Utilização

Para usar um de nossos utilitários, basta importar a função necessária, como no exemplo abaixo:

```python
>>> from brutils import is_valid_cpf
>>> is_valid_cpf('00011122233')
False
```

# Utilitários

- [CPF](#cpf)
  - [is\_valid\_cpf](#is_valid_cpf)
  - [format\_cpf](#format_cpf)
  - [remove\_symbols\_cpf](#remove_symbols_cpf)
  - [generate\_cpf](#generate_cpf)
- [CNPJ](#cnpj)
  - [is\_valid\_cnpj](#is_valid_cnpj)
  - [format\_cnpj](#format_cnpj)
  - [remove\_symbols\_cnpj](#remove_symbols_cnpj)
  - [generate\_cnpj](#generate_cnpj)
- [CEP](#cep)
  - [is\_valid\_cep](#is_valid_cep)
  - [format\_cep](#format_cep)
  - [remove\_symbols\_cep](#remove_symbols_cep)
  - [generate\_cep](#generate_cep)
  - [get\_address\_from\_cep](#get_address_from_cep)
  - [get\_cep\_information\_from\_address](#get_cep_information_from_address)
- [Telefone](#telefone)
  - [is\_valid\_phone](#is_valid_phone)
  - [format\_phone](#format_phone)
  - [remove\_symbols\_phone](#remove_symbols_phone)
  - [remove\_international\_dialing\_code](#remove_international_dialing_code)
  - [generate\_phone](#generate_phone)
- [Email](#email)
  - [is\_valid\_email](#is_valid_email)
- [Placa de Carro](#placa-de-carro)
  - [is\_valid\_license\_plate](#is_valid_license_plate)
  - [format\_license\_plate](#format_license_plate)
  - [remove\_symbols\_license\_plate](#remove_symbols_license_plate)
  - [generate\_license\_plate](#generate_license_plate)
  - [convert\_license\_plate\_to\_mercosul](#convert_license_plate_to_mercosul)
  - [get\_format\_license\_plate](#get_format_license_plate)
- [PIS](#pis)
  - [is\_valid\_pis](#is_valid_pis)
  - [format\_pis](#format_pis)
  - [remove\_symbols\_pis](#remove_symbols_pis)
  - [generate\_pis](#generate_pis)
- [Processo Jurídico](#processo-jurídico)
  - [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)
- [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

### is_valid_cpf

Retorna se os dígitos de verificação do CPF fornecido
correspondem ao seu número base. Esta função não verifica a existência do CPF;
ela apenas valida o formato da string.

Argumentos:

- cpf (str): O CPF a ser validado, uma string de 11 dígitos

Retorna:

- bool: Verdadeiro se os dígitos de verificação corresponderem ao número base,
          Falso caso contrário.

Exemplo:

```python
>>> from brutils import is_valid_cpf
>>> is_valid_cpf("82178537464")
True
>>> is_valid_cpf('00011122233')
False
```

### format_cpf

Formata um CPF (Cadastro de Pessoa Física brasileiro) para exibição visual.
Esta função recebe uma string de CPF contendo apenas números como entrada e
adiciona símbolos de formatação padrão para exibição.

Argumentos:

- cpf (str): Uma string de CPF contendo apenas números.

Retorna:

- str: O CPF formatado com símbolos visuais se for válido,
         None se não for válido.

Exemplo:

```python
>>> from brutils import format_cpf
>>> format_cpf('82178537464')
'821.785.374-64'
>>> format_cpf("55550207753")
'555.502.077-53'
```

### remove_symbols_cpf

Remove símbolos específicos de uma string de CPF (Cadastro de Pessoa Física
brasileiro). Esta função recebe como entrada uma string de CPF e remove todas as
ocorrências dos caracteres '.', '-' dela.

Argumentos:

- cpf (str): A string de CPF contendo os símbolos a serem removidos.

Retorna:

- str: Uma nova string com os símbolos especificados removidos.

Exemplo:

```python
>>> from brutils import remove_symbols_cpf
>>> remove_symbols_cpf('000.111.222-33')
'00011122233'
```

### generate_cpf

Gerar uma string de dígitos de CPF válida aleatória.

Retorna:

- str: Um CPF válido gerado aleatoriamente.

Exemplo:

```python
>>> from brutils import generate_cpf
>>> generate_cpf()
'17433964657'
>>> generate_cpf()
"10895948109"
```

## CNPJ

### is_valid_cnpj

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
existência do CNPJ; ela só valida o formato da string.

Argumentos:

- cnpj (str): O CNPJ a ser validado.

Retorna:

- bool: True se os dígitos de verificação corresponderem ao número base,
        False caso contrário.

Exemplo:

```python
>>> from brutils import is_valid_cnpj
>>> is_valid_cnpj('03560714000142')
True
>>> is_valid_cnpj('00111222000133')
False
```

### format_cnpj

Formata uma string de CNPJ (Cadastro Nacional da Pessoa Jurídica) para exibição
visual.
Esta função recebe uma string de CNPJ como entrada, valida seu formato e a
formata com símbolos visuais padrão para fins de exibição.

Argumentos:

- cnpj (str): A string de CNPJ a ser formatada para exibição.

Retorna:

- str: O CNPJ formatado com símbolos visuais se for válido, None se não for válido.

Exemplo:

```python
>>> from brutils import format_cnpj
>>> format_cnpj("03560714000142")
'03.560.714/0001-42'
>>> format_cnpj("98765432100100")
None
```

### remove_symbols_cnpj

Remove símbolos específicos de uma string de CNPJ (Cadastro Nacional da Pessoa
Jurídica).
Esta função recebe uma string de CNPJ como entrada e remove todas as
ocorrências dos caracteres '.', '/' e '-' dela.

Argumentos:

- cnpj (str): A string de CNPJ que contém os símbolos a serem removidos.

Retorna:

- str: Uma nova string com os símbolos especificados removidos.

Exemplo:

```python
>>> from brutils import remove_symbols_cnpj
>>> remove_symbols_cnpj('00.111.222/0001-00')
'00111222000100'
```

### 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.

Argumentos:

- branch (int): Um número de filial opcional a ser incluído no CNPJ.

Retorna:

- str: Um CNPJ válido gerado aleatoriamente.

Exemplo:

```python
>>> from brutils import generate_cnpj
>>> generate_cnpj()
'34665388000161'
>>> generate_cnpj(1234)
"01745284123455"
```

## CEP

### is_valid_cep

Verifica se um CEP (Código de Endereçamento Postal) brasileiro é válido.
Para que um CEP seja considerado válido, a entrada deve ser uma string contendo
exatamente 8 dígitos. Esta função não verifica se o CEP é um CEP real, pois
valida apenas o formato da string.

Argumentos:

- cep (str): A string contendo o CEP a ser verificado.

Retorno:

- bool: True se o CEP for válido (8 dígitos), False caso contrário.

Exemplo:

```python
>>> from brutils import is_valid_cep
>>> is_valid_cep('01310200')
True
>>> is_valid_cep("12345")
False
>>> is_valid_cep("abcdefgh")
False
```

### format_cep

Formata um CEP (Código de Endereçamento Postal) brasileiro em um formato padrão.
Esta função recebe um CEP como entrada e, se for um CEP válido com 8 dígitos,
o formata no padrão "12345-678".

Argumentos:

- cep (str): O CEP (Código de Endereçamento Postal) de entrada a ser
              formatado.

Retorna:

- str: O CEP formatado no formato "12345-678" se for válido, None se não for
        válido.

Example:

```python
>>> from brutils import format_cep
>>> format_cep('01310200')
'01310-200'
>>> format_cep("12345678")
"12345-678"
>>> format_cep("12345")
None
```

### remove_symbols_cep

Remove símbolos específicos de um CEP (Código de Endereçamento Postal)
fornecido. Esta função recebe um CEP como entrada e remove todas as ocorrências
dos caracteres '.' e '-' dele.

Argumentos:

- cep (str): O CEP (Código de Endereçamento Postal) de entrada que contém os
               símbolos a serem removidos.

Retorna:

- str: Uma nova string com os símbolos especificados removidos.

Exemplo:

```python
>>> from brutils import remove_symbols_cep
>>> remove_symbols_cep('01310-200')
'01310200'
>>> remove_symbols_cep("123-45.678.9")
"123456789"
>>> remove_symbols_cep("abc.xyz")
"abcxyz"
```

### generate_cep

Gera um número de CEP (Código de Endereçamento Postal) aleatório de 8 dígitos
como uma string.

Retorna:

- str: Um número de 8 dígitos gerado aleatoriamente.

Exemplo:

```python
>>> from brutils import generate_cep
>>> generate_cep()
'77520503'
>>> generate_cep()
'29641407'
```

### get_address_from_cep

Busca as informações de endereço a partir de um CEP (Código de Endereçamento Postal) utilizando a API da ViaCEP.

Argumentos:

- cep (str): O CEP a ser utilizado na busca.
- raise_exceptions (bool, opcional): Se deve gerar exceções quando o CEP for inválido ou não for encontrado. O padrão é False.

Retorna:

- Address | None: Um objeto Address (TypedDict) contendo as informações de endereço se o CEP for encontrado, caso contrário, None.

Exemplo:

```python
>>> from brutils import get_address_from_cep
>>> get_address_from_cep("12345678")
{
    "cep": "12345-678",
    "logradouro": "Rua Example",
    "complemento": "",
    "bairro": "Example",
    "localidade": "Example",
    "uf": "EX",
    "ibge": "1234567",
    "gia": "1234",
    "ddd": "12",
    "siafi": "1234"
}
```

### get_cep_information_from_address

Busca o CEP e outras informações a partir de um endereço utilizando a API da ViaCEP.

Argumentos:

- federal_unit (str): Abreviação de duas letras do estado brasileiro.
- city (str): Nome da cidade.
- street (str): Nome (ou substring) da rua.
- raise_exceptions (bool, opcional): Se deve gerar exceções quando o endereço é inválido ou não foi encontrado. O padrão é False.

Retorna:

- list[Address] | None: Uma lista de objetos Address (TypedDict) contendo as informações de endereço se o endereço for encontrado, None caso contrário.

Exemplo:

```python
>>> from brutils import get_cep_information_from_address
>>> get_cep_information_from_address("EX", "Example", "Rua Example")
[
    {
        "cep": "12345-678",
        "logradouro": "Rua Example",
        "complemento": "",
        "bairro": "Example",
        "localidade": "Example",
        "uf": "EX",
        "ibge": "1234567",
        "gia": "1234",
        "ddd": "12",
        "siafi": "1234"
    }
]
```

## Telefone

### is_valid_phone

Retorna se um número de telefone brasileiro é válido conforme o formato da string.
Não verifica se o número realmente existe.
```

is_valid_phone(phone_number, type)

```

Argumentos:

- phone_number (str):
  - o número de telefone a ser validado
  - apenas dígitos, sem símbolos
  - sem o código do país
  - deve incluir o número de DDD com dois dígitos
  - exemplo: '+55 48 9999 9999' deve ser utilizado como '4899999999'
  - obrigatório

- type (str):
  - 'mobile' para validar apenas números de celular
  - 'landline' para validar apenas números de telefone fixo
  - caso não especificado, valida para um para o outro.
  - opcional

Retorna:

- bool: True se o número é válido, False caso contrário.

Exemplo:

```python
>>> from brutils import is_valid_phone
>>> is_valid_phone('11994029275')
True
>>> is_valid_phone('11994029275', 'mobile')
True
>>> is_valid_phone('1938814933', 'landline')
True
```

### format_phone

Formata um número de telefone para exibição visual. Esta função recebe uma string representando um número de telefone contendo apenas números como entrada e adiciona símbolos de formatação padrão para exibição.

Argumentos:

- phone (str): Uma string representando um número de telefone.

Retorna:

- str: O número de telefone formatado para exibição ou None se não for válido.

Exemplo:

```python
>>> from brutils import format_phone
>>> format_phone("11994029275")
'(11)99402-9275'
>>> format_phone("1635014415")
'(16)3501-4415'
>>> format_phone("333333")
None
```

### remove_symbols_phone

Remove símbolos do número de telefone. Esta função recebe um número de telefone como entrada e remove todos os símbolos, como parênteses '()', traços '-' e espaços ' '.

Argumentos:

- phone (str): O número de telefone de entrada que contém os símbolos a serem removidos.

Retorna:

- str: Uma nova string com os símbolos especificados removidos.

Exemplo:

```python
>>> from brutils import remove_symbols_phone
>>> remove_symbols_phone('(21)2569-6969')
'2125696969'
>>> remove_symbols_phone('11 9999-8888')
'1199998888'
>>> remove_symbols_phone('333333')
'333333'
```

### remove_international_dialing_code

Remove o código internacional (+55) de uma string que contém um número de telefone brasileiro, mantendo outros caracteres especiais.

Argumentos:

- phone (str): O número de telefone de entrada que pode conter o código internacional.

Retorna:

- str: Uma nova string sem o código internacional, preservando outros caracteres especiais.

Exemplo:

```python
>>> from brutils import remove_international_dialing_code
>>> remove_international_dialing_code("5521994029275")
"21994029275"
>>> remove_international_dialing_code("+5521994029275")
"+21994029275"
>>> remove_international_dialing_code("5555994029275")
"55994029275"
>>> remove_international_dialing_code("21994029275")
"21994029275"
>>> remove_international_dialing_code("(+55)21994029275")
"(+)21994029275"
```

### generate_phone

Gera um número de telefone aleatório válido.

Argumentos:

- type (str): Pode ser "landline" ou "mobile".
                Se não for especificado, a função gera um número
                aleatório de qualquer tipo.

Retorna:

- str: Um número de telefone válido gerado aleatoriamente.

Exemplo:

```python
>>> from brutils import generate_phone
>>> generate_phone()
"5929797740"
>>> generate_phone("mobile")
"1899115895"
>>> generate_phone("landline")
"5535317900"
```

## Email

### is_valid_email

Verificar se uma string corresponde a um endereço de e-mail válido.

Argumentos:

- email (str): A string de entrada a ser verificada.

Retorna:

- bool: Verdadeiro se o email for um endereço de e-mail válido, Falso
          caso contrário.

Exemplo:

```python
from brutils import is_valid_email

>>> is_valid_email("joao.ninguem@gmail.com")
True
>>> is_valid_email(".joao.ninguem@gmail.com")
False
>>> is_valid_email("joao.ninguem@gmail.")
False
>>> is_valid_email("joao ninguem@gmail.com")
False
```

## Placa de Carro

### is_valid_license_plate

Verifica se uma placa de carro é válida.
Esta função não verifica se a placa de carro é uma placa de carro real,
apenas valida o formato da string.

Argumentos:

- license_plate (str): Uma string representando uma placa de carro.
- type (str): "old_format" ou "mercosul".
                Se não especificado, verifica um ou outro.

Retorna:

- bool: True se a placa de carro for válida, False caso contrário.

Exemplo:

```python
>>> from brutils import is_valid_license_plate
>>> is_valid_license_plate('ABC1234')
True
>>> is_valid_license_plate('def5678', type="old_format")
True
>>> is_valid_license_plate('ABC4E67')
True
>>> is_valid_license_plate('ABC4E67', type="mercosul")
True
>>> is_valid_license_plate('GHI-4567')
False
```

### format_license_plate

Formata uma placa de carro no padrão correto.
Esta função recebe uma placa de carro em qualquer formato (LLLNNNN ou LLLNLNN) e retorna uma versão formatada.

Argumentos:

- license_plate (str): Uma string representando uma placa de carro.

Retorna:

- str: A string da placa de carro formatada ou
         'None' se a entrada for inválida.

Exemplo:

```python
>>> from brutils import format_license_plate
>>> format_license_plate("ABC1234")
"ABC-1234"
# formato antigo (contém traço)
>>> format_license_plate("abc1234")
"ABC-1234"
# formato antigo (contém traço)
>>> format_license_plate("ABC1D23")
"ABC1D23"
# formato mercosul
>>> format_license_plate("abc1d23")
"ABC1D23"
# formato mercosul
>>> format_license_plate("ABCD123")
None
```

### remove_symbols_license_plate

Remove o símbolo de hífen (-) de uma string de placa de carro.

Argumentos:

- license_plate_number (str): Uma string de placa de carro contendo símbolos a serem removidos.

Retorna:

- str: A string da placa de carro com os símbolos especificados removidos.

Exemplo:

```python
from brutils import remove_symbols_license_plate
>>> remove_symbols_license_plate("ABC-123")
"ABC123"
>>> remove_symbols_license_plate("abc123")
"abc123"
>>> remove_symbols_license_plate("ABCD123")
"ABCD123"
>>> remove_symbols_license_plate("@abc#-#123@")
"@abc##123@"
```

### generate_license_plate

Gera uma placa de carro válida no formato especificado. Caso nenhum formato seja fornecido, ele retornará uma placa de carro no formato Mercosul.

Argumentos:

- format (str): O formato desejado para a placa de carro. 'LLLNNNN' para o formato antigo ou 'LLLNLNN' para o formato Mercosul. O padrão é 'LLLNLNN'.

Retorna:

- str: Um número de placa de carro gerado aleatoriamente ou
   None se o formato for inválido.

Exemplo:

```python
from brutils import generate_license_plate
>>> generate_license_plate()
"ABC1D23"
>>> generate_license_plate(format="LLLNLNN")
"ABC4D56"
>>> generate_license_plate(format="LLLNNNN")
"ABC123"
>>> generate_license_plate(format="invalid")
None
```

### convert_license_plate_to_mercosul

Converte uma placa de carro no formato antigo (LLLNNNN) para o formato Mercosul (LLLNLNN).

Argumentos:

- license_plate(str): Uma string com o tamanho adequado que representa a placa no formato antigo.

Retorna:

- str: A placa Mercosul convertida (LLLNLNN) ou None se a entrada for inválida.

Exemplo:

```python
>>> from brutils import convert_license_plate_to_mercosul
>>> convert_license_plate_to_mercosul("ABC123")
"ABC1C34"
>>> convert_license_plate_to_mercosul("abc123")
"ABC1C34"
>>> convert_license_plate_to_mercosul("ABC1D23")
None
```

### get_format_license_plate

Retorna o formato de uma placa de carro. 'LLLNNNN' para o formato antigo e
'LLLNLNN' para o formato Mercosul.

Argumentos:

- license_plate (str): Uma string de placa de carro sem símbolos.

Retorna:

- str: O formato da placa de carro (LLLNNNN, LLLNLNN) ou
         'None' se o formato for inválido.

Exemplo:

```python
from brutils import get_format_license_plate
>>> get_format_license_plate("ABC123")
"LLLNNNN"
>>> get_format_license_plate("abc123")
"LLLNNNN"
>>> get_format_license_plate("ABC1D23")
"LLLNLNN"
>>> get_format_license_plate("abc1d23")
"LLLNLNN"
>>> get_format_license_plate("ABCD123")
None
```

## PIS

### is_valid_pis

Verifica se o número PIS/PASEP é valido. Apenas números, formatados como string. Não verifica se o PIS/PASEP realmente existe.

Referências:

- <https://www.macoratti.net/alg_pis.htm>.

Argumentos:

- pis (str): Número PIS como uma string com o comprimento apropriado.

Retorna:

- bool: True se o PIS for válido, False caso contrário.

Exemplo:

```python
from brutils import is_valid_pis
>>> is_valid_pis("82178537464")
False
>>> is_valid_pis("12082043519")
True
```

### format_pis

Formata uma string de PIS (Programa de Integração Social) válida com símbolos e adiciona símbolos de formatação padrão para exibição.

Argumentos:

- pis (str): Uma string válida de PIS contendo apenas números.

Retorna:

- str: Uma string de PIS formatada com símbolos visuais padrão ou None se a entrada for inválida.

Exemplo:

```python
from brutils import format_pis
>>> format_pis("17033259504")
'170.33259.50-4'
>>> format_pis("12013128292")
'120.13128.29-2'
```

### remove_symbols_pis

Esta função recebe uma string de PIS (Programa de Integração Social) com símbolos de formatação e retorna uma versão limpa sem símbolos. Remove apenas os símbolos "-" e "." , propositalmente não remove outros símbolos.

Argumentos:

- pis (str): Uma string de PIS que pode conter símbolos de formatação.

Retorna:

- str: Uma string de PIS limpa, sem símbolos de formatação.

Exemplo:

```python
from brutils import remove_symbols_pis

>>> remove_symbols_pis('170.33259.50-4')
'17033259504'
>>> remove_symbols_pis("123.456.789-09")
'12345678909'
>>> remove_symbols_pis('/._')
'/_'
```

### generate_pis

Gera uma string de dígitos contendo um número de um PIS brasileiro válido aleatório.

Retorna:

- str: Um número PIS válido gerado aleatoriamente como string.

Exemplo:

```python
from brutils import generate_pis
>>> generate_pis()
'61352489741'
>>> generate_pis()
'73453349671'
```

## Processo Jurídico

## is_valid_legal_process

Verifica se um ID de processo jurídico é válido, não verifica se o ID de processo jurídico é um ID de processo
jurídico real; ela apenas valida o formato da string.

Argumentos:

- legal_process_id (str): Uma string contendo apenas dígitos que representa
                            o ID do processo jurídico.

Retorna:

- bool: True se o ID do processo jurídico for válido, False caso
          contrário.

Examplo:

```python
>>> from brutils import is_valid_legal_process
>>> is_valid_legal_process('10188748220234018200')
True
>>> is_valid_legal_process('45532346920234025107')
True
>>> is_valid_legal_process('00000000000000000000')
False
>>> is_valid_legal_process('455323423QQWEQWSsasd&*(()')
False
>>>
```

### format_legal_process

Formata um ID de processo jurídico em um formato padrão.

Argumentos:

- legal_process_id (str): Uma string de 20 dígitos que representa o ID do
                            processo jurídico.

Retorna:

- str: O ID do processo jurídico formatado ou None se a entrada for inválida.

Exemplo:

```python
>>> from brutils import format_legal_process
>>> format_legal_process('23141945820055070079')
'2314194-58.2005.5.07.0079'
>>> format_legal_process('00000000000000000000')
'0000000-00.0000.0.00.0000'
>>>
```

### remove_symbols_legal_process

Remove símbolos específicos de um processo jurídico fornecido.

Esta função recebe um processo jurídico como entrada e remove todas as
ocorrências dos caracteres '.' e '-' dele.

Argumentos:

- legal_process (str): Um processo jurídico contendo símbolos a serem
                         removidos.

Retorna:

- str: A string do processo jurídico com os símbolos especificados removidos.

Exemplo:

```python
from brutils import remove_symbols_legal_process
>>> remove_symbols_legal_process("6439067-89.2023.4.04.5902")
"64390678920234045902"
>>> remove_symbols_legal_process("4976023-82.2012.7.00.2263")
"49760238220127002263"
>>> remove_symbols_legal_process("4976023-82.2012.7.00.2263*!*&#")
"49760238220127002263*!*&#"
```

### generate_legal_process

Gera um número válido aleatório de ID de processo jurídico.

Argumentos:

- year (int): O ano para o ID do processo jurídico (o padrão é o ano atual).
                Não pode ser um ano do passado.
- orgao (int): O órgão (1-9) para o ID do processo jurídico
                 (o padrão é aleatório).

Retorna:

- str: Um ID de processo jurídico gerado aleatoriamente.
         None caso algum dos argumento seja inválido.

Exemplo:

```python
>>> from brutils import generate_legal_process
>>> generate_legal_process()
"45676401020238170592"
>>> generate_legal_process(ano=2025)
"32110268020258121130"
>>> generate_legal_process(orgao=5)
"37573041520235090313"
>>> generate_legal_process(ano=2024, orgao=4)
"33158248820244017105"
```

## Titulo Eleitoral

### is_valid_voter_id

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.

Retorna:

- bool: True se o número do título de eleitor for válido. False, caso contrário.

Exemplo:

```python
>>> from brutils import is_valid_voter_id
>>> is_valid_voter_id('123456789011')
False
>>> is_valid_voter_id('427503840213')
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
uma nova [issue][github-issues] e iremos lhe responder por lá!

(Para saber mais sobre github issues, confira a [documentação oficial do GitHub][github-issues-doc]).

# Dúvidas? Ideias?

Dúvidas de como utilizar a biblioteca? Novas ideias para o projeto?
Quer compartilhar algo com a gente? Fique à vontade para criar um tópico no nosso
[Discussions][github-discussions] que iremos interagir por lá!

(Para saber mais sobre github discussions, confira a
[documentação oficial do GitHub][github-discussions-doc]).

# Contribuindo com o Código do Projeto

Sua colaboração é sempre muito bem-vinda! Preparamos o arquivo [CONTRIBUTING.md][contributing] para
te ajudar nos primeiros passos. Lá você encontrará toda a informação necessária para contribuir com
o projeto. Não hesite em nos perguntar utilizando o [GitHub Discussions][github-discussions] caso
haja qualquer dificuldade ou dúvida. Toda ajuda conta!

Vamos construir juntos! 🚀🚀

[contributing]: CONTRIBUTING.md
[github-discussions-doc]: https://docs.github.com/pt/discussions
[github-discussions]: https://github.com/brazilian-utils/brutils-python/discussions
[github-issues-doc]: https://docs.github.com/pt/issues/tracking-your-work-with-issues/creating-an-issue
[github-issues]: https://github.com/brazilian-utils/brutils-python/issues

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/brazilian-utils/brutils",
    "name": "brutils",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4.0.0,>=3.8.1",
    "maintainer_email": null,
    "keywords": "cpf, cnpj, cep, document, validation, brazil, brazilian",
    "author": "The Brazilian Utils Organization",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/74/0d/814db7c7d58d929011f86d22a2e3c99de9e5b8e74656f164c0aa4238fc66/brutils-2.2.0.tar.gz",
    "platform": null,
    "description": "<div align=\"center\">\n<h1>\ud83c\udde7\ud83c\uddf7 Brazilian Utils</h1>\n\n<p>Utils library for Brazilian-specific businesses.</p>\n\n[![codecov](https://codecov.io/gh/brazilian-utils/brutils-python/branch/main/graph/badge.svg?token=5KNECS8JYF)](https://codecov.io/gh/brazilian-utils/brutils-python)\n[![Downloads per Month](https://shields.io/pypi/dm/brutils)](https://pypistats.org/packages/brutils)\n[![Package version](https://shields.io/pypi/v/brutils)](https://pypi.org/project/brutils/)\n\n### [Looking for the english version?](README_EN.md)\n\n</div>\n\n# Introdu\u00e7\u00e3o\n\nBrazilian Utils \u00e9 uma biblioteca com foco na resolu\u00e7\u00e3o de problemas que enfrentamos diariamente no\ndesenvolvimento de aplica\u00e7\u00f5es para o business Brasileiro.\n\n- [Instala\u00e7\u00e3o](#instala\u00e7\u00e3o)\n- [Utiliza\u00e7\u00e3o](#utiliza\u00e7\u00e3o)\n- [Utilit\u00e1rios](#utilit\u00e1rios)\n- [Novos Utilit\u00e1rios e Reportar Bugs](#novos-utilit\u00e1rios-e-reportar-bugs)\n- [D\u00favidas? Ideias?](#d\u00favidas-ideias)\n- [Contribuindo com o C\u00f3digo do Projeto](#contribuindo-com-o-c\u00f3digo-do-projeto)\n\n# Instala\u00e7\u00e3o\n\n```bash\npip install brutils\n```\n\n# Utiliza\u00e7\u00e3o\n\nPara usar um de nossos utilit\u00e1rios, basta importar a fun\u00e7\u00e3o necess\u00e1ria, como no exemplo abaixo:\n\n```python\n>>> from brutils import is_valid_cpf\n>>> is_valid_cpf('00011122233')\nFalse\n```\n\n# Utilit\u00e1rios\n\n- [CPF](#cpf)\n  - [is\\_valid\\_cpf](#is_valid_cpf)\n  - [format\\_cpf](#format_cpf)\n  - [remove\\_symbols\\_cpf](#remove_symbols_cpf)\n  - [generate\\_cpf](#generate_cpf)\n- [CNPJ](#cnpj)\n  - [is\\_valid\\_cnpj](#is_valid_cnpj)\n  - [format\\_cnpj](#format_cnpj)\n  - [remove\\_symbols\\_cnpj](#remove_symbols_cnpj)\n  - [generate\\_cnpj](#generate_cnpj)\n- [CEP](#cep)\n  - [is\\_valid\\_cep](#is_valid_cep)\n  - [format\\_cep](#format_cep)\n  - [remove\\_symbols\\_cep](#remove_symbols_cep)\n  - [generate\\_cep](#generate_cep)\n  - [get\\_address\\_from\\_cep](#get_address_from_cep)\n  - [get\\_cep\\_information\\_from\\_address](#get_cep_information_from_address)\n- [Telefone](#telefone)\n  - [is\\_valid\\_phone](#is_valid_phone)\n  - [format\\_phone](#format_phone)\n  - [remove\\_symbols\\_phone](#remove_symbols_phone)\n  - [remove\\_international\\_dialing\\_code](#remove_international_dialing_code)\n  - [generate\\_phone](#generate_phone)\n- [Email](#email)\n  - [is\\_valid\\_email](#is_valid_email)\n- [Placa de Carro](#placa-de-carro)\n  - [is\\_valid\\_license\\_plate](#is_valid_license_plate)\n  - [format\\_license\\_plate](#format_license_plate)\n  - [remove\\_symbols\\_license\\_plate](#remove_symbols_license_plate)\n  - [generate\\_license\\_plate](#generate_license_plate)\n  - [convert\\_license\\_plate\\_to\\_mercosul](#convert_license_plate_to_mercosul)\n  - [get\\_format\\_license\\_plate](#get_format_license_plate)\n- [PIS](#pis)\n  - [is\\_valid\\_pis](#is_valid_pis)\n  - [format\\_pis](#format_pis)\n  - [remove\\_symbols\\_pis](#remove_symbols_pis)\n  - [generate\\_pis](#generate_pis)\n- [Processo Jur\u00eddico](#processo-jur\u00eddico)\n  - [is\\_valid\\_legal\\_process](#is_valid_legal_process)\n  - [format\\_legal\\_process](#format_legal_process)\n  - [remove\\_symbols\\_legal\\_process](#remove_symbols_legal_process)\n  - [generate\\_legal\\_process](#generate_legal_process)\n- [T\u00edtulo Eleitoral](#titulo-eleitoral)\n  - [is_valid_voter_id](#is_valid_voter_id)\n  - [format_voter_id](#format_voter_id)\n  - [generate_voter_id](#generate_voter_id)\n\n## CPF\n\n### is_valid_cpf\n\nRetorna se os d\u00edgitos de verifica\u00e7\u00e3o do CPF fornecido\ncorrespondem ao seu n\u00famero base. Esta fun\u00e7\u00e3o n\u00e3o verifica a exist\u00eancia do CPF;\nela apenas valida o formato da string.\n\nArgumentos:\n\n- cpf (str): O CPF a ser validado, uma string de 11 d\u00edgitos\n\nRetorna:\n\n- bool: Verdadeiro se os d\u00edgitos de verifica\u00e7\u00e3o corresponderem ao n\u00famero base,\n          Falso caso contr\u00e1rio.\n\nExemplo:\n\n```python\n>>> from brutils import is_valid_cpf\n>>> is_valid_cpf(\"82178537464\")\nTrue\n>>> is_valid_cpf('00011122233')\nFalse\n```\n\n### format_cpf\n\nFormata um CPF (Cadastro de Pessoa F\u00edsica brasileiro) para exibi\u00e7\u00e3o visual.\nEsta fun\u00e7\u00e3o recebe uma string de CPF contendo apenas n\u00fameros como entrada e\nadiciona s\u00edmbolos de formata\u00e7\u00e3o padr\u00e3o para exibi\u00e7\u00e3o.\n\nArgumentos:\n\n- cpf (str): Uma string de CPF contendo apenas n\u00fameros.\n\nRetorna:\n\n- str: O CPF formatado com s\u00edmbolos visuais se for v\u00e1lido,\n         None se n\u00e3o for v\u00e1lido.\n\nExemplo:\n\n```python\n>>> from brutils import format_cpf\n>>> format_cpf('82178537464')\n'821.785.374-64'\n>>> format_cpf(\"55550207753\")\n'555.502.077-53'\n```\n\n### remove_symbols_cpf\n\nRemove s\u00edmbolos espec\u00edficos de uma string de CPF (Cadastro de Pessoa F\u00edsica\nbrasileiro). Esta fun\u00e7\u00e3o recebe como entrada uma string de CPF e remove todas as\nocorr\u00eancias dos caracteres '.', '-' dela.\n\nArgumentos:\n\n- cpf (str): A string de CPF contendo os s\u00edmbolos a serem removidos.\n\nRetorna:\n\n- str: Uma nova string com os s\u00edmbolos especificados removidos.\n\nExemplo:\n\n```python\n>>> from brutils import remove_symbols_cpf\n>>> remove_symbols_cpf('000.111.222-33')\n'00011122233'\n```\n\n### generate_cpf\n\nGerar uma string de d\u00edgitos de CPF v\u00e1lida aleat\u00f3ria.\n\nRetorna:\n\n- str: Um CPF v\u00e1lido gerado aleatoriamente.\n\nExemplo:\n\n```python\n>>> from brutils import generate_cpf\n>>> generate_cpf()\n'17433964657'\n>>> generate_cpf()\n\"10895948109\"\n```\n\n## CNPJ\n\n### is_valid_cnpj\n\nVerifica se os d\u00edgitos de verifica\u00e7\u00e3o do CNPJ (Cadastro Nacional da Pessoa\nJur\u00eddica) fornecido correspondem ao seu n\u00famero base. A entrada deve ser uma\nstring de d\u00edgitos com o comprimento apropriado. Esta fun\u00e7\u00e3o n\u00e3o verifica a\nexist\u00eancia do CNPJ; ela s\u00f3 valida o formato da string.\n\nArgumentos:\n\n- cnpj (str): O CNPJ a ser validado.\n\nRetorna:\n\n- bool: True se os d\u00edgitos de verifica\u00e7\u00e3o corresponderem ao n\u00famero base,\n        False caso contr\u00e1rio.\n\nExemplo:\n\n```python\n>>> from brutils import is_valid_cnpj\n>>> is_valid_cnpj('03560714000142')\nTrue\n>>> is_valid_cnpj('00111222000133')\nFalse\n```\n\n### format_cnpj\n\nFormata uma string de CNPJ (Cadastro Nacional da Pessoa Jur\u00eddica) para exibi\u00e7\u00e3o\nvisual.\nEsta fun\u00e7\u00e3o recebe uma string de CNPJ como entrada, valida seu formato e a\nformata com s\u00edmbolos visuais padr\u00e3o para fins de exibi\u00e7\u00e3o.\n\nArgumentos:\n\n- cnpj (str): A string de CNPJ a ser formatada para exibi\u00e7\u00e3o.\n\nRetorna:\n\n- str: O CNPJ formatado com s\u00edmbolos visuais se for v\u00e1lido, None se n\u00e3o for v\u00e1lido.\n\nExemplo:\n\n```python\n>>> from brutils import format_cnpj\n>>> format_cnpj(\"03560714000142\")\n'03.560.714/0001-42'\n>>> format_cnpj(\"98765432100100\")\nNone\n```\n\n### remove_symbols_cnpj\n\nRemove s\u00edmbolos espec\u00edficos de uma string de CNPJ (Cadastro Nacional da Pessoa\nJur\u00eddica).\nEsta fun\u00e7\u00e3o recebe uma string de CNPJ como entrada e remove todas as\nocorr\u00eancias dos caracteres '.', '/' e '-' dela.\n\nArgumentos:\n\n- cnpj (str): A string de CNPJ que cont\u00e9m os s\u00edmbolos a serem removidos.\n\nRetorna:\n\n- str: Uma nova string com os s\u00edmbolos especificados removidos.\n\nExemplo:\n\n```python\n>>> from brutils import remove_symbols_cnpj\n>>> remove_symbols_cnpj('00.111.222/0001-00')\n'00111222000100'\n```\n\n### generate_cnpj\n\nGera uma string de d\u00edgitos CNPJ v\u00e1lida aleat\u00f3ria. Um n\u00famero de filial\nopcional pode ser fornecido; o padr\u00e3o \u00e9 1.\n\nArgumentos:\n\n- branch (int): Um n\u00famero de filial opcional a ser inclu\u00eddo no CNPJ.\n\nRetorna:\n\n- str: Um CNPJ v\u00e1lido gerado aleatoriamente.\n\nExemplo:\n\n```python\n>>> from brutils import generate_cnpj\n>>> generate_cnpj()\n'34665388000161'\n>>> generate_cnpj(1234)\n\"01745284123455\"\n```\n\n## CEP\n\n### is_valid_cep\n\nVerifica se um CEP (C\u00f3digo de Endere\u00e7amento Postal) brasileiro \u00e9 v\u00e1lido.\nPara que um CEP seja considerado v\u00e1lido, a entrada deve ser uma string contendo\nexatamente 8 d\u00edgitos. Esta fun\u00e7\u00e3o n\u00e3o verifica se o CEP \u00e9 um CEP real, pois\nvalida apenas o formato da string.\n\nArgumentos:\n\n- cep (str): A string contendo o CEP a ser verificado.\n\nRetorno:\n\n- bool: True se o CEP for v\u00e1lido (8 d\u00edgitos), False caso contr\u00e1rio.\n\nExemplo:\n\n```python\n>>> from brutils import is_valid_cep\n>>> is_valid_cep('01310200')\nTrue\n>>> is_valid_cep(\"12345\")\nFalse\n>>> is_valid_cep(\"abcdefgh\")\nFalse\n```\n\n### format_cep\n\nFormata um CEP (C\u00f3digo de Endere\u00e7amento Postal) brasileiro em um formato padr\u00e3o.\nEsta fun\u00e7\u00e3o recebe um CEP como entrada e, se for um CEP v\u00e1lido com 8 d\u00edgitos,\no formata no padr\u00e3o \"12345-678\".\n\nArgumentos:\n\n- cep (str): O CEP (C\u00f3digo de Endere\u00e7amento Postal) de entrada a ser\n              formatado.\n\nRetorna:\n\n- str: O CEP formatado no formato \"12345-678\" se for v\u00e1lido, None se n\u00e3o for\n        v\u00e1lido.\n\nExample:\n\n```python\n>>> from brutils import format_cep\n>>> format_cep('01310200')\n'01310-200'\n>>> format_cep(\"12345678\")\n\"12345-678\"\n>>> format_cep(\"12345\")\nNone\n```\n\n### remove_symbols_cep\n\nRemove s\u00edmbolos espec\u00edficos de um CEP (C\u00f3digo de Endere\u00e7amento Postal)\nfornecido. Esta fun\u00e7\u00e3o recebe um CEP como entrada e remove todas as ocorr\u00eancias\ndos caracteres '.' e '-' dele.\n\nArgumentos:\n\n- cep (str): O CEP (C\u00f3digo de Endere\u00e7amento Postal) de entrada que cont\u00e9m os\n               s\u00edmbolos a serem removidos.\n\nRetorna:\n\n- str: Uma nova string com os s\u00edmbolos especificados removidos.\n\nExemplo:\n\n```python\n>>> from brutils import remove_symbols_cep\n>>> remove_symbols_cep('01310-200')\n'01310200'\n>>> remove_symbols_cep(\"123-45.678.9\")\n\"123456789\"\n>>> remove_symbols_cep(\"abc.xyz\")\n\"abcxyz\"\n```\n\n### generate_cep\n\nGera um n\u00famero de CEP (C\u00f3digo de Endere\u00e7amento Postal) aleat\u00f3rio de 8 d\u00edgitos\ncomo uma string.\n\nRetorna:\n\n- str: Um n\u00famero de 8 d\u00edgitos gerado aleatoriamente.\n\nExemplo:\n\n```python\n>>> from brutils import generate_cep\n>>> generate_cep()\n'77520503'\n>>> generate_cep()\n'29641407'\n```\n\n### get_address_from_cep\n\nBusca as informa\u00e7\u00f5es de endere\u00e7o a partir de um CEP (C\u00f3digo de Endere\u00e7amento Postal) utilizando a API da ViaCEP.\n\nArgumentos:\n\n- cep (str): O CEP a ser utilizado na busca.\n- raise_exceptions (bool, opcional): Se deve gerar exce\u00e7\u00f5es quando o CEP for inv\u00e1lido ou n\u00e3o for encontrado. O padr\u00e3o \u00e9 False.\n\nRetorna:\n\n- Address | None: Um objeto Address (TypedDict) contendo as informa\u00e7\u00f5es de endere\u00e7o se o CEP for encontrado, caso contr\u00e1rio, None.\n\nExemplo:\n\n```python\n>>> from brutils import get_address_from_cep\n>>> get_address_from_cep(\"12345678\")\n{\n    \"cep\": \"12345-678\",\n    \"logradouro\": \"Rua Example\",\n    \"complemento\": \"\",\n    \"bairro\": \"Example\",\n    \"localidade\": \"Example\",\n    \"uf\": \"EX\",\n    \"ibge\": \"1234567\",\n    \"gia\": \"1234\",\n    \"ddd\": \"12\",\n    \"siafi\": \"1234\"\n}\n```\n\n### get_cep_information_from_address\n\nBusca o CEP e outras informa\u00e7\u00f5es a partir de um endere\u00e7o utilizando a API da ViaCEP.\n\nArgumentos:\n\n- federal_unit (str): Abrevia\u00e7\u00e3o de duas letras do estado brasileiro.\n- city (str): Nome da cidade.\n- street (str): Nome (ou substring) da rua.\n- raise_exceptions (bool, opcional): Se deve gerar exce\u00e7\u00f5es quando o endere\u00e7o \u00e9 inv\u00e1lido ou n\u00e3o foi encontrado. O padr\u00e3o \u00e9 False.\n\nRetorna:\n\n- list[Address] | None: Uma lista de objetos Address (TypedDict) contendo as informa\u00e7\u00f5es de endere\u00e7o se o endere\u00e7o for encontrado, None caso contr\u00e1rio.\n\nExemplo:\n\n```python\n>>> from brutils import get_cep_information_from_address\n>>> get_cep_information_from_address(\"EX\", \"Example\", \"Rua Example\")\n[\n    {\n        \"cep\": \"12345-678\",\n        \"logradouro\": \"Rua Example\",\n        \"complemento\": \"\",\n        \"bairro\": \"Example\",\n        \"localidade\": \"Example\",\n        \"uf\": \"EX\",\n        \"ibge\": \"1234567\",\n        \"gia\": \"1234\",\n        \"ddd\": \"12\",\n        \"siafi\": \"1234\"\n    }\n]\n```\n\n## Telefone\n\n### is_valid_phone\n\nRetorna se um n\u00famero de telefone brasileiro \u00e9 v\u00e1lido conforme o formato da string.\nN\u00e3o verifica se o n\u00famero realmente existe.\n```\n\nis_valid_phone(phone_number, type)\n\n```\n\nArgumentos:\n\n- phone_number (str):\n  - o n\u00famero de telefone a ser validado\n  - apenas d\u00edgitos, sem s\u00edmbolos\n  - sem o c\u00f3digo do pa\u00eds\n  - deve incluir o n\u00famero de DDD com dois d\u00edgitos\n  - exemplo: '+55 48 9999 9999' deve ser utilizado como '4899999999'\n  - obrigat\u00f3rio\n\n- type (str):\n  - 'mobile' para validar apenas n\u00fameros de celular\n  - 'landline' para validar apenas n\u00fameros de telefone fixo\n  - caso n\u00e3o especificado, valida para um para o outro.\n  - opcional\n\nRetorna:\n\n- bool: True se o n\u00famero \u00e9 v\u00e1lido, False caso contr\u00e1rio.\n\nExemplo:\n\n```python\n>>> from brutils import is_valid_phone\n>>> is_valid_phone('11994029275')\nTrue\n>>> is_valid_phone('11994029275', 'mobile')\nTrue\n>>> is_valid_phone('1938814933', 'landline')\nTrue\n```\n\n### format_phone\n\nFormata um n\u00famero de telefone para exibi\u00e7\u00e3o visual. Esta fun\u00e7\u00e3o recebe uma string representando um n\u00famero de telefone contendo apenas n\u00fameros como entrada e adiciona s\u00edmbolos de formata\u00e7\u00e3o padr\u00e3o para exibi\u00e7\u00e3o.\n\nArgumentos:\n\n- phone (str): Uma string representando um n\u00famero de telefone.\n\nRetorna:\n\n- str: O n\u00famero de telefone formatado para exibi\u00e7\u00e3o ou None se n\u00e3o for v\u00e1lido.\n\nExemplo:\n\n```python\n>>> from brutils import format_phone\n>>> format_phone(\"11994029275\")\n'(11)99402-9275'\n>>> format_phone(\"1635014415\")\n'(16)3501-4415'\n>>> format_phone(\"333333\")\nNone\n```\n\n### remove_symbols_phone\n\nRemove s\u00edmbolos do n\u00famero de telefone. Esta fun\u00e7\u00e3o recebe um n\u00famero de telefone como entrada e remove todos os s\u00edmbolos, como par\u00eanteses '()', tra\u00e7os '-' e espa\u00e7os ' '.\n\nArgumentos:\n\n- phone (str): O n\u00famero de telefone de entrada que cont\u00e9m os s\u00edmbolos a serem removidos.\n\nRetorna:\n\n- str: Uma nova string com os s\u00edmbolos especificados removidos.\n\nExemplo:\n\n```python\n>>> from brutils import remove_symbols_phone\n>>> remove_symbols_phone('(21)2569-6969')\n'2125696969'\n>>> remove_symbols_phone('11 9999-8888')\n'1199998888'\n>>> remove_symbols_phone('333333')\n'333333'\n```\n\n### remove_international_dialing_code\n\nRemove o c\u00f3digo internacional (+55) de uma string que cont\u00e9m um n\u00famero de telefone brasileiro, mantendo outros caracteres especiais.\n\nArgumentos:\n\n- phone (str): O n\u00famero de telefone de entrada que pode conter o c\u00f3digo internacional.\n\nRetorna:\n\n- str: Uma nova string sem o c\u00f3digo internacional, preservando outros caracteres especiais.\n\nExemplo:\n\n```python\n>>> from brutils import remove_international_dialing_code\n>>> remove_international_dialing_code(\"5521994029275\")\n\"21994029275\"\n>>> remove_international_dialing_code(\"+5521994029275\")\n\"+21994029275\"\n>>> remove_international_dialing_code(\"5555994029275\")\n\"55994029275\"\n>>> remove_international_dialing_code(\"21994029275\")\n\"21994029275\"\n>>> remove_international_dialing_code(\"(+55)21994029275\")\n\"(+)21994029275\"\n```\n\n### generate_phone\n\nGera um n\u00famero de telefone aleat\u00f3rio v\u00e1lido.\n\nArgumentos:\n\n- type (str): Pode ser \"landline\" ou \"mobile\".\n                Se n\u00e3o for especificado, a fun\u00e7\u00e3o gera um n\u00famero\n                aleat\u00f3rio de qualquer tipo.\n\nRetorna:\n\n- str: Um n\u00famero de telefone v\u00e1lido gerado aleatoriamente.\n\nExemplo:\n\n```python\n>>> from brutils import generate_phone\n>>> generate_phone()\n\"5929797740\"\n>>> generate_phone(\"mobile\")\n\"1899115895\"\n>>> generate_phone(\"landline\")\n\"5535317900\"\n```\n\n## Email\n\n### is_valid_email\n\nVerificar se uma string corresponde a um endere\u00e7o de e-mail v\u00e1lido.\n\nArgumentos:\n\n- email (str): A string de entrada a ser verificada.\n\nRetorna:\n\n- bool: Verdadeiro se o email for um endere\u00e7o de e-mail v\u00e1lido, Falso\n          caso contr\u00e1rio.\n\nExemplo:\n\n```python\nfrom brutils import is_valid_email\n\n>>> is_valid_email(\"joao.ninguem@gmail.com\")\nTrue\n>>> is_valid_email(\".joao.ninguem@gmail.com\")\nFalse\n>>> is_valid_email(\"joao.ninguem@gmail.\")\nFalse\n>>> is_valid_email(\"joao ninguem@gmail.com\")\nFalse\n```\n\n## Placa de Carro\n\n### is_valid_license_plate\n\nVerifica se uma placa de carro \u00e9 v\u00e1lida.\nEsta fun\u00e7\u00e3o n\u00e3o verifica se a placa de carro \u00e9 uma placa de carro real,\napenas valida o formato da string.\n\nArgumentos:\n\n- license_plate (str): Uma string representando uma placa de carro.\n- type (str): \"old_format\" ou \"mercosul\".\n                Se n\u00e3o especificado, verifica um ou outro.\n\nRetorna:\n\n- bool: True se a placa de carro for v\u00e1lida, False caso contr\u00e1rio.\n\nExemplo:\n\n```python\n>>> from brutils import is_valid_license_plate\n>>> is_valid_license_plate('ABC1234')\nTrue\n>>> is_valid_license_plate('def5678', type=\"old_format\")\nTrue\n>>> is_valid_license_plate('ABC4E67')\nTrue\n>>> is_valid_license_plate('ABC4E67', type=\"mercosul\")\nTrue\n>>> is_valid_license_plate('GHI-4567')\nFalse\n```\n\n### format_license_plate\n\nFormata uma placa de carro no padr\u00e3o correto.\nEsta fun\u00e7\u00e3o recebe uma placa de carro em qualquer formato (LLLNNNN ou LLLNLNN) e retorna uma vers\u00e3o formatada.\n\nArgumentos:\n\n- license_plate (str): Uma string representando uma placa de carro.\n\nRetorna:\n\n- str: A string da placa de carro formatada ou\n         'None' se a entrada for inv\u00e1lida.\n\nExemplo:\n\n```python\n>>> from brutils import format_license_plate\n>>> format_license_plate(\"ABC1234\")\n\"ABC-1234\"\n# formato antigo (cont\u00e9m tra\u00e7o)\n>>> format_license_plate(\"abc1234\")\n\"ABC-1234\"\n# formato antigo (cont\u00e9m tra\u00e7o)\n>>> format_license_plate(\"ABC1D23\")\n\"ABC1D23\"\n# formato mercosul\n>>> format_license_plate(\"abc1d23\")\n\"ABC1D23\"\n# formato mercosul\n>>> format_license_plate(\"ABCD123\")\nNone\n```\n\n### remove_symbols_license_plate\n\nRemove o s\u00edmbolo de h\u00edfen (-) de uma string de placa de carro.\n\nArgumentos:\n\n- license_plate_number (str): Uma string de placa de carro contendo s\u00edmbolos a serem removidos.\n\nRetorna:\n\n- str: A string da placa de carro com os s\u00edmbolos especificados removidos.\n\nExemplo:\n\n```python\nfrom brutils import remove_symbols_license_plate\n>>> remove_symbols_license_plate(\"ABC-123\")\n\"ABC123\"\n>>> remove_symbols_license_plate(\"abc123\")\n\"abc123\"\n>>> remove_symbols_license_plate(\"ABCD123\")\n\"ABCD123\"\n>>> remove_symbols_license_plate(\"@abc#-#123@\")\n\"@abc##123@\"\n```\n\n### generate_license_plate\n\nGera uma placa de carro v\u00e1lida no formato especificado. Caso nenhum formato seja fornecido, ele retornar\u00e1 uma placa de carro no formato Mercosul.\n\nArgumentos:\n\n- format (str): O formato desejado para a placa de carro. 'LLLNNNN' para o formato antigo ou 'LLLNLNN' para o formato Mercosul. O padr\u00e3o \u00e9 'LLLNLNN'.\n\nRetorna:\n\n- str: Um n\u00famero de placa de carro gerado aleatoriamente ou\n   None se o formato for inv\u00e1lido.\n\nExemplo:\n\n```python\nfrom brutils import generate_license_plate\n>>> generate_license_plate()\n\"ABC1D23\"\n>>> generate_license_plate(format=\"LLLNLNN\")\n\"ABC4D56\"\n>>> generate_license_plate(format=\"LLLNNNN\")\n\"ABC123\"\n>>> generate_license_plate(format=\"invalid\")\nNone\n```\n\n### convert_license_plate_to_mercosul\n\nConverte uma placa de carro no formato antigo (LLLNNNN) para o formato Mercosul (LLLNLNN).\n\nArgumentos:\n\n- license_plate(str): Uma string com o tamanho adequado que representa a placa no formato antigo.\n\nRetorna:\n\n- str: A placa Mercosul convertida (LLLNLNN) ou None se a entrada for inv\u00e1lida.\n\nExemplo:\n\n```python\n>>> from brutils import convert_license_plate_to_mercosul\n>>> convert_license_plate_to_mercosul(\"ABC123\")\n\"ABC1C34\"\n>>> convert_license_plate_to_mercosul(\"abc123\")\n\"ABC1C34\"\n>>> convert_license_plate_to_mercosul(\"ABC1D23\")\nNone\n```\n\n### get_format_license_plate\n\nRetorna o formato de uma placa de carro. 'LLLNNNN' para o formato antigo e\n'LLLNLNN' para o formato Mercosul.\n\nArgumentos:\n\n- license_plate (str): Uma string de placa de carro sem s\u00edmbolos.\n\nRetorna:\n\n- str: O formato da placa de carro (LLLNNNN, LLLNLNN) ou\n         'None' se o formato for inv\u00e1lido.\n\nExemplo:\n\n```python\nfrom brutils import get_format_license_plate\n>>> get_format_license_plate(\"ABC123\")\n\"LLLNNNN\"\n>>> get_format_license_plate(\"abc123\")\n\"LLLNNNN\"\n>>> get_format_license_plate(\"ABC1D23\")\n\"LLLNLNN\"\n>>> get_format_license_plate(\"abc1d23\")\n\"LLLNLNN\"\n>>> get_format_license_plate(\"ABCD123\")\nNone\n```\n\n## PIS\n\n### is_valid_pis\n\nVerifica se o n\u00famero PIS/PASEP \u00e9 valido. Apenas n\u00fameros, formatados como string. N\u00e3o verifica se o PIS/PASEP realmente existe.\n\nRefer\u00eancias:\n\n- <https://www.macoratti.net/alg_pis.htm>.\n\nArgumentos:\n\n- pis (str): N\u00famero PIS como uma string com o comprimento apropriado.\n\nRetorna:\n\n- bool: True se o PIS for v\u00e1lido, False caso contr\u00e1rio.\n\nExemplo:\n\n```python\nfrom brutils import is_valid_pis\n>>> is_valid_pis(\"82178537464\")\nFalse\n>>> is_valid_pis(\"12082043519\")\nTrue\n```\n\n### format_pis\n\nFormata uma string de PIS (Programa de Integra\u00e7\u00e3o Social) v\u00e1lida com s\u00edmbolos e adiciona s\u00edmbolos de formata\u00e7\u00e3o padr\u00e3o para exibi\u00e7\u00e3o.\n\nArgumentos:\n\n- pis (str): Uma string v\u00e1lida de PIS contendo apenas n\u00fameros.\n\nRetorna:\n\n- str: Uma string de PIS formatada com s\u00edmbolos visuais padr\u00e3o ou None se a entrada for inv\u00e1lida.\n\nExemplo:\n\n```python\nfrom brutils import format_pis\n>>> format_pis(\"17033259504\")\n'170.33259.50-4'\n>>> format_pis(\"12013128292\")\n'120.13128.29-2'\n```\n\n### remove_symbols_pis\n\nEsta fun\u00e7\u00e3o recebe uma string de PIS (Programa de Integra\u00e7\u00e3o Social) com s\u00edmbolos de formata\u00e7\u00e3o e retorna uma vers\u00e3o limpa sem s\u00edmbolos. Remove apenas os s\u00edmbolos \"-\" e \".\" , propositalmente n\u00e3o remove outros s\u00edmbolos.\n\nArgumentos:\n\n- pis (str): Uma string de PIS que pode conter s\u00edmbolos de formata\u00e7\u00e3o.\n\nRetorna:\n\n- str: Uma string de PIS limpa, sem s\u00edmbolos de formata\u00e7\u00e3o.\n\nExemplo:\n\n```python\nfrom brutils import remove_symbols_pis\n\n>>> remove_symbols_pis('170.33259.50-4')\n'17033259504'\n>>> remove_symbols_pis(\"123.456.789-09\")\n'12345678909'\n>>> remove_symbols_pis('/._')\n'/_'\n```\n\n### generate_pis\n\nGera uma string de d\u00edgitos contendo um n\u00famero de um PIS brasileiro v\u00e1lido aleat\u00f3rio.\n\nRetorna:\n\n- str: Um n\u00famero PIS v\u00e1lido gerado aleatoriamente como string.\n\nExemplo:\n\n```python\nfrom brutils import generate_pis\n>>> generate_pis()\n'61352489741'\n>>> generate_pis()\n'73453349671'\n```\n\n## Processo Jur\u00eddico\n\n## is_valid_legal_process\n\nVerifica se um ID de processo jur\u00eddico \u00e9 v\u00e1lido, n\u00e3o verifica se o ID de processo jur\u00eddico \u00e9 um ID de processo\njur\u00eddico real; ela apenas valida o formato da string.\n\nArgumentos:\n\n- legal_process_id (str): Uma string contendo apenas d\u00edgitos que representa\n                            o ID do processo jur\u00eddico.\n\nRetorna:\n\n- bool: True se o ID do processo jur\u00eddico for v\u00e1lido, False caso\n          contr\u00e1rio.\n\nExamplo:\n\n```python\n>>> from brutils import is_valid_legal_process\n>>> is_valid_legal_process('10188748220234018200')\nTrue\n>>> is_valid_legal_process('45532346920234025107')\nTrue\n>>> is_valid_legal_process('00000000000000000000')\nFalse\n>>> is_valid_legal_process('455323423QQWEQWSsasd&*(()')\nFalse\n>>>\n```\n\n### format_legal_process\n\nFormata um ID de processo jur\u00eddico em um formato padr\u00e3o.\n\nArgumentos:\n\n- legal_process_id (str): Uma string de 20 d\u00edgitos que representa o ID do\n                            processo jur\u00eddico.\n\nRetorna:\n\n- str: O ID do processo jur\u00eddico formatado ou None se a entrada for inv\u00e1lida.\n\nExemplo:\n\n```python\n>>> from brutils import format_legal_process\n>>> format_legal_process('23141945820055070079')\n'2314194-58.2005.5.07.0079'\n>>> format_legal_process('00000000000000000000')\n'0000000-00.0000.0.00.0000'\n>>>\n```\n\n### remove_symbols_legal_process\n\nRemove s\u00edmbolos espec\u00edficos de um processo jur\u00eddico fornecido.\n\nEsta fun\u00e7\u00e3o recebe um processo jur\u00eddico como entrada e remove todas as\nocorr\u00eancias dos caracteres '.' e '-' dele.\n\nArgumentos:\n\n- legal_process (str): Um processo jur\u00eddico contendo s\u00edmbolos a serem\n                         removidos.\n\nRetorna:\n\n- str: A string do processo jur\u00eddico com os s\u00edmbolos especificados removidos.\n\nExemplo:\n\n```python\nfrom brutils import remove_symbols_legal_process\n>>> remove_symbols_legal_process(\"6439067-89.2023.4.04.5902\")\n\"64390678920234045902\"\n>>> remove_symbols_legal_process(\"4976023-82.2012.7.00.2263\")\n\"49760238220127002263\"\n>>> remove_symbols_legal_process(\"4976023-82.2012.7.00.2263*!*&#\")\n\"49760238220127002263*!*&#\"\n```\n\n### generate_legal_process\n\nGera um n\u00famero v\u00e1lido aleat\u00f3rio de ID de processo jur\u00eddico.\n\nArgumentos:\n\n- year (int): O ano para o ID do processo jur\u00eddico (o padr\u00e3o \u00e9 o ano atual).\n                N\u00e3o pode ser um ano do passado.\n- orgao (int): O \u00f3rg\u00e3o (1-9) para o ID do processo jur\u00eddico\n                 (o padr\u00e3o \u00e9 aleat\u00f3rio).\n\nRetorna:\n\n- str: Um ID de processo jur\u00eddico gerado aleatoriamente.\n         None caso algum dos argumento seja inv\u00e1lido.\n\nExemplo:\n\n```python\n>>> from brutils import generate_legal_process\n>>> generate_legal_process()\n\"45676401020238170592\"\n>>> generate_legal_process(ano=2025)\n\"32110268020258121130\"\n>>> generate_legal_process(orgao=5)\n\"37573041520235090313\"\n>>> generate_legal_process(ano=2024, orgao=4)\n\"33158248820244017105\"\n```\n\n## Titulo Eleitoral\n\n### is_valid_voter_id\n\nVerifica se um n\u00famero de T\u00edtulo de Eleitor brasileiro \u00e9 v\u00e1lido. N\u00e3o verifica se realmente existe.\n\nRefer\u00eancias:\n\n- <https://pt.wikipedia.org/wiki/T%C3%ADtulo_de_eleitor>\n- <http://clubes.obmep.org.br/blog/a-matematica-nos-documentos-titulo-de-eleitor/>\n\nArgumentos:\n\n- voter_id (str): string representando o n\u00famero do t\u00edtulo de eleitor a ser verificado.\n\nRetorna:\n\n- bool: True se o n\u00famero do t\u00edtulo de eleitor for v\u00e1lido. False, caso contr\u00e1rio.\n\nExemplo:\n\n```python\n>>> from brutils import is_valid_voter_id\n>>> is_valid_voter_id('123456789011')\nFalse\n>>> is_valid_voter_id('427503840213')\nTrue\n```\n\n### format_voter_id\n\nFormata um n\u00famero de T\u00edtulo de Eleitor para exibi\u00e7\u00e3o visual.\n\nEsta fun\u00e7\u00e3o recebe uma string de T\u00edtulo de Eleitor contendo\napenas n\u00fameros como entrada e adiciona os espa\u00e7os de formata\u00e7\u00e3o\npadr\u00e3o para exibi\u00e7\u00e3o.\n\nArgumentos:\n  * voter_id (str): Uma string de T\u00edtulo de Eleitor contendo apenas n\u00fameros.\n\nRetorna:\n  * str: O T\u00edtulo de Eleitor formatado com os espa\u00e7os, se for v\u00e1lido.\n         Retorna None se n\u00e3o for v\u00e1lido.\n\nExemplo:\n\n```python\n>>> from brutils import format_voter_id\n>>> format_voter_id(\"246593980493\")\n'2465 9398 04 93'\n>>> format_voter_id(\"202715292895\")\n'2027 1529 28 95'\n>>> format_voter_id(\"739035552205\")\n>>>\n```\n\n### generate_voter_id\n\nGera uma string de d\u00edgitos de T\u00edtulo de Eleitor v\u00e1lida aleat\u00f3ria a partir de um estado brasileiro informado.\n\nArgs:\n  * federative_union (str): Unidade Federativa para o t\u00edtulo de eleitor que ser\u00e1 gerado. O valor padr\u00e3o \"ZZ\" \u00e9 usado para T\u00edtulos de Eleitor emitidos para estrangeiros.\n\nRetorna:\n  * str: Um T\u00edtulo de Eleitor v\u00e1lido gerado aleatoriamente.\n\nExemplo:\n\n```python\n>>> from brutils import generate_voter_id\n>>> generate_voter_id()\n'183475722801'\n>>> generate_voter_id(federative_union =\"MG\")\n'950125640248'\n```\n\n\n# Novos Utilit\u00e1rios e Reportar Bugs\n\nCaso queira sugerir novas funcionalidades ou reportar bugs, basta criar\numa nova [issue][github-issues] e iremos lhe responder por l\u00e1!\n\n(Para saber mais sobre github issues, confira a [documenta\u00e7\u00e3o oficial do GitHub][github-issues-doc]).\n\n# D\u00favidas? Ideias?\n\nD\u00favidas de como utilizar a biblioteca? Novas ideias para o projeto?\nQuer compartilhar algo com a gente? Fique \u00e0 vontade para criar um t\u00f3pico no nosso\n[Discussions][github-discussions] que iremos interagir por l\u00e1!\n\n(Para saber mais sobre github discussions, confira a\n[documenta\u00e7\u00e3o oficial do GitHub][github-discussions-doc]).\n\n# Contribuindo com o C\u00f3digo do Projeto\n\nSua colabora\u00e7\u00e3o \u00e9 sempre muito bem-vinda! Preparamos o arquivo [CONTRIBUTING.md][contributing] para\nte ajudar nos primeiros passos. L\u00e1 voc\u00ea encontrar\u00e1 toda a informa\u00e7\u00e3o necess\u00e1ria para contribuir com\no projeto. N\u00e3o hesite em nos perguntar utilizando o [GitHub Discussions][github-discussions] caso\nhaja qualquer dificuldade ou d\u00favida. Toda ajuda conta!\n\nVamos construir juntos! \ud83d\ude80\ud83d\ude80\n\n[contributing]: CONTRIBUTING.md\n[github-discussions-doc]: https://docs.github.com/pt/discussions\n[github-discussions]: https://github.com/brazilian-utils/brutils-python/discussions\n[github-issues-doc]: https://docs.github.com/pt/issues/tracking-your-work-with-issues/creating-an-issue\n[github-issues]: https://github.com/brazilian-utils/brutils-python/issues\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Utils library for specific Brazilian businesses",
    "version": "2.2.0",
    "project_urls": {
        "Homepage": "https://github.com/brazilian-utils/brutils",
        "Repository": "https://github.com/brazilian-utils/brutils"
    },
    "split_keywords": [
        "cpf",
        " cnpj",
        " cep",
        " document",
        " validation",
        " brazil",
        " brazilian"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "c86cfe845c392455741ec42fe6b43539e65fb926ae7d5b4db9105722d92db087",
                "md5": "e72b9f49bebf47e1407b434e67f18710",
                "sha256": "b51103e13ba33d1de7a17103494597da4a76f34135a698a0d50c922b6b3b3ff8"
            },
            "downloads": -1,
            "filename": "brutils-2.2.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "e72b9f49bebf47e1407b434e67f18710",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4.0.0,>=3.8.1",
            "size": 30117,
            "upload_time": "2024-09-12T19:35:12",
            "upload_time_iso_8601": "2024-09-12T19:35:12.474332Z",
            "url": "https://files.pythonhosted.org/packages/c8/6c/fe845c392455741ec42fe6b43539e65fb926ae7d5b4db9105722d92db087/brutils-2.2.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "740d814db7c7d58d929011f86d22a2e3c99de9e5b8e74656f164c0aa4238fc66",
                "md5": "fa6d4b7051ba981d8c98399ac43bd953",
                "sha256": "5eb0b8760d6de5891555ed7a6d359c438a8d3fef7fbe33b503c71044d8c80b0b"
            },
            "downloads": -1,
            "filename": "brutils-2.2.0.tar.gz",
            "has_sig": false,
            "md5_digest": "fa6d4b7051ba981d8c98399ac43bd953",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0.0,>=3.8.1",
            "size": 30890,
            "upload_time": "2024-09-12T19:35:13",
            "upload_time_iso_8601": "2024-09-12T19:35:13.541648Z",
            "url": "https://files.pythonhosted.org/packages/74/0d/814db7c7d58d929011f86d22a2e3c99de9e5b8e74656f164c0aa4238fc66/brutils-2.2.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-09-12 19:35:13",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "brazilian-utils",
    "github_project": "brutils",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "brutils"
}
The Brazilian Utils Organization
Elapsed time: 0.64750s