dadosb3 0.1.0__tar.gz

dadosb3-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Lemon Tech (Dados B3)
+
+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.

dadosb3-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: dadosb3
+Version: 0.1.0
+Summary: Cliente Python da API Dados B3: fundamentos auditáveis de ações, FIIs e ETFs da bolsa brasileira (CVM/B3), com metodologia pública.
+Author-email: Dados B3 <contato@dadosb3.com>
+License-Expression: MIT
+Project-URL: Homepage, https://dadosb3.com
+Project-URL: Documentation, https://dadosb3.com/api
+Project-URL: Methodology, https://dadosb3.com/metodologia
+Project-URL: MCP connector, https://github.com/Val7h/dados-b3-mcp
+Keywords: b3,bovespa,cvm,fundamentos,ações,fii,etf,brasil,finance,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24
+Dynamic: license-file
+
+# dadosb3
+
+Cliente Python da [API Dados B3](https://dadosb3.com): fundamentos **auditáveis**
+das companhias abertas brasileiras (2010–hoje), fundos imobiliários (FIIs) e
+ETFs, com metodologia pública. Cada número carrega a conta CVM de origem; os
+múltiplos são ponto-no-tempo (preço do 1º pregão a partir da chegada do balanço
+à CVM); nada é publicado sem a bateria de invariantes passar.
+
+```bash
+pip install dadosb3
+```
+
+```python
+from dadosb3 import DadosB3
+
+api = DadosB3()                        # sem chave: WEGE3, BOVA11, MXRF11, rankings de ETF, /hoje, /saude
+api.indicadores("WEGE3")["anos"]       # ROE, ROIC, margens... com a conta CVM de cada número
+api.multiplos("WEGE3")                 # P/L, P/VP, EV/EBITDA ponto-no-tempo
+api.etf("BOVA11")                      # cota diária, ágio/deságio, taxa efetiva, carteira
+api.auditar_amostra(semente=4242)      # sorteie a SUA amostra e confira contra a CVM
+
+api = DadosB3(chave="sua-chave")       # ou DADOS_B3_API_KEY no ambiente
+api.screener(roic_min=0.15, dl_ebitda_max=2, ano=2024)
+api.fiis_screener(pvp_max=0.9, dy_min=0.10)
+```
+
+Chave grátis (200 consultas/dia, sem cartão) ou Pro em
+[dadosb3.com/assinar](https://dadosb3.com/assinar). Documentação da API em
+[dadosb3.com/api](https://dadosb3.com/api); metodologia em
+[dadosb3.com/metodologia](https://dadosb3.com/metodologia); para quem é (e para
+quem não é) em [dadosb3.com/para-quem](https://dadosb3.com/para-quem).
+
+## Métodos
+
+| Método | Rota | Chave? |
+|---|---|---|
+| `empresas()` | `/empresas` | não |
+| `indicadores(t)`, `multiplos(t)`, `fatos(t)`, `dividendos(t)`, `scores(t)`, `reapresentacoes(t)`, `trimestres(t)` | `/empresas/{t}/...` | WEGE3 não; demais sim |
+| `screener(ano=, **faixas)` | `/screener` | sim |
+| `fii(t)` | `/fiis/{t}` | MXRF11 não; demais sim |
+| `fiis_ranking()`, `fiis_screener(**faixas)` | `/fiis`, `/fiis/screener` | sim |
+| `etfs_ranking()` | `/etfs` | não |
+| `etf(t)` | `/etfs/{t}` | BOVA11 não; demais sim |
+| `hoje()`, `saude()`, `dicionario()` | `/hoje`, `/saude`, `/dicionario` | não |
+| `auditar_amostra(semente, n=25)` | `/auditoria/amostra/{semente}/{n}` | não |
+
+Erros: `ChaveNecessaria` (401), `NaoEncontrado` (404), `ErroDadosB3` (demais),
+todos com `.status` e `.detalhe` (o corpo da resposta da API).
+
+## Limites, ditos antes
+
+Preço só de fim de dia (COTAHIST); sem tratamento de viés de sobrevivência
+(companhia que saiu da bolsa não está na base); sem composição histórica de
+índice; a base começa em 2010. A lista completa está em
+[dadosb3.com/o-que-nao-resolvemos](https://dadosb3.com/o-que-nao-resolvemos).
+
+Não é recomendação de investimento. Fontes: CVM (dados abertos, ODbL) e B3
+(COTAHIST). Projeto independente, não afiliado à B3 nem à CVM. Licença deste
+cliente: MIT. Conector MCP: [Val7h/dados-b3-mcp](https://github.com/Val7h/dados-b3-mcp).

dadosb3-0.1.0/README.md

@@ -0,0 +1,59 @@
+# dadosb3
+
+Cliente Python da [API Dados B3](https://dadosb3.com): fundamentos **auditáveis**
+das companhias abertas brasileiras (2010–hoje), fundos imobiliários (FIIs) e
+ETFs, com metodologia pública. Cada número carrega a conta CVM de origem; os
+múltiplos são ponto-no-tempo (preço do 1º pregão a partir da chegada do balanço
+à CVM); nada é publicado sem a bateria de invariantes passar.
+
+```bash
+pip install dadosb3
+```
+
+```python
+from dadosb3 import DadosB3
+
+api = DadosB3()                        # sem chave: WEGE3, BOVA11, MXRF11, rankings de ETF, /hoje, /saude
+api.indicadores("WEGE3")["anos"]       # ROE, ROIC, margens... com a conta CVM de cada número
+api.multiplos("WEGE3")                 # P/L, P/VP, EV/EBITDA ponto-no-tempo
+api.etf("BOVA11")                      # cota diária, ágio/deságio, taxa efetiva, carteira
+api.auditar_amostra(semente=4242)      # sorteie a SUA amostra e confira contra a CVM
+
+api = DadosB3(chave="sua-chave")       # ou DADOS_B3_API_KEY no ambiente
+api.screener(roic_min=0.15, dl_ebitda_max=2, ano=2024)
+api.fiis_screener(pvp_max=0.9, dy_min=0.10)
+```
+
+Chave grátis (200 consultas/dia, sem cartão) ou Pro em
+[dadosb3.com/assinar](https://dadosb3.com/assinar). Documentação da API em
+[dadosb3.com/api](https://dadosb3.com/api); metodologia em
+[dadosb3.com/metodologia](https://dadosb3.com/metodologia); para quem é (e para
+quem não é) em [dadosb3.com/para-quem](https://dadosb3.com/para-quem).
+
+## Métodos
+
+| Método | Rota | Chave? |
+|---|---|---|
+| `empresas()` | `/empresas` | não |
+| `indicadores(t)`, `multiplos(t)`, `fatos(t)`, `dividendos(t)`, `scores(t)`, `reapresentacoes(t)`, `trimestres(t)` | `/empresas/{t}/...` | WEGE3 não; demais sim |
+| `screener(ano=, **faixas)` | `/screener` | sim |
+| `fii(t)` | `/fiis/{t}` | MXRF11 não; demais sim |
+| `fiis_ranking()`, `fiis_screener(**faixas)` | `/fiis`, `/fiis/screener` | sim |
+| `etfs_ranking()` | `/etfs` | não |
+| `etf(t)` | `/etfs/{t}` | BOVA11 não; demais sim |
+| `hoje()`, `saude()`, `dicionario()` | `/hoje`, `/saude`, `/dicionario` | não |
+| `auditar_amostra(semente, n=25)` | `/auditoria/amostra/{semente}/{n}` | não |
+
+Erros: `ChaveNecessaria` (401), `NaoEncontrado` (404), `ErroDadosB3` (demais),
+todos com `.status` e `.detalhe` (o corpo da resposta da API).
+
+## Limites, ditos antes
+
+Preço só de fim de dia (COTAHIST); sem tratamento de viés de sobrevivência
+(companhia que saiu da bolsa não está na base); sem composição histórica de
+índice; a base começa em 2010. A lista completa está em
+[dadosb3.com/o-que-nao-resolvemos](https://dadosb3.com/o-que-nao-resolvemos).
+
+Não é recomendação de investimento. Fontes: CVM (dados abertos, ODbL) e B3
+(COTAHIST). Projeto independente, não afiliado à B3 nem à CVM. Licença deste
+cliente: MIT. Conector MCP: [Val7h/dados-b3-mcp](https://github.com/Val7h/dados-b3-mcp).

dadosb3-0.1.0/dadosb3/__init__.py

@@ -0,0 +1,175 @@
+"""dadosb3 — cliente Python da API Dados B3 (https://dadosb3.com).
+
+Fundamentos auditáveis das companhias abertas brasileiras (2010–hoje), fundos
+imobiliários (FIIs) e ETFs, com metodologia pública: cada número carrega a
+conta CVM de origem, os múltiplos são ponto-no-tempo (preço do 1º pregão a
+partir da chegada do balanço à CVM) e nada é publicado sem a bateria de
+invariantes passar.
+
+    from dadosb3 import DadosB3
+    api = DadosB3()                       # sem chave: WEGE3, BOVA11, MXRF11, rankings, saúde
+    api = DadosB3(chave="sua-chave")      # chave grátis (200/dia) ou Pro em https://dadosb3.com/assinar
+    api.indicadores("WEGE3")              # ROE, ROIC, margens... com a conta CVM de cada número
+    api.multiplos("WEGE3")                # P/L, P/VP, EV/EBITDA ponto-no-tempo
+    api.etf("BOVA11")                     # cota diária, ágio/deságio, taxa efetiva, carteira
+    api.auditar_amostra(semente=4242)     # sorteie a SUA amostra e confira contra a CVM
+
+Não é recomendação de investimento. Fontes: CVM (dados abertos, ODbL) e B3
+(COTAHIST fim de dia).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+__version__ = "0.1.0"
+__all__ = ["DadosB3", "ErroDadosB3", "ChaveNecessaria", "NaoEncontrado"]
+
+URL_PADRAO = "https://dadosb3.com"
+
+
+class ErroDadosB3(Exception):
+    """Erro devolvido pela API (status >= 400) com o corpo em `detalhe`."""
+
+    def __init__(self, status: int, detalhe: Any):
+        self.status, self.detalhe = status, detalhe
+        super().__init__(f"HTTP {status}: {detalhe}")
+
+
+class ChaveNecessaria(ErroDadosB3):
+    """401: a rota exige chave (grátis ou Pro). WEGE3, BOVA11 e MXRF11 são abertos."""
+
+
+class NaoEncontrado(ErroDadosB3):
+    """404: ticker ou recurso inexistente."""
+
+
+class DadosB3:
+    """Cliente síncrono. Cada método devolve o JSON da API como `dict`.
+
+    Parâmetros:
+      chave — X-API-Key. Também lida de `DADOS_B3_API_KEY`.
+      url — base da API (padrão https://dadosb3.com).
+      timeout — segundos (padrão 30).
+    """
+
+    def __init__(self, chave: str | None = None, url: str = URL_PADRAO,
+                 timeout: float = 30, transport: httpx.BaseTransport | None = None):
+        self.chave = chave or os.environ.get("DADOS_B3_API_KEY", "")
+        self.url = url.rstrip("/")
+        cabecalhos = {"Accept": "application/json",
+                      "User-Agent": f"dadosb3-python/{__version__}"}
+        if self.chave:
+            cabecalhos["X-API-Key"] = self.chave
+        self._http = httpx.Client(base_url=self.url, headers=cabecalhos,
+                                  timeout=timeout, transport=transport)
+
+    # ── infra ────────────────────────────────────────────────────────────
+    def _get(self, caminho: str, **params: Any) -> dict:
+        params = {k: v for k, v in params.items() if v not in (None, "")}
+        r = self._http.get(caminho, params=params)
+        if r.status_code >= 400:
+            try:
+                corpo = r.json()
+            except ValueError:
+                corpo = r.text
+            if r.status_code == 401:
+                raise ChaveNecessaria(401, corpo)
+            if r.status_code == 404:
+                raise NaoEncontrado(404, corpo)
+            raise ErroDadosB3(r.status_code, corpo)
+        return r.json()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "DadosB3":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    # ── companhias ───────────────────────────────────────────────────────
+    def empresas(self) -> dict:
+        """Todas as companhias cobertas (nome, CNPJ, ticker). Aberto."""
+        return self._get("/empresas")
+
+    def indicadores(self, ticker: str) -> dict:
+        """ROE, ROIC, margens, crescimento, dívida líquida/EBITDA — série anual
+        desde 2010, cada número com a conta CVM de origem."""
+        return self._get(f"/empresas/{ticker}/indicadores")
+
+    def multiplos(self, ticker: str) -> dict:
+        """P/L, P/VP, EV/EBITDA ponto-no-tempo (preço do 1º pregão a partir da
+        publicação real do balanço) e P/L TTM."""
+        return self._get(f"/empresas/{ticker}/multiplos")
+
+    def fatos(self, ticker: str, trimestral: bool = False) -> dict:
+        """Contas padronizadas (receita, lucro, PL...) com a conta CVM de cada uma."""
+        return self._get(f"/empresas/{ticker}/fatos", trimestral=str(trimestral).lower())
+
+    def dividendos(self, ticker: str) -> dict:
+        """Proventos, resumo anual e dividend yield de 12 meses."""
+        return self._get(f"/empresas/{ticker}/dividendos")
+
+    def scores(self, ticker: str) -> dict:
+        """Piotroski F-Score (nove critérios abertos) e critério de Graham."""
+        return self._get(f"/empresas/{ticker}/scores")
+
+    def reapresentacoes(self, ticker: str) -> dict:
+        """Balanços republicados: versão original e revisada lado a lado."""
+        return self._get(f"/empresas/{ticker}/reapresentacoes")
+
+    def trimestres(self, ticker: str) -> dict:
+        """Série trimestral (1T/2T/3T como publicados), preço do trimestre, TTM."""
+        return self._get(f"/empresas/{ticker}/trimestres")
+
+    def screener(self, ano: int | None = None, limite: int = 100, **filtros: float) -> dict:
+        """Filtra ações por faixas: roic_min=0.15, dl_ebitda_max=2, margem_liquida_min=0.1...
+        Sem `ano`, usa o último exercício de cada companhia. Exige chave."""
+        return self._get("/screener", ano=ano, limite=limite, **filtros)
+
+    # ── FIIs ─────────────────────────────────────────────────────────────
+    def fii(self, ticker: str) -> dict:
+        """Um FII: P/VP ponto-no-tempo, DY 12m, vacância, rendimentos. MXRF11 é aberto."""
+        return self._get(f"/fiis/{ticker}")
+
+    def fiis_ranking(self) -> dict:
+        """Mais descontados (P/VP), maiores DY 12m, mediana por segmento. Exige chave."""
+        return self._get("/fiis")
+
+    def fiis_screener(self, **filtros: Any) -> dict:
+        """Filtra FIIs: pvp_min, pvp_max, dy_min, dy_max (fração), segmento, cotistas_min, limite."""
+        return self._get("/fiis/screener", **filtros)
+
+    # ── ETFs ─────────────────────────────────────────────────────────────
+    def etfs_ranking(self) -> dict:
+        """Mais negociados, maior patrimônio, maior ágio/deságio sobre a cota do
+        dia, retorno 12m pela cota, menor taxa EFETIVA. Aberto."""
+        return self._get("/etfs")
+
+    def etf(self, ticker: str) -> dict:
+        """Um ETF: cota diária (FNET), ágio/deságio, taxa efetiva mensal, carteira
+        (CDA) e sobreposição com pares. BOVA11 é aberto."""
+        return self._get(f"/etfs/{ticker}")
+
+    # ── mercado, metodologia, auditoria ──────────────────────────────────
+    def hoje(self) -> dict:
+        """O que mudou nos últimos 30 dias: balanços, reenvios, proventos, eventos. Aberto."""
+        return self._get("/hoje")
+
+    def saude(self) -> dict:
+        """Cobertura atual, versão do dado e última ingestão. Aberto."""
+        return self._get("/saude")
+
+    def dicionario(self) -> dict:
+        """Fórmula, contas CVM e base do lucro de cada indicador. Aberto."""
+        return self._get("/dicionario")
+
+    def auditar_amostra(self, semente: int, n: int = 25) -> dict:
+        """Sorteia `n` casos com a SUA semente para refazer cada número contra o
+        arquivo da CVM (fórmula, conta, onde procurar). Determinístico. Aberto."""
+        return self._get(f"/auditoria/amostra/{int(semente)}/{int(n)}")

dadosb3-0.1.0/dadosb3.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: dadosb3
+Version: 0.1.0
+Summary: Cliente Python da API Dados B3: fundamentos auditáveis de ações, FIIs e ETFs da bolsa brasileira (CVM/B3), com metodologia pública.
+Author-email: Dados B3 <contato@dadosb3.com>
+License-Expression: MIT
+Project-URL: Homepage, https://dadosb3.com
+Project-URL: Documentation, https://dadosb3.com/api
+Project-URL: Methodology, https://dadosb3.com/metodologia
+Project-URL: MCP connector, https://github.com/Val7h/dados-b3-mcp
+Keywords: b3,bovespa,cvm,fundamentos,ações,fii,etf,brasil,finance,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24
+Dynamic: license-file
+
+# dadosb3
+
+Cliente Python da [API Dados B3](https://dadosb3.com): fundamentos **auditáveis**
+das companhias abertas brasileiras (2010–hoje), fundos imobiliários (FIIs) e
+ETFs, com metodologia pública. Cada número carrega a conta CVM de origem; os
+múltiplos são ponto-no-tempo (preço do 1º pregão a partir da chegada do balanço
+à CVM); nada é publicado sem a bateria de invariantes passar.
+
+```bash
+pip install dadosb3
+```
+
+```python
+from dadosb3 import DadosB3
+
+api = DadosB3()                        # sem chave: WEGE3, BOVA11, MXRF11, rankings de ETF, /hoje, /saude
+api.indicadores("WEGE3")["anos"]       # ROE, ROIC, margens... com a conta CVM de cada número
+api.multiplos("WEGE3")                 # P/L, P/VP, EV/EBITDA ponto-no-tempo
+api.etf("BOVA11")                      # cota diária, ágio/deságio, taxa efetiva, carteira
+api.auditar_amostra(semente=4242)      # sorteie a SUA amostra e confira contra a CVM
+
+api = DadosB3(chave="sua-chave")       # ou DADOS_B3_API_KEY no ambiente
+api.screener(roic_min=0.15, dl_ebitda_max=2, ano=2024)
+api.fiis_screener(pvp_max=0.9, dy_min=0.10)
+```
+
+Chave grátis (200 consultas/dia, sem cartão) ou Pro em
+[dadosb3.com/assinar](https://dadosb3.com/assinar). Documentação da API em
+[dadosb3.com/api](https://dadosb3.com/api); metodologia em
+[dadosb3.com/metodologia](https://dadosb3.com/metodologia); para quem é (e para
+quem não é) em [dadosb3.com/para-quem](https://dadosb3.com/para-quem).
+
+## Métodos
+
+| Método | Rota | Chave? |
+|---|---|---|
+| `empresas()` | `/empresas` | não |
+| `indicadores(t)`, `multiplos(t)`, `fatos(t)`, `dividendos(t)`, `scores(t)`, `reapresentacoes(t)`, `trimestres(t)` | `/empresas/{t}/...` | WEGE3 não; demais sim |
+| `screener(ano=, **faixas)` | `/screener` | sim |
+| `fii(t)` | `/fiis/{t}` | MXRF11 não; demais sim |
+| `fiis_ranking()`, `fiis_screener(**faixas)` | `/fiis`, `/fiis/screener` | sim |
+| `etfs_ranking()` | `/etfs` | não |
+| `etf(t)` | `/etfs/{t}` | BOVA11 não; demais sim |
+| `hoje()`, `saude()`, `dicionario()` | `/hoje`, `/saude`, `/dicionario` | não |
+| `auditar_amostra(semente, n=25)` | `/auditoria/amostra/{semente}/{n}` | não |
+
+Erros: `ChaveNecessaria` (401), `NaoEncontrado` (404), `ErroDadosB3` (demais),
+todos com `.status` e `.detalhe` (o corpo da resposta da API).
+
+## Limites, ditos antes
+
+Preço só de fim de dia (COTAHIST); sem tratamento de viés de sobrevivência
+(companhia que saiu da bolsa não está na base); sem composição histórica de
+índice; a base começa em 2010. A lista completa está em
+[dadosb3.com/o-que-nao-resolvemos](https://dadosb3.com/o-que-nao-resolvemos).
+
+Não é recomendação de investimento. Fontes: CVM (dados abertos, ODbL) e B3
+(COTAHIST). Projeto independente, não afiliado à B3 nem à CVM. Licença deste
+cliente: MIT. Conector MCP: [Val7h/dados-b3-mcp](https://github.com/Val7h/dados-b3-mcp).

dadosb3-0.1.0/dadosb3.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+dadosb3/__init__.py
+dadosb3.egg-info/PKG-INFO
+dadosb3.egg-info/SOURCES.txt
+dadosb3.egg-info/dependency_links.txt
+dadosb3.egg-info/requires.txt
+dadosb3.egg-info/top_level.txt
+tests/test_client.py

dadosb3-0.1.0/dadosb3.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dadosb3-0.1.0/dadosb3.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.24

dadosb3-0.1.0/dadosb3.egg-info/top_level.txt

@@ -0,0 +1 @@
+dadosb3

dadosb3-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dadosb3"
+version = "0.1.0"
+description = "Cliente Python da API Dados B3: fundamentos auditáveis de ações, FIIs e ETFs da bolsa brasileira (CVM/B3), com metodologia pública."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Dados B3", email = "contato@dadosb3.com" }]
+keywords = ["b3", "bovespa", "cvm", "fundamentos", "ações", "fii", "etf", "brasil", "finance", "api"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://dadosb3.com"
+Documentation = "https://dadosb3.com/api"
+Methodology = "https://dadosb3.com/metodologia"
+"MCP connector" = "https://github.com/Val7h/dados-b3-mcp"
+
+[tool.setuptools]
+packages = ["dadosb3"]

dadosb3-0.1.0/setup.cfg

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

dadosb3-0.1.0/tests/test_client.py

@@ -0,0 +1,85 @@
+"""Testes do cliente sem rede: um transporte falso responde como a API."""
+import json
+
+import httpx
+import pytest
+
+from dadosb3 import ChaveNecessaria, DadosB3, ErroDadosB3, NaoEncontrado
+
+
+def _api(resposta):
+    """Cliente cujo transporte grava a requisição e devolve `resposta(req)`."""
+    vistas = []
+
+    def handler(req: httpx.Request) -> httpx.Response:
+        vistas.append(req)
+        return resposta(req)
+
+    return DadosB3(chave="k-teste", transport=httpx.MockTransport(handler)), vistas
+
+
+def test_cabecalhos_accept_json_e_chave():
+    api, vistas = _api(lambda r: httpx.Response(200, json={"ok": 1}))
+    assert api.indicadores("WEGE3") == {"ok": 1}
+    req = vistas[0]
+    assert req.url.path == "/empresas/WEGE3/indicadores"
+    assert req.headers["accept"] == "application/json"
+    assert req.headers["x-api-key"] == "k-teste"
+    assert req.headers["user-agent"].startswith("dadosb3-python/")
+
+
+def test_sem_chave_nao_manda_cabecalho(monkeypatch):
+    monkeypatch.delenv("DADOS_B3_API_KEY", raising=False)
+    vistas = []
+    api = DadosB3(transport=httpx.MockTransport(lambda r: (vistas.append(r), httpx.Response(200, json={}))[1]))
+    api.saude()
+    assert "x-api-key" not in vistas[0].headers
+
+
+def test_chave_do_ambiente(monkeypatch):
+    monkeypatch.setenv("DADOS_B3_API_KEY", "k-env")
+    assert DadosB3(transport=httpx.MockTransport(lambda r: httpx.Response(200, json={}))).chave == "k-env"
+
+
+def test_rotas_e_parametros():
+    api, vistas = _api(lambda r: httpx.Response(200, json={}))
+    api.screener(roic_min=0.15, dl_ebitda_max=2, ano=2024, limite=10)
+    api.fiis_screener(pvp_max=0.9, dy_min=0.10)
+    api.fatos("ITUB4", trimestral=True)
+    api.etf("BOVA11"); api.etfs_ranking(); api.fiis_ranking(); api.fii("MXRF11")
+    api.auditar_amostra(semente=4242, n=10); api.hoje(); api.dicionario(); api.empresas()
+    caminhos = [str(v.url).replace("https://dadosb3.com", "") for v in vistas]
+    assert caminhos[0].startswith("/screener?") and "roic_min=0.15" in caminhos[0] and "ano=2024" in caminhos[0]
+    assert "dl_ebitda_max=2" in caminhos[0] and "limite=10" in caminhos[0]
+    assert caminhos[1].startswith("/fiis/screener?") and "pvp_max=0.9" in caminhos[1]
+    assert caminhos[2] == "/empresas/ITUB4/fatos?trimestral=true"
+    assert caminhos[3:] == ["/etfs/BOVA11", "/etfs", "/fiis", "/fiis/MXRF11",
+                            "/auditoria/amostra/4242/10", "/hoje", "/dicionario", "/empresas"]
+
+
+def test_parametro_vazio_nao_vai():
+    api, vistas = _api(lambda r: httpx.Response(200, json={}))
+    api.screener(ano=None, limite=100)
+    assert "ano" not in str(vistas[0].url)
+
+
+@pytest.mark.parametrize("status,tipo", [(401, ChaveNecessaria), (404, NaoEncontrado), (500, ErroDadosB3)])
+def test_erros_tipados_com_o_corpo(status, tipo):
+    corpo = {"erro": "x", "como_resolver": "crie uma chave"}
+    api, _ = _api(lambda r: httpx.Response(status, json=corpo))
+    with pytest.raises(tipo) as e:
+        api.multiplos("PETR4")
+    assert e.value.status == status and e.value.detalhe == corpo
+
+
+def test_erro_sem_json_traz_o_texto():
+    api, _ = _api(lambda r: httpx.Response(503, text="fora do ar"))
+    with pytest.raises(ErroDadosB3) as e:
+        api.saude()
+    assert e.value.detalhe == "fora do ar"
+
+
+def test_gerenciador_de_contexto_fecha():
+    with DadosB3(transport=httpx.MockTransport(lambda r: httpx.Response(200, json={}))) as api:
+        api.saude()
+    assert api._http.is_closed