bacendata 0.1.0__tar.gz

bacendata-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bacendata-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: bacendata
+Version: 0.1.0
+Summary: Acesso simplificado aos dados do Banco Central do Brasil
+Author: Felipe
+License: MIT
+Project-URL: Homepage, https://github.com/fmaignacio/bacendata
+Project-URL: Repository, https://github.com/fmaignacio/bacendata
+Project-URL: Issues, https://github.com/fmaignacio/bacendata/issues
+Keywords: bacen,bcb,sgs,banco-central,economia,brasil
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pandas>=1.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: respx>=0.20; extra == "dev"
+Dynamic: license-file
+
+# BacenData
+
+Acesso simplificado aos dados do Banco Central do Brasil.
+
+Resolve automaticamente a limitacao de 10 anos por consulta imposta pelo BACEN em marco/2025, com paginacao transparente, retry inteligente e cache local.
+
+## Instalacao
+
+```bash
+pip install bacendata
+```
+
+## Uso rapido
+
+```python
+from bacendata import sgs
+
+# Buscar a taxa Selic (por codigo ou nome)
+selic = sgs.get(11, start="2020-01-01")
+selic = sgs.get("selic", start="2020-01-01")
+
+# Buscar multiplas series de uma vez
+df = sgs.get({"Selic": 11, "IPCA": 433, "Dolar": 1}, start="2010-01-01")
+
+# Ultimos N valores
+ipca = sgs.get(433, last=12)
+
+# Buscar mais de 10 anos (paginacao automatica!)
+selic_longa = sgs.get(11, start="2000-01-01", end="2024-12-31")
+```
+
+## Funcionalidades
+
+- **Paginacao automatica** — consultas >10 anos sao divididas em chunks e feitas em paralelo
+- **Multiplas series** — busque varias series de uma vez com `dict`
+- **Catalogo integrado** — use nomes em vez de codigos: `sgs.get("selic")`
+- **Cache local** — evite chamadas repetidas a API do BACEN
+- **Retry com backoff** — trata automaticamente erros 429, 500 e timeouts
+- **Formato flexivel** — aceita datas ISO (`2024-01-01`), brasileiro (`01/01/2024`) e objetos `date`
+- **Retorno pandas** — dados prontos para analise como `DataFrame`
+- **Async nativo** — interface sync (`get`) e async (`aget`) para FastAPI
+
+## Catalogo de series
+
+Voce pode usar nomes em vez de codigos numericos:
+
+```python
+sgs.get("selic")          # Taxa Selic diaria (codigo 11)
+sgs.get("ipca")           # IPCA mensal (codigo 433)
+sgs.get("dolar")          # Dolar PTAX compra (codigo 1)
+sgs.get("euro")           # Euro compra (codigo 10813)
+sgs.get("focus_ipca")     # Expectativa IPCA 12m (codigo 27574)
+sgs.get("focus_selic")    # Expectativa Selic (codigo 27575)
+sgs.get("inadimplencia_pf")  # Inadimplencia PF (codigo 21112)
+```
+
+Para listar todas as series disponiveis:
+
+```python
+from bacendata.wrapper.catalogo import listar
+
+for serie in listar():
+    print(f"{serie.codigo:>6} | {serie.nome} ({serie.periodicidade})")
+```
+
+## Cache local
+
+Ative o cache para evitar chamadas repetidas:
+
+```python
+from bacendata import sgs
+
+sgs.cache.ativar()  # Salva em ~/.bacendata/cache.db
+
+selic = sgs.get(11, start="2020-01-01")  # Primeira vez: busca na API
+selic = sgs.get(11, start="2020-01-01")  # Segunda vez: le do cache
+
+# Caminho customizado
+sgs.cache.ativar("/tmp/meu_cache.db")
+
+# Limpar cache
+sgs.cache.limpar()
+
+# Desativar
+sgs.cache.desativar()
+```
+
+TTL padrao por periodicidade:
+- Series diarias: 1 hora
+- Series semanais: 6 horas
+- Series mensais: 24 horas
+
+## Metadados
+
+```python
+info = sgs.metadata(433)
+# {'codigo': 433, 'nome': 'IPCA - Variacao mensal', 'periodicidade': 'Mensal', ...}
+```
+
+## Interface async
+
+Para uso em FastAPI ou outros frameworks async:
+
+```python
+import asyncio
+from bacendata import sgs
+
+async def main():
+    df = await sgs.aget(11, start="2020-01-01")
+    print(df)
+
+asyncio.run(main())
+```
+
+## Series disponiveis no catalogo
+
+| Codigo | Nome | Periodicidade | Aliases |
+|--------|------|---------------|---------|
+| 1 | Dolar (compra) | Diaria | `dolar`, `usd`, `ptax`, `cambio` |
+| 11 | Selic diaria | Diaria | `selic`, `selic_diaria` |
+| 12 | Selic acumulada no mes | Mensal | `selic_mensal`, `selic_acumulada` |
+| 433 | IPCA | Mensal | `ipca`, `inflacao` |
+| 4189 | Juros PF | Mensal | `juros_pf`, `taxa_pf` |
+| 4390 | Selic acumulada anualizada | Mensal | `selic_anual`, `selic_anualizada` |
+| 7326 | Reservas Internacionais | Diaria | `reservas` |
+| 10813 | Euro (compra) | Diaria | `euro`, `eur` |
+| 20542 | Saldo Credito Livre | Mensal | `saldo_credito`, `carteira_credito` |
+| 21082 | Inadimplencia PJ | Mensal | `inadimplencia_pj`, `default_pj` |
+| 21112 | Inadimplencia PF | Mensal | `inadimplencia_pf`, `default_pf` |
+| 25434 | Juros Credito Livre | Mensal | `juros_credito`, `credito_livre` |
+| 27574 | Expectativa IPCA 12m | Semanal | `focus_ipca`, `expectativa_ipca` |
+| 27575 | Expectativa Selic | Semanal | `focus_selic`, `expectativa_selic` |
+
+Qualquer codigo SGS funciona mesmo fora do catalogo: `sgs.get(99999, last=10)`.
+
+## Tratamento de erros
+
+```python
+from bacendata.wrapper.exceptions import (
+    SerieNaoEncontrada,
+    BacenAPIError,
+    BacenTimeoutError,
+    ParametrosInvalidos,
+)
+
+try:
+    df = sgs.get(99999, start="2024-01-01")
+except SerieNaoEncontrada:
+    print("Serie nao existe")
+except BacenTimeoutError:
+    print("API do BACEN nao respondeu")
+except BacenAPIError as e:
+    print(f"Erro {e.status_code}: {e.mensagem}")
+```
+
+## Desenvolvimento
+
+```bash
+git clone https://github.com/fmaignacio/bacendata.git
+cd bacendata
+python -m venv .venv
+source .venv/bin/activate  # Linux/Mac
+pip install -e ".[dev]"
+
+# Testes
+python -m pytest tests/ -v --cov=src/bacendata
+
+# Lint
+ruff check src/ tests/
+black src/ tests/
+```
+
+## Licenca
+
+MIT

bacendata-0.1.0/README.md

@@ -0,0 +1,175 @@
+# BacenData
+
+Acesso simplificado aos dados do Banco Central do Brasil.
+
+Resolve automaticamente a limitacao de 10 anos por consulta imposta pelo BACEN em marco/2025, com paginacao transparente, retry inteligente e cache local.
+
+## Instalacao
+
+```bash
+pip install bacendata
+```
+
+## Uso rapido
+
+```python
+from bacendata import sgs
+
+# Buscar a taxa Selic (por codigo ou nome)
+selic = sgs.get(11, start="2020-01-01")
+selic = sgs.get("selic", start="2020-01-01")
+
+# Buscar multiplas series de uma vez
+df = sgs.get({"Selic": 11, "IPCA": 433, "Dolar": 1}, start="2010-01-01")
+
+# Ultimos N valores
+ipca = sgs.get(433, last=12)
+
+# Buscar mais de 10 anos (paginacao automatica!)
+selic_longa = sgs.get(11, start="2000-01-01", end="2024-12-31")
+```
+
+## Funcionalidades
+
+- **Paginacao automatica** — consultas >10 anos sao divididas em chunks e feitas em paralelo
+- **Multiplas series** — busque varias series de uma vez com `dict`
+- **Catalogo integrado** — use nomes em vez de codigos: `sgs.get("selic")`
+- **Cache local** — evite chamadas repetidas a API do BACEN
+- **Retry com backoff** — trata automaticamente erros 429, 500 e timeouts
+- **Formato flexivel** — aceita datas ISO (`2024-01-01`), brasileiro (`01/01/2024`) e objetos `date`
+- **Retorno pandas** — dados prontos para analise como `DataFrame`
+- **Async nativo** — interface sync (`get`) e async (`aget`) para FastAPI
+
+## Catalogo de series
+
+Voce pode usar nomes em vez de codigos numericos:
+
+```python
+sgs.get("selic")          # Taxa Selic diaria (codigo 11)
+sgs.get("ipca")           # IPCA mensal (codigo 433)
+sgs.get("dolar")          # Dolar PTAX compra (codigo 1)
+sgs.get("euro")           # Euro compra (codigo 10813)
+sgs.get("focus_ipca")     # Expectativa IPCA 12m (codigo 27574)
+sgs.get("focus_selic")    # Expectativa Selic (codigo 27575)
+sgs.get("inadimplencia_pf")  # Inadimplencia PF (codigo 21112)
+```
+
+Para listar todas as series disponiveis:
+
+```python
+from bacendata.wrapper.catalogo import listar
+
+for serie in listar():
+    print(f"{serie.codigo:>6} | {serie.nome} ({serie.periodicidade})")
+```
+
+## Cache local
+
+Ative o cache para evitar chamadas repetidas:
+
+```python
+from bacendata import sgs
+
+sgs.cache.ativar()  # Salva em ~/.bacendata/cache.db
+
+selic = sgs.get(11, start="2020-01-01")  # Primeira vez: busca na API
+selic = sgs.get(11, start="2020-01-01")  # Segunda vez: le do cache
+
+# Caminho customizado
+sgs.cache.ativar("/tmp/meu_cache.db")
+
+# Limpar cache
+sgs.cache.limpar()
+
+# Desativar
+sgs.cache.desativar()
+```
+
+TTL padrao por periodicidade:
+- Series diarias: 1 hora
+- Series semanais: 6 horas
+- Series mensais: 24 horas
+
+## Metadados
+
+```python
+info = sgs.metadata(433)
+# {'codigo': 433, 'nome': 'IPCA - Variacao mensal', 'periodicidade': 'Mensal', ...}
+```
+
+## Interface async
+
+Para uso em FastAPI ou outros frameworks async:
+
+```python
+import asyncio
+from bacendata import sgs
+
+async def main():
+    df = await sgs.aget(11, start="2020-01-01")
+    print(df)
+
+asyncio.run(main())
+```
+
+## Series disponiveis no catalogo
+
+| Codigo | Nome | Periodicidade | Aliases |
+|--------|------|---------------|---------|
+| 1 | Dolar (compra) | Diaria | `dolar`, `usd`, `ptax`, `cambio` |
+| 11 | Selic diaria | Diaria | `selic`, `selic_diaria` |
+| 12 | Selic acumulada no mes | Mensal | `selic_mensal`, `selic_acumulada` |
+| 433 | IPCA | Mensal | `ipca`, `inflacao` |
+| 4189 | Juros PF | Mensal | `juros_pf`, `taxa_pf` |
+| 4390 | Selic acumulada anualizada | Mensal | `selic_anual`, `selic_anualizada` |
+| 7326 | Reservas Internacionais | Diaria | `reservas` |
+| 10813 | Euro (compra) | Diaria | `euro`, `eur` |
+| 20542 | Saldo Credito Livre | Mensal | `saldo_credito`, `carteira_credito` |
+| 21082 | Inadimplencia PJ | Mensal | `inadimplencia_pj`, `default_pj` |
+| 21112 | Inadimplencia PF | Mensal | `inadimplencia_pf`, `default_pf` |
+| 25434 | Juros Credito Livre | Mensal | `juros_credito`, `credito_livre` |
+| 27574 | Expectativa IPCA 12m | Semanal | `focus_ipca`, `expectativa_ipca` |
+| 27575 | Expectativa Selic | Semanal | `focus_selic`, `expectativa_selic` |
+
+Qualquer codigo SGS funciona mesmo fora do catalogo: `sgs.get(99999, last=10)`.
+
+## Tratamento de erros
+
+```python
+from bacendata.wrapper.exceptions import (
+    SerieNaoEncontrada,
+    BacenAPIError,
+    BacenTimeoutError,
+    ParametrosInvalidos,
+)
+
+try:
+    df = sgs.get(99999, start="2024-01-01")
+except SerieNaoEncontrada:
+    print("Serie nao existe")
+except BacenTimeoutError:
+    print("API do BACEN nao respondeu")
+except BacenAPIError as e:
+    print(f"Erro {e.status_code}: {e.mensagem}")
+```
+
+## Desenvolvimento
+
+```bash
+git clone https://github.com/fmaignacio/bacendata.git
+cd bacendata
+python -m venv .venv
+source .venv/bin/activate  # Linux/Mac
+pip install -e ".[dev]"
+
+# Testes
+python -m pytest tests/ -v --cov=src/bacendata
+
+# Lint
+ruff check src/ tests/
+black src/ tests/
+```
+
+## Licenca
+
+MIT

bacendata-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bacendata"
+version = "0.1.0"
+description = "Acesso simplificado aos dados do Banco Central do Brasil"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "Felipe"},
+]
+keywords = ["bacen", "bcb", "sgs", "banco-central", "economia", "brasil"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pandas>=1.5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/fmaignacio/bacendata"
+Repository = "https://github.com/fmaignacio/bacendata"
+Issues = "https://github.com/fmaignacio/bacendata/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "pytest-cov>=4.0",
+    "ruff>=0.1.0",
+    "black>=23.0",
+    "respx>=0.20",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.black]
+target-version = ["py39"]
+line-length = 100

bacendata-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bacendata-0.1.0/src/bacendata/__init__.py

@@ -0,0 +1,12 @@
+"""
+BacenData — Acesso simplificado aos dados do Banco Central do Brasil.
+
+Uso rápido:
+    >>> from bacendata import sgs
+    >>> selic = sgs.get(11, start="2020-01-01")
+"""
+
+from bacendata.wrapper import bacen_sgs as sgs
+
+__version__ = "0.1.0"
+__all__ = ["sgs", "__version__"]