Metadata-Version: 2.5
Name: plonegovbr.brfields
Version: 1.0.0b1
Summary: Dexterity fields for data used in Brazilian projects: CEP, CNPJ, CPF, states, and phone numbers.
Project-URL: Homepage, https://github.com/plonegovbr/brfieldsandwidgets
Project-URL: Documentation, https://plonegovbr.github.io/brfieldsandwidgets/
Project-URL: PyPI, https://pypi.org/project/plonegovbr.brfields
Project-URL: Source, https://github.com/plonegovbr/brfieldsandwidgets
Project-URL: Tracker, https://github.com/plonegovbr/brfieldsandwidgets/issues
Author-email: PloneGov-BR <gov@plone.org.br>
License-Expression: GPL-2.0-only
License-File: LICENSE.GPL
License-File: LICENSE.md
Keywords: CMS,Dexterity,Plone,Python,eGov
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Plone
Classifier: Framework :: Plone :: 6.1
Classifier: Framework :: Plone :: 6.2
Classifier: Framework :: Plone :: Addon
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: brutils>=2.5.0
Requires-Dist: plone-api
Requires-Dist: plone-restapi
Requires-Dist: plone-volto
Requires-Dist: products-cmfplone
Provides-Extra: test
Requires-Dist: horse-with-no-namespace; extra == 'test'
Requires-Dist: plone-app-testing; extra == 'test'
Requires-Dist: plone-exportimport; extra == 'test'
Requires-Dist: plone-restapi[test]; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-plone>=1.1.0; extra == 'test'
Description-Content-Type: text/markdown

# plonegovbr.brfields 🚀

Plone package implementing Dexterity fields for common data types used in Brazil.

## Features ✨

This package provides the following Dexterity fields:

- **CEP** (`plonegovbr.brfields.fields.CEP`): 🏠 A text field for validating and storing Brazilian postal codes (CEP) with basic format validation.
- **CNPJ** (`plonegovbr.brfields.fields.CNPJ`): 🏢 A text field for validating and storing Brazilian company registration numbers (CNPJ) with value validation.
- **CPF** (`plonegovbr.brfields.fields.CPF`): 🆔 A text field for validating and storing Brazilian individual taxpayer numbers (CPF) with value validation.
- **Estados** (`plonegovbr.brfields.fields.Estados`): 📍 A choice field with a predefined vocabulary of Brazilian states, using `plonegovbr.vocabulary.estados` for validation.
- **Telefone** (`plonegovbr.brfields.fields.Telefone`): 📞 A text field for validating and storing Brazilian phone numbers.

Additionally, the package provides the following named vocabulary:

- `plonegovbr.vocabulary.estados`: 📌 A predefined list of Brazilian states.

## Compatibility ✅

| | |
|---|---|
| Plone | 6.1 and 6.2 |
| Python | 3.11 to 3.14 |

## Installation 🛠️

Add `plonegovbr.brfields` to the **dependencies** list under the `[project]` section of your project's `pyproject.toml`:

````toml
dependencies = [
    "Products.CMFPlone",
    "plonegovbr.brfields",
]
````

Then install the dependencies as your project normally does, and install the **Brazilian Fields for Dexterity and Volto: Install** profile in your site.

The [documentation](https://plonegovbr.github.io/brfieldsandwidgets/) has the full installation guide.

## Usage 📖

To use one of these fields in your content type, import the required field and include it in your schema definition.

Example:

````python
from plone.supermodel import model
from plonegovbr.brfields import _
from plonegovbr.brfields.fields import CPF


class IDemoContent(model.Schema):
    """Demo content showcasing all available fields."""

    cpf = CPF(
        title=_("CPF"),
        description=_("Enter the CPF number"),
        required=True,
    )
````

### Volto Support ⚡

For Volto support, you need to add the package [`@plonegovbr/volto-brwidgets`](https://github.com/plonegovbr/brfieldsandwidgets/) to your Volto project. This package provides widgets to properly render the Brazilian-specific fields in the Volto UI.


## Contributing 🤝

Contributions are welcome! If you find any issues or want to suggest improvements, please check out:

- [Source Code](https://github.com/plonegovbr/brfieldsandwidgets/) 💻
- [Issue Tracker](https://github.com/plonegovbr/brfieldsandwidgets/issues) 🐛

## License 📜

This project is licensed under the **GPLv2**.

## Credits & Acknowledgements 🙏

This package was developed and maintained by the [PloneGov-BR](https://plone.org.br/gov) community ❤️.
