DOCSEARCHbyAlgolia
Submit Docs

brutils

repository·main·Indexed 19 days ago

https://github.com/brazilian-utils/python

A Python utility library for validating, generating, and manipulating data specific to Brazilian business requirements. It provides tools for handling CPF, CNPJ, CEP (including ViaCEP API integration), phone numbers, CNH, license plates (Old and Mercosul), PIS, Legal Process IDs, Voter IDs, RENAVAM, and passports. Additionally, it includes modules for IBGE codes, Brazilian holidays, currency formatting and text conversion, and Legal Nature (Natureza Jurídica) codes.

Tokens
23.8K
Snippets
107
Records
130
Agent score
64%

What's inside brutils

  1. Create a high-quality GitHub Pull Request

    main

    To ensure fast reviews, follow these best practices when submitting a PR:

    • Descriptive Title: Use specific titles (e.g., Add utility convert_uf_to_text to handle Brazilian state codes) instead of generic ones like Fix issue.
    • Detailed Description: Explain what was changed, why it was changed, and which issues were resolved.
    • Link Issues: Use keywords like Closes #474 or Fixes #474 in the description to automatically close the associated issue upon merging.
    • Checklist Compliance: Use the provided PR template. Mark completed items with [x] and incomplete ones with [ ]. Note that [ x ] or [x ] (with extra spaces) will not render correctly.

  2. Update README documentation

    main

    When adding or changing features, you must update the documentation files:

    1. README_EN.md (English): Use the content directly from the function's docstring.
    2. README.md (Portuguese): Translate the function's docstring into Portuguese.

    Both files should include a description, arguments, return values, and a usage example.

  3. Install brutils locally using pip

    main

    If you prefer using pip, follow these steps to install the project in development mode.

    Requirements:

    • Python 3.10 or higher
    • pip
    1. Create and activate a virtual environment:
    python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate
    1. Install development and test dependencies using the requirements file:
    pip install -r requirements-dev.txt
    python -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt

  4. Claim an issue to work on

    main
    To ensure you are working on an unassigned task, visit the brutils issues page and find an issue that interests you. To claim the issue, leave a comment containing the word bora! (Brazilian Portuguese for "let's go!"). A bot will automatically assign the issue to you. It is recommended to work on only one issue at a time to allow others to collaborate.

  5. Format the CHANGELOG.md entries

    main

    The project follows the Keep a Changelog guidelines. When adding entries to CHANGELOG.md, ensure that sections are ordered alphabetically by type. The standard order is:

    1. Added
    2. Changed
    3. Deprecated
    4. Fixed
    5. Removed
    6. Security

    Each entry should include a descriptive message and a link to the relevant issue or pull request using the format: - Description. [#<issue_number>](<issue_link>).

    ## [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>)

  8. Set up a development branch

    main

    After forking and cloning the repository, navigate to the project directory and create a new branch named after the issue number you are working on to keep your changes organized.

    cd brutils-python
git checkout -b <issue_number>

    Example for issue 386:

    git checkout -b 386
    $ git checkout -b 386
Switched to a new branch '386'

  9. Format, commit, and push changes

    main

    Before pushing your changes, follow these steps to ensure code quality and proper version control:

    1. Format code: Run make format to ensure consistent styling.
    2. Stage changes: Use git add --all.
    3. Commit: Use git commit -a -m "<commit_message>".
    4. Push: Use git push --set-upstream origin <branch_name>.
    # Format code
make format

# Stage and commit
git add --all
git commit -a -m "your message"

# Push to remote
git push --set-upstream origin <branch_name>

  10. Release a new version of brutils

    main

    Releasing a new production version involves three main stages:

    1. Create a Release Issue

    • Use the feature template to create an issue named Release v<version>.
    • A branch will be created related to the Issue number.

    2. Create a Release PR

    • Update Version: Increment the version number in pyproject.toml following Semantic Versioning.
    • Update CHANGELOG.md: Add a new title for the version with the current date and include the version links.
    • Submit PR: Create a PR named Release v<version> containing the version bump and changelog updates. Include the modified changelog section in the PR description.

    3. Deploy via GitHub

    Once the Release PR is merged, create a formal GitHub Release:

    • Tag version: v<version> (e.g., v2.0.0).
    • Release title: Same as the tag version (e.g., v2.0.0).
    • Release description: Copy the content from the corresponding version section in CHANGELOG.md.

    Deployment to PyPI is triggered automatically by the GitHub release.

  11. Document code using docstrings

    main

    All modules, classes, functions, and methods must have docstrings written in English. Follow the established pattern for consistency:

    • Classes: Explain the purpose and list Attributes with their types and descriptions.
    • Functions/Methods: Explain the purpose, list Args (name and type), Returns (type and description), and provide an Example using doctest format.
    • Note: You can ignore docstrings for property decorators and magic methods.

    Example pattern:

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

    Attributes:
        x[dict]: Short explanation here
    """

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

        Args:
            w[type]: Short explanation here

        Returns:
            type: Short explanation here

        Example:
            >>> foobar(1)
            output
        """
        ...
    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