opendata-bcb 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. opendata_bcb-0.1.0/LICENSE +21 -0
  2. opendata_bcb-0.1.0/PKG-INFO +195 -0
  3. opendata_bcb-0.1.0/README.md +159 -0
  4. opendata_bcb-0.1.0/pyproject.toml +82 -0
  5. opendata_bcb-0.1.0/src/opendata_bcb/__init__.py +25 -0
  6. opendata_bcb-0.1.0/src/opendata_bcb/_internal/__init__.py +1 -0
  7. opendata_bcb-0.1.0/src/opendata_bcb/_internal/config/AGENTS.md +88 -0
  8. opendata_bcb-0.1.0/src/opendata_bcb/_internal/config/__init__.py +1 -0
  9. opendata_bcb-0.1.0/src/opendata_bcb/_internal/config/contracts/__init__.py +35 -0
  10. opendata_bcb-0.1.0/src/opendata_bcb/_internal/config/contracts/banks.py +27 -0
  11. opendata_bcb-0.1.0/src/opendata_bcb/_internal/config/contracts/currency_codes.py +27 -0
  12. opendata_bcb-0.1.0/src/opendata_bcb/_internal/config/contracts/ptax_usd_brl.py +19 -0
  13. opendata_bcb-0.1.0/src/opendata_bcb/_internal/config/contracts/quote_bulletins.py +19 -0
  14. opendata_bcb-0.1.0/src/opendata_bcb/_internal/config/ports/__init__.py +15 -0
  15. opendata_bcb-0.1.0/src/opendata_bcb/_internal/config/ports/olinda_reader_port.py +45 -0
  16. opendata_bcb-0.1.0/src/opendata_bcb/_internal/olinda.py +624 -0
  17. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/AGENTS.md +53 -0
  18. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/__init__.py +1 -0
  19. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/banks_frame.py +46 -0
  20. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/br_identifiers.py +27 -0
  21. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/currency_codes_frame.py +49 -0
  22. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/daily_cache.py +250 -0
  23. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/dates.py +145 -0
  24. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/dbapi.py +118 -0
  25. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/dtypes.py +319 -0
  26. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/http_downloader.py +286 -0
  27. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/logs.py +381 -0
  28. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/logs_emitter.py +62 -0
  29. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/provenance.py +183 -0
  30. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/quote_bulletins_frame.py +132 -0
  31. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/raw_workspace.py +72 -0
  32. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/records_frame.py +27 -0
  33. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/retry/__init__.py +28 -0
  34. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/retry/_schedule.py +78 -0
  35. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/retry/backoff.py +219 -0
  36. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/retry/log_emitter.py +55 -0
  37. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/retry/policy.py +105 -0
  38. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/schema_regimes.py +22 -0
  39. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/sgs_frames.py +41 -0
  40. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/sidecar_metadata.py +122 -0
  41. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/tabular_reader.py +852 -0
  42. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/text.py +78 -0
  43. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/typing/__init__.py +30 -0
  44. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/typing/abc_type_checker.py +16 -0
  45. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/typing/decorators.py +38 -0
  46. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/typing/policy.py +93 -0
  47. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/typing/protocol_type_checker.py +20 -0
  48. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/typing/type_checker.py +85 -0
  49. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/typing/validate.py +78 -0
  50. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/xml_reader.py +497 -0
  51. opendata_bcb-0.1.0/src/opendata_bcb/_internal/utils/zip_extractor.py +318 -0
  52. opendata_bcb-0.1.0/src/opendata_bcb/banks.py +88 -0
  53. opendata_bcb-0.1.0/src/opendata_bcb/currency_codes.py +200 -0
  54. opendata_bcb-0.1.0/src/opendata_bcb/main.py +12 -0
  55. opendata_bcb-0.1.0/src/opendata_bcb/py.typed +0 -0
  56. opendata_bcb-0.1.0/src/opendata_bcb/quote_bulletins.py +90 -0
  57. opendata_bcb-0.1.0/src/opendata_bcb/sgs.py +160 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 guilhermegor
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,195 @@
1
+ Metadata-Version: 2.4
2
+ Name: opendata-bcb
3
+ Version: 0.1.0
4
+ Summary: Pacote Python para coletar dados do Banco Central do Brasil (SGS, Olinda/PTAX, Focus, boletins de cotações, cadastro de bancos), com cache e proveniência.
5
+ License: MIT
6
+ License-File: LICENSE
7
+ Keywords: opendata-bcb,python,library
8
+ Author: guilhermegor
9
+ Requires-Python: >=3.11,<4.0
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Programming Language :: Python :: 3.15
20
+ Classifier: Topic :: Software Development :: Libraries
21
+ Requires-Dist: beartype (>=0.22)
22
+ Requires-Dist: defusedxml (>=0.7)
23
+ Requires-Dist: numpy (>=1.22)
24
+ Requires-Dist: openpyxl (>=3.1.0)
25
+ Requires-Dist: pandas (>=2.1.0)
26
+ Requires-Dist: pure-schema-regimes (>=0.1.0,<0.2)
27
+ Requires-Dist: purecalendars (>=3.0.1)
28
+ Requires-Dist: purepii-br (>=2.0.0)
29
+ Project-URL: Bug Reports, https://github.com/guilhermegor/opendata-bcb/issues
30
+ Project-URL: Documentation, https://guilhermegor.github.io/opendata-bcb/
31
+ Project-URL: Homepage, https://guilhermegor.github.io/opendata-bcb/
32
+ Project-URL: Repository, https://github.com/guilhermegor/opendata-bcb
33
+ Project-URL: Source, https://github.com/guilhermegor/opendata-bcb
34
+ Description-Content-Type: text/markdown
35
+
36
+ <!-- readme-archetype: library -->
37
+ # opendata-bcb
38
+
39
+ <p align="center"><img src="https://raw.githubusercontent.com/guilhermegor/opendata-bcb/main/docs/assets/logo.png" width="200" alt="opendata-bcb logo"></p>
40
+
41
+ [![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
42
+ ![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)
43
+ [![PyPI](https://img.shields.io/pypi/v/opendata-bcb.svg)](https://pypi.org/project/opendata-bcb/)
44
+ [![Downloads](https://img.shields.io/pepy/dt/opendata-bcb)](https://pepy.tech/projects/opendata-bcb)
45
+ [![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://guilhermegor.github.io/opendata-bcb/)
46
+ [![Linting](https://img.shields.io/badge/linting-ruff_%7C_codespell-blue)](https://github.com/astral-sh/ruff)
47
+ [![Mypy](https://img.shields.io/badge/type--checked-mypy-blue)](https://mypy-lang.org)
48
+ ![Test Coverage](https://raw.githubusercontent.com/guilhermegor/opendata-bcb/badges/coverage.svg)
49
+ ![License](https://img.shields.io/badge/license-MIT-green.svg)
50
+ ![Open Issues](https://img.shields.io/github/issues/guilhermegor/opendata-bcb)
51
+ ![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-darkgreen.svg)
52
+
53
+ <!-- slug: overview -->
54
+ ## Visão geral
55
+
56
+ Pacote Python para coletar dados do Banco Central do Brasil (SGS, Olinda/PTAX, Focus, boletins de cotações, cadastro de bancos), com cache e proveniência.
57
+
58
+ <!-- optional section: delete it when the project has no feature list -->
59
+ <!-- slug: features -->
60
+ ## Funcionalidades
61
+
62
+ - `read_banks`: participantes do STR (Sistema de Transferência de Reservas) do BCB.
63
+ - `read_sgs_series`: séries temporais do SGS, com valores em `Decimal`.
64
+ - `read_currency_codes`: tabela de códigos de moeda da PTAX, com a data de exclusão e `is_active`.
65
+
66
+ Todo leitor guarda o arquivo em cache por dia e devolve as colunas de proveniência. Assinaturas e
67
+ colunas em [docs/api/reference.md](docs/api/reference.md).
68
+
69
+ <!-- slug: documentation -->
70
+ ## Documentação
71
+
72
+ O site de documentação fica em https://guilhermegor.github.io/opendata-bcb/. Para servi-lo localmente, rode `poetry run poe docs_serve`.
73
+
74
+ <!-- slug: getting-started -->
75
+ ## Primeiros passos
76
+
77
+ O Python 3.11+ é o único pré-requisito; o `bin/venv.sh` instala o [Poetry](https://python-poetry.org/) quando ele estiver ausente.
78
+
79
+ <!-- slug: install -->
80
+ ### Instalação
81
+
82
+ #### Como dependência
83
+
84
+ ```bash
85
+ pip install opendata-bcb
86
+ poetry add opendata-bcb
87
+ ```
88
+
89
+ Estes comandos funcionam depois que a primeira versão for publicada no PyPI.
90
+
91
+ #### Para desenvolver
92
+
93
+ ```bash
94
+ git clone https://github.com/guilhermegor/opendata-bcb.git
95
+ cd opendata-bcb
96
+ bash bin/venv.sh
97
+ poetry run poe init
98
+ ```
99
+
100
+ O `poe` vive dentro do virtualenv, então o `bin/venv.sh` o cria primeiro; em seguida o
101
+ `poetry run poe init` o executa sem ativar nada. Se o `poetry` não estiver no `PATH` (por exemplo
102
+ logo depois de o `bin/venv.sh` instalá-lo com `--user`), use `bash bin/poe_exec.sh init`, que
103
+ encontra o `poe` do venv sozinho. Atrás de um proxy com inspeção TLS e com `bin/corporate_ca.pem`
104
+ no lugar, rode o `init` por `bash bin/poe_exec.sh init`, para que o bundle de CAs seja usado nos downloads.
105
+
106
+ <!-- slug: usage -->
107
+ ### Uso
108
+
109
+ Rode o projeto pelos pontos de entrada em `src/`; troque este parágrafo pelos comandos que as
110
+ pessoas usuárias executam primeiro.
111
+
112
+ <!-- slug: project-structure -->
113
+ ## Estrutura do projeto
114
+
115
+ ```text
116
+ opendata-bcb/
117
+ ├── .github/ workflows, CODEOWNERS e template de PR
118
+ ├── .specs/ specs de funcionalidades e trackers de backlog
119
+ ├── bin/ scripts de gate e utilitários
120
+ ├── docs/ documentação publicada
121
+ ├── src/ código da aplicação
122
+ ├── tests/
123
+ │ ├── unit/
124
+ │ └── integration/
125
+ ├── pyproject.toml
126
+ └── poe_tasks.toml pontos de entrada do task runner
127
+ ```
128
+
129
+ <!-- slug: development -->
130
+ ## Desenvolvimento
131
+
132
+ Depois do bootstrap descrito em Instalação, qualquer tarefa pode ser executada com
133
+ `poetry run poe <task>`; e `poetry run poe` sem tarefa lista todas elas.
134
+
135
+ ```bash
136
+ poetry run poe unit_tests
137
+ poetry run poe integration_tests
138
+ ```
139
+
140
+ Quando o deploy da documentação do primeiro release tiver criado a branch `gh-pages`, rode
141
+ `poetry run poe enable_pages` uma vez: até que essa branch exista, o `init` deixa o Pages intocado.
142
+
143
+ ### `poetry run poe` ou `bash bin/poe_exec.sh`?
144
+
145
+ Os dois rodam a mesma tarefa do mesmo `poe` do venv. Use `poetry run poe`, o comando que a
146
+ comunidade conhece; o `bin/poe_exec.sh` cobre os casos em que ele não basta:
147
+
148
+ | Situação | `poetry run poe` | `bash bin/poe_exec.sh` |
149
+ |---|---|---|
150
+ | Máquina comum, `poetry` no `PATH` | funciona | funciona |
151
+ | `poetry` fora do `PATH` (ex.: recém-instalado com `--user` pelo `bin/venv.sh`) | falha: `poetry: command not found` | funciona: acha `.venv/bin/poe` (ou `.venv/Scripts/poe.exe` no Windows) sem o `poetry` |
152
+ | Rede corporativa com inspeção TLS (`bin/corporate_ca.pem` presente) | tarefas que baixam algo podem falhar com erro de certificado | funciona: monta o bundle de CAs e exporta `REQUESTS_CA_BUNDLE`, `SSL_CERT_FILE`, `CURL_CA_BUNDLE` e `PIP_CERT` antes de rodar a tarefa |
153
+ | `poe` não instalado | erro genérico do Poetry | lista as formas de instalar (`bin/venv.sh`, `pipx`, plugin do Poetry) |
154
+
155
+ <!-- slug: public-api -->
156
+ ## API pública
157
+
158
+ A superfície pública é o que o `__init__.py` do pacote lista em `__all__`; tudo o que está em
159
+ `_internal/` é privado.
160
+
161
+ <!-- slug: publishing -->
162
+ ## Publicação
163
+
164
+ Os lançamentos saem dos workflows de release em `.github/workflows/`; a tag do git é a versão.
165
+
166
+ O caminho da 0.x até a 1.0.0, e o gate de lançamento que o protege, está em
167
+ [docs/releasing-1-0-0.md](docs/releasing-1-0-0.md).
168
+
169
+ <!-- slug: contributing -->
170
+ ## Contribuindo
171
+
172
+ Veja o [CONTRIBUTING.md](CONTRIBUTING.md) para as regras de branch, commit e revisão.
173
+
174
+ <!-- slug: license -->
175
+ ## Licença
176
+
177
+ Este projeto é licenciado sob MIT; veja [LICENSE](LICENSE).
178
+
179
+ <!-- slug: authors -->
180
+ ## Autores
181
+
182
+ - guilhermegor — [GitHub](https://github.com/guilhermegor) | [LinkedIn](https://www.linkedin.com/in/guilhermegor/)
183
+
184
+ <!-- slug: useful-links -->
185
+ ## Links úteis
186
+
187
+ - [Repositório no GitHub](https://github.com/guilhermegor/opendata-bcb)
188
+ - [Issue Tracker](https://github.com/guilhermegor/opendata-bcb/issues)
189
+ - [Documentação](https://guilhermegor.github.io/opendata-bcb/)
190
+
191
+ ---
192
+
193
+ <sub>Gerado a partir do template lib-minimal via [BlueprintX](https://github.com/guilhermegor/blueprintx). Pacote não oficial, sem afiliação com o Banco Central do Brasil; apenas consome dados que o BCB publica abertamente. Foto do logo: sede do BCB em Brasília, por [Matheus Natan](https://www.pexels.com/@matheusnatan/) no Pexels.</sub>
194
+ <!-- add any project disclaimer inside the sub tag above; for a library wrapping a third party, e.g. "Unofficial, community library. Not affiliated with or endorsed by ORG_NAME." -->
195
+
@@ -0,0 +1,159 @@
1
+ <!-- readme-archetype: library -->
2
+ # opendata-bcb
3
+
4
+ <p align="center"><img src="https://raw.githubusercontent.com/guilhermegor/opendata-bcb/main/docs/assets/logo.png" width="200" alt="opendata-bcb logo"></p>
5
+
6
+ [![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
7
+ ![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)
8
+ [![PyPI](https://img.shields.io/pypi/v/opendata-bcb.svg)](https://pypi.org/project/opendata-bcb/)
9
+ [![Downloads](https://img.shields.io/pepy/dt/opendata-bcb)](https://pepy.tech/projects/opendata-bcb)
10
+ [![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://guilhermegor.github.io/opendata-bcb/)
11
+ [![Linting](https://img.shields.io/badge/linting-ruff_%7C_codespell-blue)](https://github.com/astral-sh/ruff)
12
+ [![Mypy](https://img.shields.io/badge/type--checked-mypy-blue)](https://mypy-lang.org)
13
+ ![Test Coverage](https://raw.githubusercontent.com/guilhermegor/opendata-bcb/badges/coverage.svg)
14
+ ![License](https://img.shields.io/badge/license-MIT-green.svg)
15
+ ![Open Issues](https://img.shields.io/github/issues/guilhermegor/opendata-bcb)
16
+ ![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-darkgreen.svg)
17
+
18
+ <!-- slug: overview -->
19
+ ## Visão geral
20
+
21
+ Pacote Python para coletar dados do Banco Central do Brasil (SGS, Olinda/PTAX, Focus, boletins de cotações, cadastro de bancos), com cache e proveniência.
22
+
23
+ <!-- optional section: delete it when the project has no feature list -->
24
+ <!-- slug: features -->
25
+ ## Funcionalidades
26
+
27
+ - `read_banks`: participantes do STR (Sistema de Transferência de Reservas) do BCB.
28
+ - `read_sgs_series`: séries temporais do SGS, com valores em `Decimal`.
29
+ - `read_currency_codes`: tabela de códigos de moeda da PTAX, com a data de exclusão e `is_active`.
30
+
31
+ Todo leitor guarda o arquivo em cache por dia e devolve as colunas de proveniência. Assinaturas e
32
+ colunas em [docs/api/reference.md](docs/api/reference.md).
33
+
34
+ <!-- slug: documentation -->
35
+ ## Documentação
36
+
37
+ O site de documentação fica em https://guilhermegor.github.io/opendata-bcb/. Para servi-lo localmente, rode `poetry run poe docs_serve`.
38
+
39
+ <!-- slug: getting-started -->
40
+ ## Primeiros passos
41
+
42
+ O Python 3.11+ é o único pré-requisito; o `bin/venv.sh` instala o [Poetry](https://python-poetry.org/) quando ele estiver ausente.
43
+
44
+ <!-- slug: install -->
45
+ ### Instalação
46
+
47
+ #### Como dependência
48
+
49
+ ```bash
50
+ pip install opendata-bcb
51
+ poetry add opendata-bcb
52
+ ```
53
+
54
+ Estes comandos funcionam depois que a primeira versão for publicada no PyPI.
55
+
56
+ #### Para desenvolver
57
+
58
+ ```bash
59
+ git clone https://github.com/guilhermegor/opendata-bcb.git
60
+ cd opendata-bcb
61
+ bash bin/venv.sh
62
+ poetry run poe init
63
+ ```
64
+
65
+ O `poe` vive dentro do virtualenv, então o `bin/venv.sh` o cria primeiro; em seguida o
66
+ `poetry run poe init` o executa sem ativar nada. Se o `poetry` não estiver no `PATH` (por exemplo
67
+ logo depois de o `bin/venv.sh` instalá-lo com `--user`), use `bash bin/poe_exec.sh init`, que
68
+ encontra o `poe` do venv sozinho. Atrás de um proxy com inspeção TLS e com `bin/corporate_ca.pem`
69
+ no lugar, rode o `init` por `bash bin/poe_exec.sh init`, para que o bundle de CAs seja usado nos downloads.
70
+
71
+ <!-- slug: usage -->
72
+ ### Uso
73
+
74
+ Rode o projeto pelos pontos de entrada em `src/`; troque este parágrafo pelos comandos que as
75
+ pessoas usuárias executam primeiro.
76
+
77
+ <!-- slug: project-structure -->
78
+ ## Estrutura do projeto
79
+
80
+ ```text
81
+ opendata-bcb/
82
+ ├── .github/ workflows, CODEOWNERS e template de PR
83
+ ├── .specs/ specs de funcionalidades e trackers de backlog
84
+ ├── bin/ scripts de gate e utilitários
85
+ ├── docs/ documentação publicada
86
+ ├── src/ código da aplicação
87
+ ├── tests/
88
+ │ ├── unit/
89
+ │ └── integration/
90
+ ├── pyproject.toml
91
+ └── poe_tasks.toml pontos de entrada do task runner
92
+ ```
93
+
94
+ <!-- slug: development -->
95
+ ## Desenvolvimento
96
+
97
+ Depois do bootstrap descrito em Instalação, qualquer tarefa pode ser executada com
98
+ `poetry run poe <task>`; e `poetry run poe` sem tarefa lista todas elas.
99
+
100
+ ```bash
101
+ poetry run poe unit_tests
102
+ poetry run poe integration_tests
103
+ ```
104
+
105
+ Quando o deploy da documentação do primeiro release tiver criado a branch `gh-pages`, rode
106
+ `poetry run poe enable_pages` uma vez: até que essa branch exista, o `init` deixa o Pages intocado.
107
+
108
+ ### `poetry run poe` ou `bash bin/poe_exec.sh`?
109
+
110
+ Os dois rodam a mesma tarefa do mesmo `poe` do venv. Use `poetry run poe`, o comando que a
111
+ comunidade conhece; o `bin/poe_exec.sh` cobre os casos em que ele não basta:
112
+
113
+ | Situação | `poetry run poe` | `bash bin/poe_exec.sh` |
114
+ |---|---|---|
115
+ | Máquina comum, `poetry` no `PATH` | funciona | funciona |
116
+ | `poetry` fora do `PATH` (ex.: recém-instalado com `--user` pelo `bin/venv.sh`) | falha: `poetry: command not found` | funciona: acha `.venv/bin/poe` (ou `.venv/Scripts/poe.exe` no Windows) sem o `poetry` |
117
+ | Rede corporativa com inspeção TLS (`bin/corporate_ca.pem` presente) | tarefas que baixam algo podem falhar com erro de certificado | funciona: monta o bundle de CAs e exporta `REQUESTS_CA_BUNDLE`, `SSL_CERT_FILE`, `CURL_CA_BUNDLE` e `PIP_CERT` antes de rodar a tarefa |
118
+ | `poe` não instalado | erro genérico do Poetry | lista as formas de instalar (`bin/venv.sh`, `pipx`, plugin do Poetry) |
119
+
120
+ <!-- slug: public-api -->
121
+ ## API pública
122
+
123
+ A superfície pública é o que o `__init__.py` do pacote lista em `__all__`; tudo o que está em
124
+ `_internal/` é privado.
125
+
126
+ <!-- slug: publishing -->
127
+ ## Publicação
128
+
129
+ Os lançamentos saem dos workflows de release em `.github/workflows/`; a tag do git é a versão.
130
+
131
+ O caminho da 0.x até a 1.0.0, e o gate de lançamento que o protege, está em
132
+ [docs/releasing-1-0-0.md](docs/releasing-1-0-0.md).
133
+
134
+ <!-- slug: contributing -->
135
+ ## Contribuindo
136
+
137
+ Veja o [CONTRIBUTING.md](CONTRIBUTING.md) para as regras de branch, commit e revisão.
138
+
139
+ <!-- slug: license -->
140
+ ## Licença
141
+
142
+ Este projeto é licenciado sob MIT; veja [LICENSE](LICENSE).
143
+
144
+ <!-- slug: authors -->
145
+ ## Autores
146
+
147
+ - guilhermegor — [GitHub](https://github.com/guilhermegor) | [LinkedIn](https://www.linkedin.com/in/guilhermegor/)
148
+
149
+ <!-- slug: useful-links -->
150
+ ## Links úteis
151
+
152
+ - [Repositório no GitHub](https://github.com/guilhermegor/opendata-bcb)
153
+ - [Issue Tracker](https://github.com/guilhermegor/opendata-bcb/issues)
154
+ - [Documentação](https://guilhermegor.github.io/opendata-bcb/)
155
+
156
+ ---
157
+
158
+ <sub>Gerado a partir do template lib-minimal via [BlueprintX](https://github.com/guilhermegor/blueprintx). Pacote não oficial, sem afiliação com o Banco Central do Brasil; apenas consome dados que o BCB publica abertamente. Foto do logo: sede do BCB em Brasília, por [Matheus Natan](https://www.pexels.com/@matheusnatan/) no Pexels.</sub>
159
+ <!-- add any project disclaimer inside the sub tag above; for a library wrapping a third party, e.g. "Unofficial, community library. Not affiliated with or endorsed by ORG_NAME." -->
@@ -0,0 +1,82 @@
1
+ [tool.poetry]
2
+ name = "opendata-bcb"
3
+ version = "0.1.0" # set from the git tag, see docs/contributing.md#releasing
4
+ description = "Pacote Python para coletar dados do Banco Central do Brasil (SGS, Olinda/PTAX, Focus, boletins de cotações, cadastro de bancos), com cache e proveniência."
5
+ authors = ["guilhermegor"]
6
+ readme = "README.md"
7
+ license = "MIT"
8
+ homepage = "https://guilhermegor.github.io/opendata-bcb/"
9
+ documentation = "https://guilhermegor.github.io/opendata-bcb/"
10
+ repository = "https://github.com/guilhermegor/opendata-bcb"
11
+ keywords = ["opendata-bcb", "python", "library"]
12
+ packages = [{ include = "opendata_bcb", from = "src" }]
13
+ exclude = ["src/**/CLAUDE.md"]
14
+ package-mode = true
15
+ classifiers = [
16
+ "Programming Language :: Python :: 3",
17
+ "Programming Language :: Python :: 3.11",
18
+ "Programming Language :: Python :: 3.12",
19
+ "Programming Language :: Python :: 3.13",
20
+ "Programming Language :: Python :: 3.14",
21
+ "Operating System :: OS Independent",
22
+ "License :: OSI Approved :: MIT License",
23
+ "Development Status :: 3 - Alpha",
24
+ "Intended Audience :: Developers",
25
+ "Topic :: Software Development :: Libraries",
26
+ ]
27
+
28
+ [tool.poetry.urls]
29
+ "Bug Reports" = "https://github.com/guilhermegor/opendata-bcb/issues"
30
+ "Source" = "https://github.com/guilhermegor/opendata-bcb"
31
+ "Documentation" = "https://guilhermegor.github.io/opendata-bcb/"
32
+
33
+ [tool.poetry.dependencies]
34
+ python = ">=3.11,<4.0"
35
+ beartype = ">=0.22"
36
+ pandas = ">=2.1.0"
37
+ numpy = ">=1.22"
38
+ purecalendars = ">=3.0.1"
39
+ openpyxl = ">=3.1.0"
40
+ defusedxml = ">=0.7"
41
+ purepii-br = ">=2.0.0"
42
+ pure-schema-regimes = ">=0.1.0,<0.2"
43
+
44
+ [tool.poetry.group.dev.dependencies]
45
+ poethepoet = ">=0.35"
46
+ pre-commit = ">=4.1.0"
47
+ pretty-errors = ">=1.2.25"
48
+ commitizen = ">=4.4.1"
49
+ build = ">=1.2.2"
50
+ twine = ">=6.1.0"
51
+ ruff = ">=0.17.5"
52
+ codespell = ">=2.4.1"
53
+ pydocstyle = ">=6.3.0"
54
+ pytest = ">=8.0.0"
55
+ pytest-cov = ">=6.0.0"
56
+ pytest-randomly = ">=3.15.0"
57
+ coverage = ">=7.6.0"
58
+ genbadge = {extras = ["coverage"], version = ">=1.1.0"}
59
+ mypy = ">=1.8.0"
60
+ sqlfluff = ">=3.0.0"
61
+ yamllint = ">=1.35.0"
62
+ shfmt-py = ">=3.7.0"
63
+ shellcheck-py = ">=0.10.0"
64
+ deptry = ">=0.20"
65
+
66
+ [tool.poetry.group.docs.dependencies]
67
+ mkdocs = ">=1.6.0"
68
+ mkdocs-material = ">=9.5.0"
69
+ pymdown-extensions = ">=10.0"
70
+ mike = ">=2.1.0"
71
+
72
+ [tool.deptry.per_rule_ignores]
73
+ DEP002 = ["openpyxl"]
74
+
75
+ [tool.poetry-dynamic-versioning]
76
+ enable = false
77
+ vcs = "git"
78
+ style = "pep440"
79
+
80
+ [build-system]
81
+ requires = ["poetry-core>=1.7.0", "poetry-dynamic-versioning>=1.4.0,<2.0.0"]
82
+ build-backend = "poetry_dynamic_versioning.backend"
@@ -0,0 +1,25 @@
1
+ """opendata-bcb package."""
2
+
3
+ from importlib.metadata import PackageNotFoundError, version
4
+
5
+ from .banks import read_banks
6
+ from .currency_codes import read_currency_codes
7
+ from .main import main
8
+ from .quote_bulletins import read_quote_bulletin_codes
9
+ from .sgs import read_sgs_series
10
+
11
+
12
+ try:
13
+ __version__ = version("opendata-bcb")
14
+ except PackageNotFoundError: # pragma: no cover - source tree without an installed dist
15
+ __version__ = "0.0.0"
16
+
17
+
18
+ __all__ = [
19
+ "__version__",
20
+ "main",
21
+ "read_banks",
22
+ "read_currency_codes",
23
+ "read_quote_bulletin_codes",
24
+ "read_sgs_series",
25
+ ]
@@ -0,0 +1 @@
1
+ """Private internals of the opendata_bcb package (not a public API)."""
@@ -0,0 +1,88 @@
1
+ # AGENTS.md — `_internal/config/`
2
+
3
+ `config/` is the home of **every private structural declaration** — the shapes and
4
+ interfaces the library conforms to. It holds three sub-packages, all under `_internal/`
5
+ (they ship inside the wheel but are **not part of the public API** — consumers import the
6
+ library's core, never `_internal`):
7
+
8
+ | Sub-package | Declares | Ships |
9
+ |-------------|----------|-------|
10
+ | `contracts/` | `FileContract` — the columns an input file must carry | always (drop if the library never reads tabular inputs) |
11
+ | `ports/` | private behavioural ABCs (the hexagonal *ports*) | **opt-in** — only when two macro-sections share an operation |
12
+ | `schemas/` | direction-neutral Pydantic models, one per external standard | **opt-in** — same condition as `ports/`, or the models are the library's product |
13
+
14
+ The organising split is **declaration vs machinery**: `config/` answers "*what shape /
15
+ interface must this conform to?*"; `_internal/utils/` answers "*how is it done?*" (the engines:
16
+ `tabular_reader`, `dtypes`, `typing/`). A `ports/` ABC is a behavioural contract rather than a
17
+ pure data declaration, but it still declares a *contract to conform to*, so it lives here beside
18
+ `contracts/`, **not** in `utils/`.
19
+
20
+ ⚠️ `ports/` and `schemas/` are an **opt-in tier** — a single-purpose library should carry
21
+ **neither** (an interface with one implementation is over-abstraction). This starter ships a
22
+ reference `ports/` seam to copy; delete it (and never add `schemas/`) unless the library really
23
+ grows two macro-sections over a shared domain — or, for `schemas/` only, its product is the
24
+ models themselves.
25
+
26
+ ## The `contracts/` sub-package
27
+
28
+ A `FileContract` declares the shape an input file (or SQL result) must have: which columns
29
+ must be present (`tuple_required`) and which must hold at least one valid CNPJ
30
+ (`tuple_cnpj_cols`). It is a **declaration**, not a validator — the validation engine lives
31
+ in `_internal/utils/tabular_reader.py` (`read_table` / `read_query` raise `ContractError`
32
+ on a violation before types are applied).
33
+
34
+ - **One contract per file** (`cadastro.py`, `orders.py`, …): a module docstring plus a
35
+ single `FileContract` constant. New input → new file.
36
+ - `contracts/__init__.py` re-exports every contract **and** the machinery
37
+ (`FileContract`, `find_file_problems` from `_internal.utils.tabular_reader`), so callers
38
+ use one import: `from <pkg>._internal.config.contracts import PTAX_USD_BRL`.
39
+ - A contract that constrains nothing is still explicit: `FileContract(name, key, (), ())`.
40
+ - **`contracts/` is the ONLY place a `FileContract` is constructed** — statically enforced
41
+ by ruff (`TID251`). Loaders import the instances; they never build one inline.
42
+
43
+ `PTAX_USD_BRL` (`ptax_usd_brl.py`) is the first real contract — copy it per new source.
44
+
45
+ ## The `ports/` sub-package (opt-in)
46
+
47
+ Private behavioural interfaces — the **ports** of hexagonal *ports-and-adapters*. Everything
48
+ here is an **abstract contract**, not an implementation; consumers import the concrete adapters,
49
+ never `_internal.config.ports`.
50
+
51
+ A **port** is the abstract operation a family of concrete classes (the **adapters**) all
52
+ implement, so callers treat any adapter polymorphically and every new variant conforms to the
53
+ same shape. When two macro-sections share one operation (e.g. an `export`, a `read`), name that
54
+ operation as a port here; the concrete classes are the adapters.
55
+
56
+ - **One port per file** (`olinda_reader_port.py`, `submission_writer.py`, …): a module docstring plus
57
+ a single ABC. New shared operation → new file.
58
+ - **`metaclass=ABCTypeCheckerMeta`** on the port gives both abstract-method enforcement (a
59
+ partial adapter fails at instantiation) and runtime type checking of every call.
60
+ - **Adapters inherit the port and its metaclass** — never redeclare `metaclass` on a subclass;
61
+ Python inherits it (the `check_typing` hook already skips a class with bases for that reason).
62
+ - **Generic over its value** (`Generic[T]`) when adapters differ in the value type: an adapter
63
+ narrows it through the type parameter rather than by re-annotating the override, keeping the
64
+ concrete signature Liskov-compatible.
65
+ - `ports/__init__.py` re-exports every port so callers use one import:
66
+ `from <pkg>._internal.config.ports import OlindaReaderPort`.
67
+ - Ports stay **private** — never add one to the library's public `__all__`.
68
+
69
+ `OlindaReaderPort` is the first real port — every Olinda-backed reader implements it.
70
+
71
+ ## `schemas/` vs `contracts/` — the boundary people get wrong
72
+
73
+ If you add `schemas/` (opt-in), keep the distinction sharp: a **schema** is a Pydantic model
74
+ that mirrors an external **standard** (e.g. the submission XML your library emits) — **schema ↔
75
+ structured document**. A **`FileContract`** describes a flat **tabular dump** an ingestion
76
+ reader consumes (an open-data CSV of the *same* standard) — **`FileContract` ↔ flat table**. So a
77
+ reader that consumes a *different artifact* of a standard your schema already models declares its
78
+ **own `FileContract`**; it does **not** reuse the schema. Same domain, two artifacts, two
79
+ declarations — both living here under `config/`.
80
+
81
+ ## Consumer-built models still live in `schemas/`
82
+
83
+ When consumers **construct** the models (the library's product is the schema), they stay in
84
+ `_internal/config/schemas/`; do not promote them to a public `schemas/` package. Re-export each
85
+ class from the package's top-level `__all__`: consumers only ever write
86
+ `from <pkg> import X`, so the file location is an implementation detail. Accepted cost: the
87
+ class's `__module__` (tracebacks, mkdocstrings paths, pickles) shows the `_internal` path, so
88
+ moving the file later is a pickle-compatibility change.
@@ -0,0 +1 @@
1
+ """Private configuration internals (data contracts) of opendata_bcb."""
@@ -0,0 +1,35 @@
1
+ """Data contracts for the project's input sources (config layer).
2
+
3
+ A contract is **declarative configuration** of a source's expected shape — which columns it
4
+ must carry — *not* data access. Convention: **one file per source** under this package, each
5
+ defining a single ``FileContract`` instance; this aggregator re-exports them (plus the
6
+ machinery from ``utils.tabular_reader``) so callers import from one place:
7
+ ``from opendata_bcb._internal.config.contracts import PTAX_USD_BRL, find_contract_problems``.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from opendata_bcb._internal.config.contracts.banks import CONTRACT_BANKS
13
+ from opendata_bcb._internal.config.contracts.currency_codes import CONTRACT_CURRENCY_CODES
14
+ from opendata_bcb._internal.config.contracts.ptax_usd_brl import PTAX_USD_BRL
15
+ from opendata_bcb._internal.config.contracts.quote_bulletins import (
16
+ CONTRACT_QUOTE_BULLETIN_CODES,
17
+ )
18
+ from opendata_bcb._internal.utils.tabular_reader import (
19
+ ContractError,
20
+ FileContract, # noqa: TID251 -- contracts are constructed here
21
+ find_contract_problems,
22
+ find_file_problems,
23
+ )
24
+
25
+
26
+ __all__ = [
27
+ "CONTRACT_BANKS",
28
+ "CONTRACT_CURRENCY_CODES",
29
+ "CONTRACT_QUOTE_BULLETIN_CODES",
30
+ "ContractError",
31
+ "FileContract",
32
+ "find_contract_problems",
33
+ "find_file_problems",
34
+ "PTAX_USD_BRL",
35
+ ]
@@ -0,0 +1,27 @@
1
+ """Data contract for the BCB STR participants list (the bank registry CSV).
2
+
3
+ Subset contract: the keys the reader depends on must be present; a column the source adds
4
+ later flows through untouched rather than failing the read.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from opendata_bcb._internal.utils.tabular_reader import (
10
+ FileContract, # noqa: TID251 -- contracts are constructed here
11
+ )
12
+
13
+
14
+ CONTRACT_BANKS = FileContract(
15
+ "BCB STR participants",
16
+ "bcb_banks",
17
+ (
18
+ "ISPB",
19
+ "Nome_Reduzido",
20
+ "Número_Código",
21
+ "Participa_da_Compe",
22
+ "Acesso_Principal",
23
+ "Nome_Extenso",
24
+ "Início_da_Operação",
25
+ ),
26
+ (),
27
+ )
@@ -0,0 +1,27 @@
1
+ """Data contract for the BCB PTAX currency code table (the dated ``M<yyyymmdd>.csv``).
2
+
3
+ Subset contract: the keys the reader depends on must be present; a column the source adds
4
+ later flows through untouched rather than failing the read.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from opendata_bcb._internal.utils.tabular_reader import (
10
+ FileContract, # noqa: TID251 -- contracts are constructed here
11
+ )
12
+
13
+
14
+ CONTRACT_CURRENCY_CODES = FileContract(
15
+ "BCB PTAX currency codes",
16
+ "bcb_currency_codes",
17
+ (
18
+ "Código",
19
+ "Nome",
20
+ "Simbolo",
21
+ "Código País",
22
+ "País",
23
+ "Tipo",
24
+ "Data Exclusão PTAX",
25
+ ),
26
+ (),
27
+ )