Metadata-Version: 2.4
Name: plonegovbr.brfields
Version: 1.0.0a3
Summary: Packages implementing fields used in Brazil for Dexterity and Volto projects
Project-URL: Homepage, https://github.com/plonegovbr/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 :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Plone
Classifier: Framework :: Plone :: 6.0
Classifier: Framework :: Plone :: 6.1
Classifier: Framework :: Plone :: Addon
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: plone-api
Requires-Dist: plone-restapi
Requires-Dist: plone-volto
Requires-Dist: products-cmfplone>=6.0
Requires-Dist: validate-docbr>=1.10.0
Provides-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>=0.5.0; extra == 'test'
Requires-Dist: zest-releaser[recommended]; extra == 'test'
Requires-Dist: zestreleaser-towncrier; 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.

## Installation 🛠️

To install `plonegovbr.brfields`, add it to your project dependencies and install the package using your preferred method.

### Using `setup.py` 🐍

For projects managed via `setup.py`, edit your `setup.py` file and add `plonegovbr.brfields` to the `install_requires` list:

````python
install_requires = [
    ...
    "plonegovbr.brfields",
]
````

Then, install the dependencies:

````sh
pip install -e .
````

### Using `pyproject.toml` 📜

For projects using `pyproject.toml`, add `plonegovbr.brfields` to the **dependencies** list under the `[project]` section:

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

Then, install the dependencies:

````sh
pip install .
````

## 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 plonegovbr.brfields.fields import CPF
from zope.interface import Interface
from plone.supermodel import model


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 ❤️.
