Metadata-Version: 2.4
Name: climasus_readdbc_py
Version: 0.1.3
Summary: Pure-Python reader for DATASUS .dbc files (blast-compressed dBASE III)
Author-email: Marlon Resende Faria <marlon.faria@usp.br>, Thauã Menezes <thaua.menezes@unesp.br>, "Dr. Max Anjos" <max.anjos@campus.ul.pt>, Andrey Araújo <andreyke.araujo@gmail.com>
Maintainer-email: "Dr. Max Anjos" <max.anjos@campus.ul.pt>
License-Expression: MIT
Project-URL: Homepage, https://github.com/climasus/climasus_readdbc_py
Project-URL: Repository, https://github.com/climasus/climasus_readdbc_py
Project-URL: Bug Tracker, https://github.com/climasus/climasus_readdbc_py/issues
Keywords: datasus,dbc,dbf,sus,blast,pkware
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
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: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# readdbc

[![PyPI version](https://img.shields.io/pypi/v/readdbc.svg)](https://pypi.org/project/readdbc/)
[![CI](https://github.com/climasus/climasus_readdbc_py/actions/workflows/ci.yml/badge.svg)](https://github.com/climasus/climasus_readdbc_py/actions/workflows/ci.yml)
[![Python Versions](https://img.shields.io/pypi/pyversions/readdbc.svg)](https://pypi.org/project/readdbc/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Leitor puro-Python para arquivos `.dbc` do DATASUS — formato dBASE III com compressão PKWARE blast. Sem dependências C, sem compilador necessário.

---

## Instalação

```bash
pip install climasus_readdbc_py
```

**Requisitos:** Python ≥ 3.10, pandas ≥ 2.0

---

## Uso rápido

```python
import readdbc

# Ler arquivo .dbc diretamente como DataFrame pandas
df = readdbc.read_dbc("DOSP2023.dbc")

# Ler arquivo .dbf comum
df = readdbc.read_dbf("dados.dbf")

# Descomprimir bytes brutos de um .dbc para .dbf
with open("DOSP2023.dbc", "rb") as f:
    compressed = f.read()

raw_dbf_bytes = readdbc.blast_decompress(compressed)
```

---

## O formato DBC

Os arquivos `.dbc` são distribuídos pelo [DATASUS](https://datasus.saude.gov.br/) para transferência eficiente dos microdados do SUS (Sistema Único de Saúde). Internamente, são arquivos dBASE III (`.dbf`) cujo bloco de registros foi comprimido com o algoritmo **PKWARE DCL Implode** (também chamado de *blast*).

**Layout interno:**

```
[0 .. H)       Cabeçalho DBF não comprimido (H = uint16 LE nos bytes 8-9)
[H .. H+4)     4 bytes de CRC / padding (ignorados)
[H+4 .. EOF)   Dados comprimidos com PKWare blast
```

A descompressão produz: `cabeçalho_dbf + registros_descomprimidos = DBF completo`.

---

## API de referência

| Função / Classe       | Descrição                                              |
|-----------------------|--------------------------------------------------------|
| `read_dbc(path)`      | Lê um `.dbc` e retorna `pd.DataFrame`                  |
| `read_dbf(path)`      | Lê um `.dbf` e retorna `pd.DataFrame`                  |
| `blast_decompress(b)` | Descomprime bytes brutos do formato blast              |
| `dbc_to_dbf(b)`       | Converte bytes `.dbc` para bytes `.dbf`                |
| `BlastError`          | Exceção para erros de descompressão                    |
| `DBFError`            | Exceção para erros de leitura DBF                      |
| `DBCError`            | Exceção para erros de leitura DBC                      |

---

## Projeto ClimaSUS

Este pacote faz parte do ecossistema **ClimaSUS** — plataforma de análise de dados climáticos e de saúde pública do SUS.

- Repositório principal: <https://github.com/climasus/climasus_readdbc_py>
- Organização: <https://github.com/climasus>
