Skip to content

Latest commit

 

History

History
1144 lines (810 loc) · 25.9 KB

README_EN.md

File metadata and controls

1144 lines (810 loc) · 25.9 KB
Raw

🇧🇷 Brazilian Utils

Utils library for Brazilian-specific businesses.

codecov Downloads per Month Package version

Procurando pela versão em português?

Getting Started

Brazilian Utils is a library focused on solving problems that we face daily in the development of applications for the Brazilian business.

Installation

pip install brutils

Usage

To use one of our utilities you just need to import the required function as in the example below:

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

Utilities

CPF

is_valid_cpf

Returns whether or not the verifying checksum digits of the given CPF (Brazilian Individual Taxpayer Number) match its base number. This function does not verify the existence of the CPF; it only validates the format of the string.

Args:

  • cpf (str): The CPF to be validated, a 11-digit string

Returns:

  • bool: True if the checksum digits match the base number, False otherwise.

Example:

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

format_cpf

Format a CPF (Brazilian Individual Taxpayer Number) for display with visual aid symbols. This function takes a numbers-only CPF string as input and adds standard formatting visual aid symbols for display.

Args:

  • cpf (str): A numbers-only CPF string.

Returns:

  • str: A formatted CPF string with standard visual aid symbols or None if the input is invalid.

Example:

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

remove_symbols_cpf

Removes specific symbols from a CPF (Brazilian Individual Taxpayer Number) string. This function takes a CPF string as input and removes all occurrences of the '.', '-' characters from it.

Args:

  • cpf (str): The CPF string containing symbols to be removed.

Returns:

  • str: A new string with the specified symbols removed.

Example:

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

generate_cpf

Generate a random valid CPF (Brazilian Individual Taxpayer Number) digit string.

Returns:

  • str: A random valid CPF string.

Example:

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

CNPJ

is_valid_cnpj

Returns whether or not the verifying checksum digits of the given CNPJ (Brazilian Company Registration Number) match its base number. Input should be a digit string of proper length. This function does not verify the existence of the CNPJ; it only validates the format of the string.

Args:

  • cnpj (str): The CNPJ to be validated.

Returns:

  • bool: True if the checksum digits match the base number, False otherwise.

Example:

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

format_cnpj

Formats a CNPJ (Brazilian Company Registration Number) string for visual display. This function takes a CNPJ string as input, validates its format, and formats it with standard visual aid symbols for display purposes.

Args:

  • cnpj (str): The CNPJ string to be formatted for display.

Returns:

  • str: The formatted CNPJ with visual aid symbols if it's valid, None if it's not valid.

Example:

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

remove_symbols_cnpj

Removes specific symbols from a CNPJ (Brazilian Company Registration Number) string. This function takes a CNPJ string as input and removes all occurrences of the '.', '/' and '-' characters from it.

Args:

  • cnpj (str): The CNPJ string containing symbols to be removed.

Returns:

  • str: A new string with the specified symbols removed.

Example:

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

generate_cnpj

Generates a random valid CNPJ (Brazilian Company Registration Number) digit string. An optional branch number parameter can be given; it defaults to 1.

Args:

  • branch (int): An optional branch number to be included in the CNPJ.

Returns:

  • str: A randomly generated valid CNPJ string.

Example:

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

CEP

is_valid_cep

Checks if a Brazilian CEP (Postal Code) is valid. To be considered valid, the input must be a string containing exactly 8 digits. This function does not verify if the CEP is a real postal code; it only validates the format of the string.

Args:

  • cep (str): The string containing the CEP to be checked.

Returns:

  • bool: True if the CEP is valid (8 digits), False otherwise.

Example:

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

format_cep

This function takes a CEP (Postal Code) as input and, if it is a valid 8-digit CEP, formats it into the standard "12345-678" format.

Args:

  • cep (str): The input CEP (Postal Code) to be formatted.

Returns:

  • str: The formatted CEP in the "12345-678" format if it's valid, None if it's not valid.

Example:

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

remove_symbols_cep

This function takes a CEP (Postal Code) as input and removes all occurrences of the '.' and '-' characters from it.

Args:

  • cep (str): The input CEP (Postal Code) containing symbols to be removed.

Returns:

  • str: A new string with the specified symbols removed.

Example:

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

Generates a random 8-digit CEP (Postal Code) number as a string.

Returns:

  • str: A randomly generated 8-digit number.

Example:

>>> from brutils import generate_cep
>>> generate_cep()
'77520503'

get_address_from_cep

Fetches address information from a given CEP (Postal Code) using the ViaCEP API.

Args:

  • cep (str): The CEP (Postal Code) to be used in the search.
  • raise_exceptions (bool, optional): Whether to raise exceptions when the CEP is invalid or not found. Defaults to False.

Returns:

  • Address | None: An Address object (TypedDict) containing the address information if the CEP is found, None otherwise.

Example:

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

Fetches CEP (Postal Code) options from a given address using the ViaCEP API.

Args:

  • federal_unit (str): The two-letter abbreviation of the Brazilian state.
  • city (str): The name of the city.
  • street (str): The name (or substring) of the street.
  • raise_exceptions (bool, optional): Whether to raise exceptions when the address is invalid or not found. Defaults to False.

Returns:

  • list[Address] | None: A list of Address objects (TypedDict) containing the address information if the address is found, None otherwise.

Example:

>>> 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"
    }
]

Phone

is_valid_phone

Return whether a Brazilian phone number is valid. It does not verify if the number actually exists.

is_valid_phone(phone_number, type)

Args:

  • phone_number:

    • the phone number to be validated
    • digits only, no symbols
    • without the country code
    • should include the area code (DDD) with two digits
    • example: '+55 48 9999 9999' should be used as '4899999999'
    • mandatory

  • type:

    • 'mobile' to validate only mobile numbers
    • 'landline' to validate only landline phone numbers
    • if not specified, it validates for either.
    • optional

Returns:

  • bool: True if the phone number is valid. False otherwise.

Example:

>>> from brutils import is_valid_phone
>>> is_valid_phone('11994029275')
True
>>> is_valid_mobile_phone('11994029275', 'mobile')
True
>>> is_valid_landline_phone('1938814933', 'landline')
True

format_phone

Format a phone number for visual display. This function takes a string representing a phone number containing only numbers as input and adds standard formatting symbols for display.

Args:

  • phone (str): A string representing a phone number.

Returns:

  • str: The formatted phone number for display or None if it is not valid.

Example:

>>> 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 symbols from the phone number. This function takes a phone number as input and removes all symbols, such as parentheses '()', dashes '-', and spaces ' '.

Args:

  • phone (str): The input phone number containing the symbols to be removed.

Returns:

  • str: A new string with the specified symbols removed.

Example:

>>> 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 the international code (+55) from a string containing a Brazilian phone number, preserving other special characters.

Args:

  • phone (str): The input phone number that may contain the international code.

Returns:

  • str: A new string without the international code, preserving other special characters.

Example:

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

Generates a valid random phone number.

Args:

  • type (str): It can be "landline" or "mobile". If not specified, the function generates a random number of any type.

Returns:

  • str: A randomly generated valid phone number.

Example:

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

Email

is_valid_email

Check if a string corresponds to a valid email address.

Args:

  • email (str): The input string to be checked.

Returns:

  • bool: True if email is a valid email address, False otherwise.

Example:

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

License Plate

is_valid_license_plate

Check if a license plate is valid. This function does not verify if the license plate is a real license plate; it only validates the format of the string.

Args:

  • license_plate (str): A license plate string.
  • type (str): "old_format" or "mercosul". If not specified, checks for one or another.

Returns:

  • bool: True if the license plate is valid, False otherwise.

Example:

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

Formats a license plate into the correct pattern. This function receives a license plate in any pattern (LLLNNNN or LLLNLNN) and returns a formatted version.

Args:

  • license_plate (str): A license plate string.

Returns:

  • str: The formatted license plate string or 'None' if the input is invalid.

Example:

>>> from brutils import format_license_plate
>>> format_license_plate("ABC1234")
"ABC-1234"
# old format (contains a dash)
>>> format_license_plate("abc1234")
"ABC-1234"
# old format (contains a dash)
>>> format_license_plate("ABC1D23")
"ABC1D23"
# mercosul format
>>> format_license_plate("abc1d23")
"ABC1D23"
# mercosul format
>>> format_license_plate("ABCD123")
None

remove_symbols_license_plate

Removes the dash (-) symbol from a license plate string.

Args:

  • license_plate_number (str): A license plate number containing symbols to be removed.

Returns:

  • str: The license plate number with the specified symbols removed.

Example:

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

Generate a valid license plate in the given format. In case no format is provided, it will return a license plate in the Mercosul format.

Args:

  • format (str): The desired format for the license plate. 'LLLNNNN' for the old pattern or 'LLLNLNN' for the Mercosul one. Default is 'LLLNLNN'

Returns:

  • str: A randomly generated license plate number or 'None' if the format is invalid.

Example:

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

Converts an old pattern license plate (LLLNNNN) to a Mercosul format (LLLNLNN).

Args:

  • license_plate (str): A string of proper length representing the old pattern license plate.

Returns:

  • str: The converted Mercosul license plate (LLLNLNN) or 'None' if the input is invalid.

Example:

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

Return the format of a license plate. 'LLLNNNN' for the old pattern and 'LLLNLNN' for the Mercosul one.

Args:

  • license_plate (str): A license plate string without symbols.

Returns:

  • str: The format of the license plate (LLLNNNN, LLLNLNN) or 'None' if the format is invalid.

Example:

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

Verifies if the PIS/PASEP number is valid. Only numbers, formatted as a string. It does not check if the PIS/PASEP actually exists.

References:

Args:

  • pis (str): PIS number as a string with the proper length.

Returns:

  • bool: True if the PIS is valid, False otherwise.

Example:

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

format_pis

Formats a valid PIS (Programa de Integração Social) string with symbols and adds standard formatting symbols for display.

Args:

  • pis (str): A valid string of PIS containing only numbers.

Returns:

  • str: A formatted PIS string with standard visual aid symbols or None if the input is invalid.

Example:

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

remove_symbols_pis

This function takes a string of PIS (Programa de Integração Social) with formatting symbols and returns a clean version without certain symbols. It intentionally removes only the symbols "-" and ".", leaving other symbols untouched.

Args:

  • pis (str): A string of PIS that may contain formatting symbols.

Returns:

  • str: A clean string of PIS without formatting symbols.

Example:

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

Generates a string of digits containing a random valid Brazilian PIS number.

Returns:

  • str: A randomly generated valid PIS number as a string.

Example:

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

Legal Process

is_valid_legal_process

Check if a legal process ID is valid.

This function does not verify if the legal process ID is a real legal process ID; it only validates the format of the string.

Args:

  • legal_process_id (str): A digit-only string representing the legal process ID.

Returns:

  • bool: True if the legal process ID is valid, False otherwise.

Example:

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

Format a legal process ID into a standard format.

Args:

  • legal_process_id (str): A 20-digits string representing the legal process ID.

Returns:

  • str: The formatted legal process ID or None if the input is invalid.

Example:

>>> 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'
>>> format_legal_process("123")
None

remove_symbols_legal_process

Removes specific symbols from a given legal process.

This function takes a legal process as input and removes all occurrences of the '.' and '-' characters from it.

Args:

  • legal_process (str): A legal process containing symbols to be removed.

Returns:

  • str: The legal process string with the specified symbols removed.

Example:

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

Generate a random legal process ID number.

Args:

  • year (int): The year for the legal process ID (default is the current year). The year should not be in the past
  • orgao (int): The organization code (1-9) for the legal process ID (default is random).

Returns:

  • str: A randomly generated legal process ID. None if one of the arguments is invalid.

Example:

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

Voter ID

is_valid_voter_id

Check if a Brazilian voter id number is valid. It does not verify if the voter id actually exists.

References:

Args:

  • voter_id(str): string representing the voter id to be verified.

Returns:

  • bool: True if the voter id is valid. False otherwise.

Example:

>>> from brutils import is_valid_voter_id
>>> is_valid_voter_id('123456789011')
False
>>> is_valid_voter_id('427503840213')
True

format_voter_id

Formats a voter ID number for visual display.

This function takes a voter ID string containing only numbers as input and adds the standard formatting spaces for display.

Arguments:

  • voter_id (str): A voter ID string containing only numbers.

Returns:

  • str: The formatted voter ID with spaces if valid. Returns None if not valid.

Example:

>>> from brutils import format_voter_id
>>> format_voter_id("246593980493")
'2465 9398 04 93'
>>> format_voter_id("202715292895")
'2027 1529 28 95'
>>> format_voter_id("739035552205")
>>>

generate_voter_id

Generate a valid random Voter ID string of digits from an informed Brazilian federation union.

Args:

  • federative_union(str): federative union for the voter id that will be generated. The default value "ZZ" is used for voter IDs issued to foreigners.

Returns:

  • str: A randomly generated valid voter ID.

Example:

>>> from brutils import generate_voter_id
>>> generate_voter_id()
'183475722801'
>>> generate_voter_id(federative_union ="MG")
'950125640248'

IBGE

convert_code_to_uf

Converts a given IBGE code (2-digit string) to its corresponding UF (state abbreviation).

Args:

  • code (str): The 2-digit IBGE code to be converted.

Retorna:

  • str or None: The UF code corresponding to the IBGE code, or None if the IBGE code is invalid.

Exemplo:

>>> from brutils.ibge.uf import convert_code_to_uf
>>> convert_code_to_uf("12")
'AC'
>>> convert_code_to_uf("33")
'RJ'
>>> convert_code_to_uf("99")
>>>

Feature Request and Bug Report

If you want to suggest new features or report bugs, simply create a new issue, and we will respond to you there!

(To learn more about GitHub issues, check out the official GitHub documentation).

Questions? Ideas?

Questions on how to use the library? New ideas for the project? Want to share something with us? Feel free to start a thread in our Discussions, and we'll interact with you there!

(To learn more about GitHub discussions, refer to the official GitHub documentation).

Code Contribution

Your collaboration is always very welcome! We've prepared the CONTRIBUTING.md file to assist you in getting started. There, you'll find all the information you need to contribute to the project. Please, don't hesitate to ask us using GitHub Discussions if you encounter any difficulties or have any questions. Every bit of help counts!

Let's build it together 🚀🚀