[v2][br-utils] Upgrade to latest API

[juliolmuller]

Summary by CodeRabbit

• New Features
  • Added support for the newer alphanumeric CNPJ format.
  • Added/expanded a ready-to-use br_utils singleton and a unified BrUtils façade for CPF/CNPJ utilities.
• Breaking Changes
  • CPF/CNPJ helper functions (e.g., cpf_fmt/cpf_gen/cpf_val, cnpj_fmt/cnpj_gen/cnpj_val) are no longer re-exported from the package root; import them from br_utils.cpf / br_utils.cnpj.
  • Updated BrUtils setup/option configuration behavior and validation defaults.
• Documentation
  • Rewrote the English README, updated the changelog link, and added a complete Portuguese README.
• Tests
  • Replaced/expanded the Python test suite with consolidated behavioral specs.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 663c10f5-d30e-462d-8595-cb0958942acf

📥 Commits

Reviewing files that changed from the base of the PR and between 95070da and c7a17e7.

📒 Files selected for processing (5)

• README.md
• README.pt.md
• packages/br-utilities/README.md
• packages/br-utilities/README.pt.md
• packages/br-utilities/src/br_utils/br_utils.py

💤 Files with no reviewable changes (2)

• packages/br-utilities/README.pt.md
• packages/br-utilities/README.md

---

📝 Walkthrough

Walkthrough

BrUtils now supports nested CPF/CNPJ configuration, property-based replacement of bundled utils, expanded public re-exports, updated package metadata and pytest discovery, new spec-style coverage, and rewritten English/Portuguese documentation for the v2 API.

Changes

BrUtils v2 upgrade

Layer / File(s)	Summary
BrUtils facade core packages/br-utilities/src/br_utils/br_utils.py	Adds _resolve_utils, changes storage to private slots, and updates BrUtils to accept instance, mapping, and component-option inputs through constructor and cpf/cnpj setters.
Package exports and re-exports packages/br-utilities/src/br_utils/__init__.py, packages/br-utilities/src/br_utils/cpf/__init__.py, packages/br-utilities/src/br_utils/cnpj/__init__.py	Adds the package docstring, __all__, __version__, default br_utils singleton, and new CPF/CNPJ validator exception exports.
Package metadata and test config packages/br-utilities/pyproject.toml, packages/br-utilities/tests/conftest.py	Updates project description, dependency constraints, homepage URL, pytest discovery/import settings, and package test path setup.
BrUtils behavioral tests packages/br-utilities/tests/br_utils.spec.py	Adds spec coverage for construction modes, invalid options, setters, accessors, and slot behavior.
CPF and CNPJ behavioral spec tests packages/br-utilities/tests/cpf.spec.py, packages/br-utilities/tests/cnpj.spec.py	Adds spec coverage for CPF and CNPJ formatting, generation, and validation through multiple configuration styles.
Package export smoke tests packages/br-utilities/tests/package.spec.py	Adds smoke tests for the default singleton, __all__, and documented CPF/CNPJ submodule exports.
README and changelog documentation README.md, README.pt.md, packages/br-utilities/README.md, packages/br-utilities/CHANGELOG.md	Rewrites English and Portuguese docs and updates changelog notes for the new facade, options, exports, and dependency ranges.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related issues

• Implement package br-utils br-utils-java#9: The issue title and description align with this PR’s package-level façade, exports, and docs/test updates.

Possibly related PRs

• LacusSolutions/br-utils-py#19: Related to the BrUtils facade and CNPJ wrapper/API alignment.
• LacusSolutions/br-utils-py#58: Related to the CNPJ validator exception/export surface updated here.
• LacusSolutions/br-utils-py#63: Related to the CPF validator exception/export surface updated here.

Suggested labels: enhancement

Poem

A rabbit hops through docs so bright,
And facade fields reset just right.
CPF, CNPJ, side by side,
New exports bloom with v2 pride,
Hop hop — the bundle takes its flight! 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title is related to the v2 API upgrade, but "Upgrade to latest API" is too vague to clearly describe the main changes.	Use a more specific title that mentions the br-utils v2 API refresh and the key public changes, such as the new BrUtils facade and CNPJ/CPF export updates.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/br-utils-v2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/br-utilities/pyproject.toml`:
- Around line 75-78: Pytest is configured to look for describe-style names, but
nested describe/it blocks in the new *.spec.py files will not be collected
without a describe-style plugin. Update the test setup for br-utilities so the
pytest configuration in pyproject.toml is paired with a plugin such as
pytest-describe, and make sure that plugin is added to the package’s test
dependencies so nested describe_* / it_* tests are actually discovered.

In `@packages/br-utilities/README.md`:
- Around line 182-183: The README documentation for BrUtils has incorrect
__slots__ names; update the __slots__ description to match the actual private
slot names used by the BrUtils class in br_utils.py. Refer to the BrUtils class
and its cpf/cnpj properties, and change the text from public slot names to the
private slot layout so the documented class structure is accurate.

In `@packages/br-utilities/README.pt.md`:
- Around line 182-183: The documented __slots__ values for BrUtils are
incorrect; update the README entry to match the private slots used by the
BrUtils class in br_utils.py. Keep the description aligned with the actual
implementation by referring to the _cpf and _cnpj slot names, and ensure the
surrounding cpf/cnpj getter-setter documentation still accurately describes the
public properties.

In `@packages/br-utilities/src/br_utils/br_utils.py`:
- Around line 28-46: The _resolve_cpf and _resolve_cnpj helpers in br_utils.py
duplicate the same instance-check/None-check/constructor pattern. Refactor them
into a single shared generic resolver that takes the target utils class as a
parameter, then have both _resolve_cpf and _resolve_cnpj delegate to it while
preserving the current behavior for CpfUtils, CnpjUtils, and Mapping inputs.
- Around line 166-170: The example in the br_utils documentation is using an
unsupported direct assignment on CnpjGenerator. Update the referenced setter
example to go through utils.cnpj.generator.options.type instead of
utils.cnpj.generator.type, since CnpjGenerator exposes options rather than a
top-level type property.
- Around line 209-213: The guidance in the CPF utilities docs uses the wrong API
for toggling the formatter hidden setting. Update the example in the
CpfFormatter-related text to reference the formatter’s options object, using
utils.cpf.formatter.options.hidden instead of utils.cpf.formatter.hidden, so the
instruction matches the actual exposed property on CpfFormatter.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: cd979b72-47b7-4acb-941e-25585d104c5f

📥 Commits

Reviewing files that changed from the base of the PR and between 8f5cc88 and 95070da.

📒 Files selected for processing (17)

• packages/br-utilities/CHANGELOG.md
• packages/br-utilities/README.md
• packages/br-utilities/README.pt.md
• packages/br-utilities/pyproject.toml
• packages/br-utilities/src/br_utils/__init__.py
• packages/br-utilities/src/br_utils/br_utils.py
• packages/br-utilities/src/br_utils/cnpj/__init__.py
• packages/br-utilities/src/br_utils/cpf/__init__.py
• packages/br-utilities/tests/br_utils.spec.py
• packages/br-utilities/tests/br_utils_cnpj_test.py
• packages/br-utilities/tests/br_utils_cpf_test.py
• packages/br-utilities/tests/br_utils_init_test.py
• packages/br-utilities/tests/br_utils_reexports_test.py
• packages/br-utilities/tests/cnpj.spec.py
• packages/br-utilities/tests/conftest.py
• packages/br-utilities/tests/cpf.spec.py
• packages/br-utilities/tests/package.spec.py

💤 Files with no reviewable changes (5)

• packages/br-utilities/tests/conftest.py
• packages/br-utilities/tests/br_utils_cpf_test.py
• packages/br-utilities/tests/br_utils_reexports_test.py
• packages/br-utilities/tests/br_utils_init_test.py
• packages/br-utilities/tests/br_utils_cnpj_test.py