{"id":30620517,"url":"https://github.com/lacussolutions/br-utils-py","last_synced_at":"2026-01-20T17:54:56.458Z","repository":{"id":312046743,"uuid":"1042890211","full_name":"LacusSolutions/br-utils-py","owner":"LacusSolutions","description":"Python utility functions and resources for Brazilian-related data.","archived":false,"fork":false,"pushed_at":"2025-08-28T04:30:24.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-28T13:50:51.810Z","etag":null,"topics":["br","cep","cnpj","cpf","formatter","generator","geoinformation","helpers","pip","ptyhon","py","pypi","utils","validator"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LacusSolutions.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-22T18:44:23.000Z","updated_at":"2025-08-28T04:54:32.000Z","dependencies_parsed_at":"2025-08-28T13:50:55.566Z","dependency_job_id":"9caf474e-83f2-4743-b14e-6dac870037ea","html_url":"https://github.com/LacusSolutions/br-utils-py","commit_stats":null,"previous_names":["lacussolutions/br-utils-py"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/LacusSolutions/br-utils-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LacusSolutions%2Fbr-utils-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LacusSolutions%2Fbr-utils-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LacusSolutions%2Fbr-utils-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LacusSolutions%2Fbr-utils-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LacusSolutions","download_url":"https://codeload.github.com/LacusSolutions/br-utils-py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LacusSolutions%2Fbr-utils-py/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272858540,"owners_count":25005092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["br","cep","cnpj","cpf","formatter","generator","geoinformation","helpers","pip","ptyhon","py","pypi","utils","validator"],"created_at":"2025-08-30T13:59:15.676Z","updated_at":"2025-12-28T17:54:14.085Z","avatar_url":"https://github.com/LacusSolutions.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"![br-utils for Python](https://br-utils.vercel.app/img/cover_br-utils.jpg)\n\n[![PyPI Version](https://img.shields.io/pypi/v/br-utilities)](https://pypi.org/project/br-utilities)\n[![PyPI Downloads](https://img.shields.io/pypi/dm/br-utilities)](https://pypi.org/project/br-utilities)\n[![Python Version](https://img.shields.io/pypi/pyversions/br-utilities)](https://www.python.org/)\n[![Test Status](https://img.shields.io/github/actions/workflow/status/LacusSolutions/br-utils-py/ci.yml?label=ci/cd)](https://github.com/LacusSolutions/br-utils-py/actions)\n[![Last Update Date](https://img.shields.io/github/last-commit/LacusSolutions/br-utils-py)](https://github.com/LacusSolutions/br-utils-py)\n[![Project License](https://img.shields.io/github/license/LacusSolutions/br-utils-py)](https://github.com/LacusSolutions/br-utils-py/blob/main/LICENSE)\n\nUnified toolkit to deal with Brazilian documents (CPF and CNPJ): validation, formatting, and generation of valid IDs.\n\n## Python Support\n\n| ![Python 3.10](https://img.shields.io/badge/Python-3.10-3776AB?logo=python\u0026logoColor=white) | ![Python 3.11](https://img.shields.io/badge/Python-3.11-3776AB?logo=python\u0026logoColor=white) | ![Python 3.12](https://img.shields.io/badge/Python-3.12-3776AB?logo=python\u0026logoColor=white) | ![Python 3.13](https://img.shields.io/badge/Python-3.13-3776AB?logo=python\u0026logoColor=white) | ![Python 3.14](https://img.shields.io/badge/Python-3.14-3776AB?logo=python\u0026logoColor=white) |\n|--- | --- | --- | --- | --- |\n| Passing ✔ | Passing ✔ | Passing ✔ | Passing ✔ | Passing ✔ |\n\n## Installation\n\n```bash\n$ pip install br-utilities\n```\n\n## Import\n\n```python\n# Using class-based resource\nfrom br_utils import BrUtils\n\n# Or import CPF/CNPJ utilities directly\nfrom br_utils import CpfUtils, CnpjUtils\n\n# Or using function-based approach\nfrom br_utils import cpf_fmt, cpf_gen, cpf_val, cnpj_fmt, cnpj_gen, cnpj_val\n\n# Or using the default instance\nfrom br_utils import br_utils\n```\n\n## Usage\n\n### Object-Oriented Usage\n\nThe `BrUtils` class provides a unified interface for all CPF and CNPJ operations:\n\n```python\nbr_utils = BrUtils()\n\n# CPF Operations\ncpf = '93247057062'\nprint(br_utils.cpf.format(cpf))       # returns '932.470.570-62'\nprint(br_utils.cpf.is_valid(cpf))     # returns True\nprint(br_utils.cpf.generate())        # returns '65453043078'\n\n# CNPJ Operations\ncnpj = '11222333000181'\nprint(br_utils.cnpj.format(cnpj))     # returns '11.222.333/0001-81'\nprint(br_utils.cnpj.is_valid(cnpj))   # returns True\nprint(br_utils.cnpj.generate())       # returns '12345678000195'\n```\n\n#### With Configuration Options\n\nYou can configure the formatter and generator options for both CPF and CNPJ in the constructor:\n\n```python\nfrom br_utils import BrUtils\nfrom br_utils.cpf import CpfFormatterOptions, CpfGeneratorOptions\nfrom br_utils.cnpj import CnpjFormatterOptions, CnpjGeneratorOptions\n\nbr_utils = BrUtils(\n    cpf_formatter=CpfFormatterOptions(hidden=True, hidden_key='#'),\n    cpf_generator=CpfGeneratorOptions(format=True),\n    cnpj_formatter=CnpjFormatterOptions(hidden=True, hidden_key='X'),\n    cnpj_generator=CnpjGeneratorOptions(format=True),\n)\n\n# CPF with hidden digits\ncpf = '93247057062'\nprint(br_utils.cpf.format(cpf))       # returns '932.###.###-##'\nprint(br_utils.cpf.generate())        # returns '730.085.350-06'\n\n# CNPJ with hidden digits\ncnpj = '11222333000181'\nprint(br_utils.cnpj.format(cnpj))     # returns '11.222.XXX/XXXX-XX'\nprint(br_utils.cnpj.generate())       # returns '12.345.678/0001-95'\n```\n\n### Using Individual Utilities\n\nYou can also use the individual `CpfUtils` and `CnpjUtils` classes directly:\n\n```python\nfrom br_utils import CpfUtils, CnpjUtils\n\ncpf_utils = CpfUtils()\ncnpj_utils = CnpjUtils()\n\n# CPF operations\nprint(cpf_utils.format('93247057062'))     # '932.470.570-62'\nprint(cpf_utils.is_valid('93247057062'))   # True\nprint(cpf_utils.generate())                # '65453043078'\n\n# CNPJ operations\nprint(cnpj_utils.format('11222333000181')) # '11.222.333/0001-81'\nprint(cnpj_utils.is_valid('11222333000181')) # True\nprint(cnpj_utils.generate())               # '12345678000195'\n```\n\n### Functional Programming\n\nThe package also provides standalone functions for each operation:\n\n```python\nfrom br_utils import cpf_fmt, cpf_gen, cpf_val, cnpj_fmt, cnpj_gen, cnpj_val\n\n# CPF Functions\ncpf = '93247057062'\nprint(cpf_fmt(cpf))                 # '932.470.570-62'\nprint(cpf_val(cpf))                 # True\nprint(cpf_gen())                    # '65453043078'\n\n# CNPJ Functions\ncnpj = '11222333000181'\nprint(cnpj_fmt(cnpj))               # '11.222.333/0001-81'\nprint(cnpj_val(cnpj))               # True\nprint(cnpj_gen())                   # '12345678000195'\n```\n\nOr use the default instance:\n\n```python\nfrom br_utils import br_utils\n\n# CPF\nprint(br_utils.cpf.format('93247057062'))     # '932.470.570-62'\nprint(br_utils.cpf.is_valid('93247057062'))   # True\nprint(br_utils.cpf.generate())                # '65453043078'\n\n# CNPJ\nprint(br_utils.cnpj.format('11222333000181')) # '11.222.333/0001-81'\nprint(br_utils.cnpj.is_valid('11222333000181')) # True\nprint(br_utils.cnpj.generate())               # '12345678000195'\n```\n\n## API Reference\n\n### BrUtils Class\n\nThe `BrUtils` class consolidates CPF and CNPJ utilities in a single class.\n\n```python\nBrUtils(\n    cpf_formatter: CpfFormatterOptions | None = None,\n    cpf_generator: CpfGeneratorOptions | None = None,\n    cnpj_formatter: CnpjFormatterOptions | None = None,\n    cnpj_generator: CnpjGeneratorOptions | None = None,\n)\n```\n\n**Properties:**\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `cpf` | `CpfUtils` | Instance of `CpfUtils` for CPF operations |\n| `cnpj` | `CnpjUtils` | Instance of `CnpjUtils` for CNPJ operations |\n\n### CPF Operations\n\n#### Formatting (`cpf_fmt` / `br_utils.cpf.format`)\n\nFormats a CPF string with customizable delimiters and masking options.\n\n```python\nbr_utils.cpf.format(\n    cpf_string: str,\n    hidden: bool | None = None,\n    hidden_key: str | None = None,\n    hidden_start: int | None = None,\n    hidden_end: int | None = None,\n    dot_key: str | None = None,\n    dash_key: str | None = None,\n    escape: bool | None = None,\n    on_fail: Callable | None = None,\n) -\u003e str\n```\n\n**Examples:**\n\n```python\ncpf = '93247057062'\n\n# Basic formatting\nprint(cpf_fmt(cpf))                 # '932.470.570-62'\n\n# With hidden digits\nprint(cpf_fmt(cpf, hidden=True))    # '932.***.***.***-**'\n\n# Custom delimiters\nprint(cpf_fmt(cpf, dot_key='', dash_key='_'))  # '932470570_62'\n```\n\n#### Generation (`cpf_gen` / `br_utils.cpf.generate`)\n\nGenerates valid CPF numbers with optional formatting and prefix completion.\n\n```python\nbr_utils.cpf.generate(\n    format: bool | None = None,\n    prefix: str | None = None,\n) -\u003e str\n```\n\n**Examples:**\n\n```python\n# Generate random CPF\nprint(cpf_gen())                     # '65453043078'\n\n# Generate formatted CPF\nprint(cpf_gen(format=True))          # '730.085.350-06'\n\n# Complete a prefix\nprint(cpf_gen(prefix='456237'))      # '45623741038'\n```\n\n#### Validation (`cpf_val` / `br_utils.cpf.is_valid`)\n\nValidates CPF numbers using the official algorithm.\n\n```python\nbr_utils.cpf.is_valid(cpf_string: str) -\u003e bool\n```\n\n**Examples:**\n\n```python\nprint(cpf_val('93247057062'))        # True\nprint(cpf_val('932.470.570-62'))     # True\nprint(cpf_val('93247057063'))        # False\n```\n\n### CNPJ Operations\n\n#### Formatting (`cnpj_fmt` / `br_utils.cnpj.format`)\n\nFormats a CNPJ string with customizable delimiters and masking options.\n\n```python\nbr_utils.cnpj.format(\n    cnpj_string: str,\n    hidden: bool | None = None,\n    hidden_key: str | None = None,\n    hidden_start: int | None = None,\n    hidden_end: int | None = None,\n    dot_key: str | None = None,\n    slash_key: str | None = None,\n    dash_key: str | None = None,\n    escape: bool | None = None,\n    on_fail: Callable | None = None,\n) -\u003e str\n```\n\n**Examples:**\n\n```python\ncnpj = '11222333000181'\n\n# Basic formatting\nprint(cnpj_fmt(cnpj))                 # '11.222.333/0001-81'\n\n# With hidden digits\nprint(cnpj_fmt(cnpj, hidden=True))    # '11.222.XXX/XXXX-XX'\n\n# Custom delimiters\nprint(cnpj_fmt(cnpj, dot_key='', slash_key='-', dash_key=''))  # '11222333-000181'\n```\n\n#### Generation (`cnpj_gen` / `br_utils.cnpj.generate`)\n\nGenerates valid CNPJ numbers with optional formatting and prefix completion.\n\n```python\nbr_utils.cnpj.generate(\n    format: bool | None = None,\n    prefix: str | None = None,\n) -\u003e str\n```\n\n**Examples:**\n\n```python\n# Generate random CNPJ\nprint(cnpj_gen())                     # '12345678000195'\n\n# Generate formatted CNPJ\nprint(cnpj_gen(format=True))          # '12.345.678/0001-95'\n\n# Complete a prefix\nprint(cnpj_gen(prefix='11222333'))    # '11222333000181'\n```\n\n#### Validation (`cnpj_val` / `br_utils.cnpj.is_valid`)\n\nValidates CNPJ numbers using the official algorithm.\n\n```python\nbr_utils.cnpj.is_valid(cnpj_string: str) -\u003e bool\n```\n\n**Examples:**\n\n```python\nprint(cnpj_val('11222333000181'))     # True\nprint(cnpj_val('11.222.333/0001-81')) # True\nprint(cnpj_val('11111111111111'))     # False\n```\n\n## Advanced Usage\n\n### Accessing Individual Components\n\nYou can access the individual formatter, generator, and validator instances for both CPF and CNPJ:\n\n```python\nbr_utils = BrUtils()\n\n# Access CPF components\ncpf_formatter = br_utils.cpf.formatter\ncpf_generator = br_utils.cpf.generator\ncpf_validator = br_utils.cpf.validator\n\n# Access CNPJ components\ncnpj_formatter = br_utils.cnpj.formatter\ncnpj_generator = br_utils.cnpj.generator\ncnpj_validator = br_utils.cnpj.validator\n\n# Use them directly\ncpf_formatter.format('93247057062', hidden=True)\ncnpj_generator.generate(format=True)\n```\n\n### Importing from Submodules\n\nYou can also import directly from the `cpf` and `cnpj` submodules:\n\n```python\n# Import CPF resources\nfrom br_utils.cpf import (\n    CpfUtils,\n    CpfFormatter,\n    CpfFormatterOptions,\n    CpfGenerator,\n    CpfGeneratorOptions,\n    CpfValidator,\n    cpf_fmt,\n    cpf_gen,\n    cpf_val,\n)\n\n# Import CNPJ resources\nfrom br_utils.cnpj import (\n    CnpjUtils,\n    CnpjFormatter,\n    CnpjFormatterOptions,\n    CnpjGenerator,\n    CnpjGeneratorOptions,\n    CnpjValidator,\n    cnpj_fmt,\n    cnpj_gen,\n    cnpj_val,\n)\n```\n\n## Dependencies\n\nThis package is built on top of the following specialized packages:\n\n- [`cpf-utils`](https://pypi.org/project/cpf-utils) - CPF utilities (formatting, generation, validation)\n- [`cnpj-utils`](https://pypi.org/project/cnpj-utils) - CNPJ utilities (formatting, generation, validation)\n\n## Contribution \u0026 Support\n\nWe welcome contributions! Please see our [Contributing Guidelines](https://github.com/LacusSolutions/br-utils-py/blob/main/CONTRIBUTING.md) for details. But if you find this project helpful, please consider:\n\n- ⭐ Starring the repository\n- 🤝 Contributing to the codebase\n- 💡 [Suggesting new features](https://github.com/LacusSolutions/br-utils-py/issues)\n- 🐛 [Reporting bugs](https://github.com/LacusSolutions/br-utils-py/issues)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/LacusSolutions/br-utils-py/blob/main/LICENSE) file for details.\n\n## Changelog\n\nSee [CHANGELOG](https://github.com/LacusSolutions/br-utils-py/blob/main/packages/br-utilities/CHANGELOG.md) for a list of changes and version history.\n\n---\n\nMade with ❤️ by [Lacus Solutions](https://github.com/LacusSolutions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flacussolutions%2Fbr-utils-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flacussolutions%2Fbr-utils-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flacussolutions%2Fbr-utils-py/lists"}