### Format CEP Example (English README)

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Example of how to document the `format_cep` function in an English README file. Includes a description, arguments, return value, and code examples.

```md
### 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:

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

```

--------------------------------

### Format CEP Example (Portuguese README)

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Example of how to document the `format_cep` function in a Portuguese README file. Includes a description, arguments, return value, and code examples.

```md
### format_cep

Esta função recebe um CEP como entrada e, se for um CEP válido de 8 dígitos, formata-o no padrão "12345-678".

Argumentos:

- cep (str): O CEP a ser formatado.

Retorna:

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

Exemplo:

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

```

--------------------------------

### Install brutils Package

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Install the Brazilian Utils library using pip.

```bash
pip install brutils
```

--------------------------------

### Install Dependencies with Poetry

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Install all project dependencies using Poetry. This command reads the lock file to ensure reproducible builds.

```shell
$ make install
git config --local core.hooksPath .githooks/
chmod -R +x .githooks
Installing dependencies from lock file
...

```

--------------------------------

### Changelog Formatting Example

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Demonstrates the correct structure and ordering of changelog sections (Added, Changed, Deprecated, Fixed, Security, Removed) and how to add new entries.

```markdown
## [Unreleased]
### Added
- Utility `get_address_from_cep` [#358](https://github.com/brazilian-utils/brutils-python/pull/358)
- My other changelog message here. [#<issue_number>](<issue_link>)

### Changed
- Utility `fmt_voter_id` renamed to `format_voter_id` [#221](https://github.com/brazilian-utils/brutils-python/issues/221)

### Fixed
- My changelog message here. [#<issue_number>](<issue_link>)
```

--------------------------------

### Install Development Dependencies with Pip

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Install development and testing dependencies using pip from the requirements-dev.txt file. This command should be run after activating the virtual environment.

```shell
pip install -r requirements-dev.txt

```

--------------------------------

### Format Brazilian CEP Docstring Example

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Example of a docstring for a function that formats Brazilian CEPs. It includes type hints, a clear explanation, argument and return descriptions, and doctest examples.

```python
def format_cep(cep):  # type: (str) -> str | None
    """
    Formats a Brazilian CEP (Postal Code) into a standard format.

    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:
        >>> format_cep("12345678")
        "12345-678"
        >>> format_cep("12345")
        None
    """

    return f"{cep[:5]}-{cep[5:8]}" if is_valid(cep) else None

```

--------------------------------

### PR Description Example

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

An example of a detailed Pull Request description explaining the changes, the reason for them, and the issues they address.

```markdown
This PR adds the convert_uf_to_text utility to convert Brazilian state codes (e.g., "SP") to full state names (e.g., "São Paulo"). It addresses issue #474 by improving code reusability for address formatting. The function includes input validation and updated tests.
```

--------------------------------

### Setup Development Environment with Pip

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Create and activate a virtual environment using Python's built-in venv module. This is an alternative to Poetry for managing dependencies.

```shell
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate

```

--------------------------------

### Python Docstring Structure

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Follow this pattern for consistent docstrings in modules, classes, and functions. Include explanations for classes, attributes, arguments, return values, and examples.

```python
class Example:
    """
    Explain the purpose of the class

    Attributes:
        x[dict]: Short explanation here
        y[type, optional]: Short explanation here
    """

    def __init__(self, x, y=None):
        self.x = x
        self.y = y

    def foobar(self, w):
        """
        Purpose of the function

        Args:
            name[type]: Short explanation here

        Returns:
            type: Short explanation here

        Example:
            >>> command 1
            output 1
            >>> command 2
            output 2
        """
        ... 
        return value

```

--------------------------------

### Update Library Version in pyproject.toml

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Example of updating the library version number in the `pyproject.toml` file according to Semantic Versioning guidelines.

```toml
# Example content of pyproject.toml showing version update
[tool.poetry]
name = "brutils"
version = "1.2.3" # Increment this version number
description = "Utilities for Brazilian data."
authors = ["Your Name <you@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.8"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

```

--------------------------------

### Get CEP Information from Address

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Fetches CEP options from a given address using the ViaCEP API. Set raise_exceptions to True to get errors for invalid or not found addresses.

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

--------------------------------

### Get CEP Information from Address

Source: https://github.com/brazilian-utils/python/blob/main/README.md

Searches for CEP and address details using the ViaCEP API based on federal unit, city, and street. Returns a list of matching addresses or None. Can optionally raise exceptions.

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

--------------------------------

### Get Municipality by IBGE Code

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Retrieve the municipality name and UF given an IBGE code. Returns a tuple of ('Município', 'UF') or None if the code is invalid.

```python
>>> from brutils import get_municipality_by_code
>>> get_municipality_by_code(3550308)
("São Paulo", "SP")
```

--------------------------------

### Get Address from CEP

Source: https://github.com/brazilian-utils/python/blob/main/README.md

Fetches address information from the ViaCEP API using a Brazilian CEP. Optionally raises exceptions for invalid or not-found CEPs.

```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 Legal Nature Description

Source: https://github.com/brazilian-utils/python/blob/main/README.md

Retrieves the official description for a given Legal Nature code. Accepts 'NNNN' or 'NNN-N' formats, applying the same normalization as `is_valid`.

```python
>>> from brutils import legal_nature
>>> legal_nature.get_description("2062")   
'Sociedade Empresária Limitada'
```

```python
>>> legal_nature.get_description("101-5")  
'Órgão Público do Poder Executivo Federal'
```

```python
>>> legal_nature.get_description("0000")   
None
```

--------------------------------

### Get Legal Nature Description

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Retrieves the official description for a given legal nature code. Applies the same normalization as the validation function. Returns None if the code is invalid or non-existent.

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

--------------------------------

### Get License Plate Format

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Determines the format of a given license plate string. Returns 'LLLNNNN' for the old pattern and 'LLLNLNN' for Mercosul. Returns None for invalid formats.

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

--------------------------------

### Verify Poetry Virtual Environment

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

After activating the virtual environment, run this command to confirm that Poetry has correctly set up the environment and Python interpreter.

```shell
$ poetry env inf
Virtualenv
Python:         3.x.y
Implementation: CPython
...

```

--------------------------------

### Run Project Tests

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Execute all project tests using the make test command. This command runs the test suite and reports the results.

```shell
$ make test
make test
test__is_valid_mercosul (license_plate.test_is_valid.TestIsValidMercosul.test__is_valid_mercosul) ... ok
test__is_valid_old_format (license_plate.test_is_valid.TestIsValidOldFormat.test__is_valid_old_format) ... ok
....

----------------------------------------------------------------------
Ran XX tests in 0.000s

OK

```

--------------------------------

### Generate Random CEP

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Generates a random 8-digit CEP (Postal Code) number as a string. No setup is required beyond importing the function.

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

--------------------------------

### Activate Virtual Environment with Poetry

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Use the provided make command to spawn a shell within a virtual environment managed by Poetry. This ensures dependencies are isolated.

```shell
$ make shell
Spawning shell within ...-py3.x
emulate bash -c '. .../bin/activate'

```

--------------------------------

### Format Code

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Run this command to format your code according to project standards. It checks for and applies necessary formatting changes.

```bash
$ make format
```

```bash
$ make format
31 files left unchanged
All checks passed!
```

--------------------------------

### Generate Random PIS Number

Source: https://github.com/brazilian-utils/python/blob/main/README.md

Generates a random, valid Brazilian PIS number as a string. No specific setup is required beyond importing the function.

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

--------------------------------

### Create and Checkout New Branch

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Navigate to the project directory and create a new branch for your issue. This is a standard Git workflow for managing contributions.

```bash
cd brutils-python

```

```bash
git checkout -b <issue_number>

```

```bash
git checkout -b 386
Switched to a new branch '386'

```

--------------------------------

### Implement Brazilian Currency Formatting Function

Source: https://github.com/brazilian-utils/python/blob/main/MAINTAINING.md

This snippet is a template for implementing a function to format Brazilian currency (BRL). It requires creating an issue, defining the function signature, handling invalid inputs by returning None, and including a placeholder for the logic. Unit tests for edge cases are also mandatory.

```python
def format_brl(value: float) -> str | None:
    """
    Formats a float value into a Brazilian Real (BRL) currency string.

    Args:
        value (float): The float value to format.

    Returns:
        str or None: The formatted BRL string, or None if the input is invalid.
    """
    # implementar a lógica da função aqui
```

--------------------------------

### Handle CEP Not Found Exceptions

Source: https://context7.com/brazilian-utils/python/llms.txt

Demonstrates how to catch CEPNotFound exceptions when looking up address information with raise_exceptions=True.

```python
try:
    get_cep_information_from_address("SP", "Cidade Inexistente", "Rua X", raise_exceptions=True)
except CEPNotFound as e:
    print(e)
```

--------------------------------

### Interactive Python Shell

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Use an interactive Python environment to manually test your code changes. This is useful for quick checks and debugging.

```sh
$ python
Python 3.x.y ...
Type "help", "copyright", "credits" or "license" for more information.
>>> # Test your changes here!

```

--------------------------------

### PR Description Template Checklist

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Illustrates the syntax for marking items as completed ([x]) or incomplete ([ ]) in a Pull Request description template checklist.

```markdown
- [x] Code changes are tested.
- [x] Documentation (READMEs) is updated.
- [ ] Changelog entry is added.
```

--------------------------------

### Format CPF for Display

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Formats a numbers-only CPF string with standard visual aid symbols. Input must be a valid CPF string.

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

--------------------------------

### Get IBGE Code by Municipality Name

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Retrieve the IBGE code for a municipality given its name and UF. Handles case-insensitivity, accents, and 'ç' to 'c' conversion for municipality names, and case-insensitivity for UF codes. Returns None if the municipality is not found or the UF is invalid.

```python
>>> from brutils import get_code_by_municipality_name
>>> get_code_by_municipality_name("São Paulo", "SP")
"3550308"
>>> get_code_by_municipality_name("goiania", "go")
"5208707"
>>> get_code_by_municipality_name("Conceição do Coité", "BA")
"2908408"
>>> get_code_by_municipality_name("conceicao do Coite", "Ba")
"2908408"
>>> get_code_by_municipality_name("Municipio Inexistente", "")
None
>>> get_code_by_municipality_name("Municipio Inexistente", "RS")
None
```

--------------------------------

### List All Legal Nature Codes and Descriptions

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Returns a dictionary mapping all valid legal nature codes to their official descriptions. Useful for retrieving the complete set of available legal natures.

```python
>>> from brutils import legal_nature
>>> data = legal_nature.list_all()
>>> len(data) > 0
True
>>> data["2062"]
'Sociedade Empresária Limitada'
```

--------------------------------

### Validate and Get Brazilian Legal Nature Descriptions

Source: https://context7.com/brazilian-utils/python/llms.txt

Validates Brazilian legal entity classification codes from the Receita Federal do Brasil (RFB) table and retrieves their full descriptions. Accepts both raw and hyphenated code formats. Returns None if the code is not found.

```python
from brutils import is_valid_legal_nature, get_natureza_legal_nature, list_all_legal_nature

# Validate a code
is_valid_legal_nature("2062")    # True  (Sociedade Empresária Limitada)
is_valid_legal_nature("206-2")   # True  (hyphenated format also accepted)
is_valid_legal_nature("9999")    # False (not in RFB table)
is_valid_legal_nature("1015")    # True  (Órgão Público do Poder Executivo Federal)

# Get full description
get_natureza_legal_nature("2062")    # "Sociedade Empresária Limitada"
get_natureza_legal_nature("101-5")   # "Órgão Público do Poder Executivo Federal"
get_natureza_legal_nature("0000")    # None (not found)
```

--------------------------------

### format_legal_process

Source: https://github.com/brazilian-utils/python/blob/main/README.md

Formats a Brazilian legal process ID string into a standard format.

```APIDOC
### format_legal_process

### Description
Formats a legal process ID into a standard format.

### Arguments
- legal_process_id (str): A 20-digit string representing the legal process ID.

### Returns
- str: The formatted legal process ID or None if the input is invalid.

### Example
```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'
>>>
```
```

--------------------------------

### List All Legal Natures

Source: https://github.com/brazilian-utils/python/blob/main/README.md

Returns a dictionary mapping all legal nature codes to their official descriptions. Useful for browsing available options.

```python
>>> from brutils import legal_nature 
>>> data = legal_nature.list_all()
>>> len(data) > 0               
True
```

```python
>>> data["2062"]                 
'Sociedade Empresária Limitada'
```

--------------------------------

### Validate, Format, and Generate Legal Process IDs

Source: https://context7.com/brazilian-utils/python/llms.txt

Handles 20-digit Brazilian legal process IDs. `is_valid_legal_process` checks checksums and embedded IDs. `format_legal_process` converts to human-readable format. `remove_symbols_legal_process` cleans input. `generate_legal_process` creates valid IDs.

```python
from brutils import (
    is_valid_legal_process, format_legal_process,
    remove_symbols_legal_process, generate_legal_process
)

# Validate (checks checksum + tribunal/forum IDs)
is_valid_legal_process("10188748220234018200")   # True
is_valid_legal_process("45532346920234025107")   # True
is_valid_legal_process("00000000000000000000")   # False

# Format (raw 20-digit → human-readable)
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 (wrong length)

# Remove symbols
remove_symbols_legal_process("6439067-89.2023.4.04.5902")   # "64390678920234045902"

# Generate a syntactically and semantically valid ID
proc = generate_legal_process()            # uses current year, random orgao
proc2 = generate_legal_process(2025, 5)   # year=2025, Justiça do Trabalho (orgao 5)
generate_legal_process(2020, 1)            # None (past year is invalid)
generate_legal_process(2025, 10)           # None (orgao must be 1–9)
```

--------------------------------

### Format Currency to Brazilian Standard

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Format a number into a string following Brazilian monetary standards, including 'R$' prefix, comma as decimal separator, and period as thousands separator. Returns None for non-numeric input.

```python
>>> from brutils.currency import format_currency
>>> format_currency(1259.03)
'R$ 1.259,03'
>>> format_currency(0)
'R$ 0,00'
>>> format_currency("not a number")
None
```

--------------------------------

### format_cpf

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Formats a CPF string with standard visual aid symbols for display.

```APIDOC
## format_cpf

### Description
Formats 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
```python
>>> from brutils import format_cpf
>>> format_cpf('82178537464')
'821.785.374-64'
>>> format_cpf("55550207753")
'555.502.077-53'
```
```

--------------------------------

### generate_cpf

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Generates a random valid CPF string.

```APIDOC
## generate_cpf

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

### Returns
- str: A random valid CPF string.

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

--------------------------------

### Add Changes to Staging Area

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Use this command to add all modified and new files to the Git staging area before committing.

```bash
$ git add --all
```

--------------------------------

### list_all_legal_nature

Source: https://github.com/brazilian-utils/python/blob/main/README.md

Returns a copy of the complete dictionary mapping all Legal Nature codes to their descriptions.

```APIDOC
## list_all_legal_nature

### Description
Returns a copy of the complete dictionary mapping all Legal Nature codes to their descriptions.

### Returns
- **dict[str, str]**: A mapping of all codes to their descriptions.

### Example
```python
>>> from brutils import legal_nature 
>>> data = legal_nature.list_all()
>>> len(data) > 0               
True
>>> data["2062"]                 
'Sociedade Empresária Limitada'
```
```

--------------------------------

### Format Currency (R$)

Source: https://context7.com/brazilian-utils/python/llms.txt

Formats a numeric value into the Brazilian Real (BRL) currency format with the 'R$' prefix, using a dot for thousands separators and a comma for decimal separators. Accepts string inputs that can be converted to numbers. Returns `None` for non-numeric inputs.

```APIDOC
## Currency — format_currency — Format as R$

format_currency(1259.03)       # "R$ 1.259,03"
format_currency(0)             # "R$ 0,00"
format_currency(-9876.54)      # "R$ -9.876,54"
format_currency(1000000)       # "R$ 1.000.000,00"
format_currency("1234.56")     # "R$ 1.234,56"  (string input accepted)
format_currency("not a number")  # None
format_currency(None)           # None
```

--------------------------------

### List All Legal Nature Codes

Source: https://context7.com/brazilian-utils/python/llms.txt

Retrieves a list of all registered legal nature codes and allows access to specific codes. Use this to understand the available legal nature classifications.

```python
all_codes = list_all_legal_nature()
# {"1015": "Órgão Público do Poder Executivo Federal", "2062": "Sociedade Empresária Limitada", ...}
print(len(all_codes))          # number of registered codes
print(all_codes["2143"])       # "Cooperativa"
print(all_codes["3123"])       # "Partido Político"
```

--------------------------------

### format_legal_process

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Formats a legal process ID into a standard 20-digit format.

```APIDOC
## format_legal_process

### Description
Formats 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
```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'
>>> format_legal_process("123")
None
```
```

--------------------------------

### get_municipality_by_code

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Returns the municipality name and UF for a given IBGE code.

```APIDOC
## get_municipality_by_code

### Description
Returns the municipality name and UF for a given IBGE code.

### Parameters
#### Path Parameters
- **code** (str) - Required - The IBGE code of the municipality.

### Returns
- **tuple**: Returns a tuple formatted as ("Município", "UF").
- **None**: Returns None if the code is not valid.

### Example
```python
>>> from brutils import get_municipality_by_code
>>> get_municipality_by_code(3550308)
("São Paulo", "SP")
```
```

--------------------------------

### Fetch IBGE Municipality Codes and Names

Source: https://context7.com/brazilian-utils/python/llms.txt

Fetches IBGE municipality codes and names using the official IBGE REST API. Lookups are accent-tolerant and case-insensitive. Returns None on network failure or invalid input.

```python
from brutils import get_municipality_by_code, get_code_by_municipality_name

# IBGE 7-digit code → (municipality_name, UF)
get_municipality_by_code("3550308")   # ("São Paulo", "SP")
get_municipality_by_code("3304557")   # ("Rio de Janeiro", "RJ")
get_municipality_by_code("1234567")   # None (non-existent code)

# Municipality name + UF → IBGE 7-digit code
# Case-insensitive, accent-tolerant matching
get_code_by_municipality_name("São Paulo", "SP")            # "3550308"
get_code_by_municipality_name("goiania", "go")              # "5208707"
get_code_by_municipality_name("Conceição do Coité", "BA")   # "2908408"
get_code_by_municipality_name("conceicao do coite", "ba")   # "2908408"
get_code_by_municipality_name("Municipio Inexistente", "RS")  # None
```

--------------------------------

### Remove Symbols from Legal Process String

Source: https://github.com/brazilian-utils/python/blob/main/README.md

Removes '.' and '-' characters from a legal process string. Other characters remain unaffected.

```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*!*&#"
```

--------------------------------

### Linking Issue in PR Description

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Shows how to link a Pull Request to a specific issue using keywords like 'Closes' or 'Fixes' for automatic issue closure upon merging.

```markdown
Closes #474
```

--------------------------------

### convert_name_to_uf

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Converts a Brazilian state name to its UF code. Comparison is case-insensitive and ignores accents.

```APIDOC
## convert_name_to_uf

### Description
Converts a Brazilian state name to its UF code. This function takes the full name of a Brazilian state and returns its corresponding two-letter UF code. The comparison is case-insensitive and ignores accents.

### Parameters
#### Path Parameters
- **state_name** (str) - Required - The full name of the state (e.g., 'São Paulo', 'sao paulo').

### Returns
- **str | None**: The UF code if found, or None if the state name is invalid.

### Example
```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('Invalid State')
>>>
```
```

--------------------------------

### generate_legal_process

Source: https://github.com/brazilian-utils/python/blob/main/README.md

Generates a random, valid Brazilian legal process ID.

```APIDOC
### generate_legal_process

### Description
Generates a random, valid Brazilian legal process ID.

### Arguments
- year (int): The year for the legal process ID (defaults to the current year). Cannot be a past year.
- orgao (int): The organ (1-9) for the legal process ID (defaults to random).

### Returns
- str: A randomly generated legal process ID. None if any argument is invalid.

### Example
```python
>>> 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"
```
```

--------------------------------

### CPF Validation, Formatting, and Generation

Source: https://context7.com/brazilian-utils/python/llms.txt

Use these functions to validate CPF numbers, format them for display, remove symbols, or generate random valid CPFs. Validation checks checksums but not real-world existence. Input must be digits only for validation and formatting.

```python
from brutils import is_valid_cpf, format_cpf, remove_symbols_cpf, generate_cpf

# Validate
is_valid_cpf("82178537464")   # True
is_valid_cpf("00011122233")   # False  (all-same-digit sequences are rejected)
is_valid_cpf("821.785.374-64")  # False (formatted strings fail; strip first)

# Strip symbols first, then validate
raw = remove_symbols_cpf("821.785.374-64")  # "82178537464"
is_valid_cpf(raw)  # True

# Format for display
format_cpf("82178537464")   # "821.785.374-64"
format_cpf("00011122233")   # None  (invalid input → None)

# Generate a random valid CPF
cpf = generate_cpf()  # e.g. "17433964657"
is_valid_cpf(cpf)     # True (always)
```

--------------------------------

### Push Changes to Remote

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Push your local commits to the remote repository. The '--set-upstream' flag establishes the upstream tracking branch.

```bash
$ git push --set-upstream origin 386
Running pre-push hook checks
All checks passed!
Enumerating objects: 7, done.
Counting objects: 100% (7/7), done.
Delta compression using up to 10 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 2.36 KiB | 2.36 MiB/s, done.
Total 4 (delta 3), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (3/3), completed with 3 local objects.
remote: 
remote: Create a pull request for '386' on GitHub by visiting:
remote:      https://github.com/brazilian-utils/brutils-python/pull/new/386
remote: 
To github.com:brazilian-utils/brutils-python.git
 * [new branch]      386 -> 386
```

--------------------------------

### Date to Text Conversion

Source: https://context7.com/brazilian-utils/python/llms.txt

Converts a date string in `dd/mm/yyyy` format to its written-out Brazilian Portuguese representation. Returns `None` for invalid date formats or non-existent dates.

```APIDOC
## Date Utilities — Date to Text Conversion

convert_date_to_text("25/12/2000")   # "Vinte e cinco de dezembro de dois mil"
convert_date_to_text("01/08/2024")   # "Primeiro de agosto de dois mil e vinte e quatro"
convert_date_to_text("29/02/2024")   # "Vinte e nove de fevereiro de dois mil e vinte e quatro"
convert_date_to_text("31/02/2000")   # None (invalid date)
convert_date_to_text("2024-01-01")   # None (wrong format)
```

--------------------------------

### PIS (Program Integration Bank)

Source: https://context7.com/brazilian-utils/python/llms.txt

Utilities for formatting, removing symbols from, and validating PIS numbers.

```APIDOC
## PIS Utilities

### Description
Functions to format PIS numbers into the standard `NNN.NNNNN.NN-N` format, remove symbols, and validate their checksum.

### Functions

- **format_pis(pis_number: str) -> Optional[str]**
  Formats a raw PIS number string into `NNN.NNNNN.NN-N`. Returns `None` if the PIS is invalid (e.g., bad checksum).

- **remove_symbols_pis(pis_number: str) -> str**
  Removes formatting symbols (dots and hyphen) from a PIS number string.

- **generate_pis() -> str**
  Generates a syntactically valid PIS number.

- **is_valid_pis(pis_number: str) -> bool**
  Validates the checksum of a PIS number.

### Examples
```python
from brutils import format_pis, remove_symbols_pis, generate_pis, is_valid_pis

# Format
format_pis("17033259504")    # "170.33259.50-4"
format_pis("12013128292")    # "120.13128.29-2"
format_pis("00000000000")    # None (invalid checksum)

# Remove symbols
remove_symbols_pis("170.33259.50-4")    # "17033259504"
remove_symbols_pis("123.456.789-09")    # "12345678909"

# Generate and Validate
pis = generate_pis()
is_valid_pis(pis)     # True
```
```

--------------------------------

### Convert Real to Text

Source: https://context7.com/brazilian-utils/python/llms.txt

Converts a monetary value in Brazilian Reais to its full written-out form in Brazilian Portuguese. Values are rounded down to 2 decimal places, with a maximum limit of 1 quadrillion. Returns `None` for invalid inputs.

```APIDOC
## Currency — convert_real_to_text — Amount to Written Words

convert_real_to_text(1523.45)   # "Mil, quinhentos e vinte e três reais e quarenta e cinco centavos"
convert_real_to_text(1.00)      # "Um real"
convert_real_to_text(0.50)      # "Cinquenta centavos"
convert_real_to_text(0.01)      # "Um centavo"
convert_real_to_text(0.00)      # "Zero reais"
convert_real_to_text(-50.25)    # "Menos cinquenta reais e vinte e cinco centavos"
convert_real_to_text("invalid")  # None
```

--------------------------------

### is_valid_legal_process

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Checks if a legal process ID string conforms to the expected format.

```APIDOC
## is_valid_legal_process

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

### Parameters
#### Query Parameters
- **legal_process_id** (str) - Required - A digit-only string representing the legal
                            process ID.

### Returns
- bool: True if the legal process ID is valid, False otherwise.

### Example
```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
>>>
```
```

--------------------------------

### Convert Real to Text in Portuguese

Source: https://github.com/brazilian-utils/python/blob/main/README.md

Converts a monetary value in Brazilian Reais to its text representation. Handles integers (reais) and decimals (centavos), including zero and negative values. Note potential precision loss for values exceeding trillions.

```python
>>> from brutils.currency import convert_real_to_text
>>> convert_real_to_text(1523.45)
'Mil, quinhentos e vinte e três reais e quarenta e cinco centavos'
```

```python
>>> convert_real_to_text(0.01)
'Um centavo'
```

```python
>>> convert_real_to_text(0.00)
'Zero reais'
```

```python
>>> convert_real_to_text(-50.25)
'Menos cinquenta reais e vinte e cinco centavos'
```

```python
>>> convert_real_to_text("invalid")
None
```

--------------------------------

### Generate Random CPF

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Generates a random, valid CPF digit string. Each call produces a new unique CPF.

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

--------------------------------

### Commit Changes

Source: https://github.com/brazilian-utils/python/blob/main/CONTRIBUTING_EN.md

Commit your staged changes with a descriptive message. The '-a' flag stages all tracked, modified files, and '-m' provides the commit message.

```bash
$ git commit -a -m "<commit_message>"
```

--------------------------------

### is_valid_legal_process

Source: https://github.com/brazilian-utils/python/blob/main/README.md

Validates the format of a Brazilian legal process ID string. It does not verify if the ID corresponds to a real legal process.

```APIDOC
## is_valid_legal_process

### Description
Verifies if a legal process ID string is valid based on its format. It does not check for the existence of the legal process.

### Arguments
- legal_process_id (str): A string containing only digits representing the legal process ID.

### Returns
- bool: True if the legal process ID format is valid, False otherwise.

### Example
```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
>>>
```
```

--------------------------------

### get_legal_nature_description

Source: https://github.com/brazilian-utils/python/blob/main/README.md

Retrieves the official description for a given Legal Nature code. Accepts 'NNNN' or 'NNN-N' formats.

```APIDOC
## get_legal_nature_description

### Description
Retrieves the official description for a given Legal Nature code. Accepts 'NNNN' or 'NNN-N' formats. Applies the same normalization as `is_valid`.

### Arguments
- **code** (str): A 4-digit code.

### Returns
- **str | None**: The corresponding description or None if the code is invalid or does not exist.

### Example
```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
```
```

--------------------------------

### Convert Monetary Value to Brazilian Portuguese Words

Source: https://context7.com/brazilian-utils/python/llms.txt

Converts a monetary value in Brazilian Reais to its full written-out form. Values are rounded down to 2 decimal places, with a maximum limit of 1 quadrillion. Returns None for invalid inputs.

```python
from brutils import convert_real_to_text

convert_real_to_text(1523.45)   # "Mil, quinhentos e vinte e três reais e quarenta e cinco centavos"
convert_real_to_text(1.00)      # "Um real"
convert_real_to_text(0.50)      # "Cinquenta centavos"
convert_real_to_text(0.01)      # "Um centavo"
convert_real_to_text(0.00)      # "Zero reais"
convert_real_to_text(-50.25)    # "Menos cinquenta reais e vinte e cinco centavos"
convert_real_to_text("invalid")  # None
```

--------------------------------

### get_code_by_municipality_name

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Returns the IBGE code for a given municipality name and UF code. Handles case, accents, and ç/c differences.

```APIDOC
## get_code_by_municipality_name

### Description
Returns the IBGE code for a given municipality name and uf code. This function takes a string representing a municipality's name and uf's code and returns the corresponding IBGE code (string). The function will handle names by ignoring differences in case, accents, and treating the character ç as c and ignoring case differences for the uf code.

### Parameters
#### Path Parameters
- **municipality_name** (str) - Required - The name of the municipality.
- **uf** (str) - Required - The uf code of the state.

### Returns
- **str**: The IBGE code of the municipality. Returns None if the name is not valid or does not exist.

### Example
```python
>>> from brutils import get_code_by_municipality_name
>>> get_code_by_municipality_name("São Paulo", "SP")
"3550308"
>>> get_code_by_municipality_name("goiania", "go")
"5208707"
>>> get_code_by_municipality_name("Conceição do Coité", "BA")
"2908408"
>>> get_code_by_municipality_name("conceicao do Coite", "Ba")
"2908408"
>>> get_code_by_municipality_name("Municipio Inexistente", "")
None
>>> get_code_by_municipality_name("Municipio Inexistente", "RS")
None
```
```

--------------------------------

### Detect Brazilian License Plate Format

Source: https://context7.com/brazilian-utils/python/llms.txt

Determines the format of a Brazilian license plate string ('LLLNNNN' or 'LLLNLNN'). Returns None for invalid formats.

```python
get_format_license_plate("ABC1234")   # "LLLNNNN"
get_format_license_plate("ABC1D23")   # "LLLNLNN"
get_format_license_plate("ABCD123")   # None
```

--------------------------------

### Format Numeric Value as Brazilian Real (BRL)

Source: https://context7.com/brazilian-utils/python/llms.txt

Formats a numeric value as Brazilian Real (BRL) with the R$ prefix, dot thousands separator, and comma decimal separator. Accepts string inputs that can be converted to numbers. Returns None for non-numeric inputs or None.

```python
from brutils import format_currency

format_currency(1259.03)       # "R$ 1.259,03"
format_currency(0)             # "R$ 0,00"
format_currency(-9876.54)      # "R$ -9.876,54"
format_currency(1000000)       # "R$ 1.000.000,00"
format_currency("1234.56")     # "R$ 1.234,56"  (string input accepted)
format_currency("not a number")  # None
format_currency(None)           # None
```

--------------------------------

### Convert License Plate to Mercosul Format

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Converts an old pattern license plate (LLLNNNN) to the Mercosul format (LLLNLNN). Returns None if the input is invalid.

```python
>>> from brutils import convert_license_plate_to_mercosul
>>> convert_license_plate_to_mercosul("ABC1234")
"ABC1C34"
>>> convert_license_plate_to_mercosul("abc1234")
"ABC1C34"
>>> convert_license_plate_to_mercosul("ABC1D23")
None
```

--------------------------------

### Generate Legal Process ID

Source: https://github.com/brazilian-utils/python/blob/main/README_EN.md

Generates a random legal process ID. Optionally specify the year and organization code. Defaults to current year and random organization.

```python
>>> 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"
```