Metadata-Version: 2.4
Name: PyCodigosBancos
Version: 0.0.2
Summary: A package that helps you to get brazilian's offset codes.
Author-email: Joao Paulo de Castro Lima <joao@paulo.com>
Project-URL: Homepage, https://github.com/joao2391/PyCodigosBancos
Project-URL: Issues, https://github.com/joao2391/PyCodigosBancos/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# PyCodigosBancos

PyCodigosBancos is a small Python library for working with Brazilian bank codes (lista de bancos). It provides a lightweight API to build an in-memory dictionary of banks and lookup helpers.

## Installation

Install from PyPI (when published):

```bash
pip install -U PyCodigosBancos
```

Or install from source for development:

```bash
pip install -e .
```

## Usage

Primary entrypoint: `CodigosBancos` (in `py_codigos_bancos.codigos_bancos`). The class builds a dictionary of `Banco` objects (by fetching and parsing codigobanco.com) and exposes lookup helpers. Example:

```python
from py_codigos_bancos.codigos_bancos import CodigosBancos

cb = CodigosBancos()

# get all banks (list of dicts)
all_bancos = cb.get_bancos()
print(all_bancos[:2])

# lookup by code -> dict
b = cb.get_bancos_by_codigo(1)
print(b)  # {'nome': 'Banco do Brasil', 'site': 'https://bb.example', 'codigo': 1}

# search by name (case-insensitive) -> list of dicts
matches = cb.get_bancos_by_nome('Banco do Brasil')
print(matches)
```

Notes:
- Methods return serializable dictionaries with keys: `nome`, `site`, `codigo`.
- Network access occurs when `CodigosBancos()` is constructed; patch or mock `_CodigosBancos__build_banco` in tests to avoid live requests.

## API Reference

### `CodigosBancos`

Key methods:

- `get_bancos() -> List[Dict]` — returns all banks as a list of dicts `[{"nome","site","codigo"}, ...]`.
- `get_bancos_by_codigo(codigo: int) -> Dict` — returns the bank dict for `codigo`. Raises `ValueError` for invalid or missing codes.
- `get_bancos_by_nome(nome_banco: str) -> List[Dict]` — case-insensitive substring search returning matching bank dicts. Raises `ValueError` if no matches.

### `Banco` model (`py_codigos_bancos.banco.Banco`)

Simple data holder with attributes: `codigo`, `nome`, `site`.

## Testing

Run the test suite with `pytest`:

```bash
pytest -q
```

Unit tests in `tests/` patch the internal builder to avoid network calls.

## Contributing

Contributions welcome. Open an issue to discuss major changes and keep tests updated.

## License

[MIT](https://choosealicense.com/licenses/mit/)
