Metadata-Version: 2.4
Name: pybr
Version: 1.0.0
Summary: Collection of utilities for Brazilian data and formats
Author-email: Gustavo Efeiche <gustavo.efeiche@gmail.com>
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: brazil,cnpj,cpf,portuguese,utilities
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Internationalization
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Localization
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: pytest>=8.4.2
Description-Content-Type: text/markdown

# pybr

[![PyPI version](https://badge.fury.io/py/pybr.svg)](https://badge.fury.io/py/pybr)
[![Build Status](https://github.com/effeix/pybr/actions/workflows/python-package.yml/badge.svg)](https://github.com/effeix/pybr/actions)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

A Python library for Brazilian data and formats.

## Overview

`pybr` is a collection of utilities designed to handle common Brazilian data formats and standards. It provides a clean, simple, and reliable interface for validating, formatting, and cleaning various types of data specific to Brazil.

This library is aimed at developers who need to work with Brazilian data and want to ensure correctness and proper formatting according to local standards. While it currently includes robust support for document numbers, the long-term goal is to cover a wider range of data types, such as dates, currency, and more.

## Features

- **Brazilian Documents**: Tools for validating, formatting, and cleaning taxpayer registry numbers.
    - **CPF**: Support for individual taxpayer numbers.
    - **CNPJ**: Support for company taxpayer numbers.
- **Extensible**: Designed with a base structure to easily support other Brazilian data types in the future (e.g., dates, phone numbers).
- **Type-hinted**: Fully type-hinted for better editor support and code quality.
- **No Dependencies**: Lightweight and dependency-free.

## Installation

You can install `pybr` from PyPI:

```bash
pip install pybr
```

## Usage

Here are a few examples of how you can use `pybr`.

### Example: CPF

The `CPF` class provides methods to handle CPF numbers.

```python
from pybr.cpf import CPF

# --- Validation ---
# Note: Replace with a valid CPF for actual testing
cpf_valid = "123.456.789-00" 
cpf_invalid = "111.111.111-11"

print(f"Is {cpf_valid} valid? {CPF.is_valid(cpf_valid)}")
# Is 123.456.789-00 valid? True

print(f"Is {cpf_invalid} valid? {CPF.is_valid(cpf_invalid)}")
# Is 111.111.111-11 valid? False

# By default, repeated digit sequences are invalid. You can allow them:
print(f"Is {cpf_invalid} valid (allowing repeated)? {CPF.is_valid(cpf_invalid, allow_repeated=True)}")
# Is 111.111.111-11 valid (allowing repeated)? True (but checksum is still checked)


# --- Formatting ---
unformatted_cpf = "12345678900"
formatted_cpf = CPF.format(unformatted_cpf)
print(f"Formatted CPF: {formatted_cpf}")
# Formatted CPF: 123.456.789-00


# --- Cleaning ---
dirty_cpf = "123.456.789/00"
clean_cpf = CPF.clean(dirty_cpf)
print(f"Cleaned CPF: {clean_cpf}")
# Cleaned CPF: 12345678900


# --- Enforcement ---
# The `validate` method raises a ValueError for invalid CPFs.
try:
    CPF.validate(cpf_invalid)
except ValueError as e:
    print(e)
    # "Invalid CPF"
```

### Example: CNPJ

The `CNPJ` class provides methods to handle CNPJ numbers.

```python
from pybr.cnpj import CNPJ

# --- Validation ---
# Note: Replace with a valid CNPJ for actual testing
cnpj_valid = "00.000.000/0001-91" 
cnpj_invalid = "11.111.111/1111-11"

print(f"Is {cnpj_valid} valid? {CNPJ.is_valid(cnpj_valid)}")
# Is 00.000.000/0001-91 valid? True

print(f"Is {cnpj_invalid} valid? {CNPJ.is_valid(cnpj_invalid)}")
# Is 11.111.111/1111-11 valid? False


# --- Formatting ---
unformatted_cnpj = "00000000000191"
formatted_cnpj = CNPJ.format(unformatted_cnpj)
print(f"Formatted CNPJ: {formatted_cnpj}")
# Formatted CNPJ: 00.000.000/0001-91


# --- Cleaning ---
dirty_cnpj = "00.000.000-0001/91"
clean_cnpj = CNPJ.clean(dirty_cnpj)
print(f"Cleaned CNPJ: {clean_cnpj}")
# Cleaned CNPJ: 00000000000191


# --- Enforcement ---
# The `validate` method raises a ValueError for invalid CNPJs.
try:
    CNPJ.validate(cnpj_invalid)
except ValueError as e:
    print(e)
    # "Invalid CNPJ"
```

## Contributing

Contributions are welcome! If you have a feature request, bug report, or want to add support for another Brazilian data type (like dates, phone numbers, etc.), please feel free to:

1. Fork the repository.
2. Create a new branch (`git checkout -b feature/my-new-feature`).
3. Make your changes and add tests.
4. Ensure the test suite passes (`pytest`).
5. Open a pull request.

## License

This project is licensed under the GPL-3.0-only License. See the [LICENSE](LICENSE) file for details.
