quantilica-cli 0.17.0__tar.gz → 0.18.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 (42) hide show
  1. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/CHANGELOG.md +19 -0
  2. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/PKG-INFO +2 -2
  3. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/pyproject.toml +2 -2
  4. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/src/quantilica/cli/cli.py +85 -4
  5. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/src/quantilica/cli/registry.py +11 -1
  6. quantilica_cli-0.18.0/tests/test_cli_apelidos.py +180 -0
  7. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/test_registry_cli.py +24 -0
  8. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/.githooks/pre-commit +0 -0
  9. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/.githooks/pre-push +0 -0
  10. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/.github/workflows/public-hygiene.yml +0 -0
  11. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/.github/workflows/publish.yml +0 -0
  12. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/.github/workflows/test.yml +0 -0
  13. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/.gitignore +0 -0
  14. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/LICENSE +0 -0
  15. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/README.md +0 -0
  16. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/src/quantilica/cli/__init__.py +0 -0
  17. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/src/quantilica/cli/catalog.py +0 -0
  18. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/src/quantilica/cli/docs.py +0 -0
  19. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/src/quantilica/cli/health.py +0 -0
  20. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/src/quantilica/cli/lake.py +0 -0
  21. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/src/quantilica/cli/manifests.py +0 -0
  22. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/src/quantilica/cli/sdk.py +0 -0
  23. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/src/quantilica/cli/sources.py +0 -0
  24. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/src/quantilica/cli/ui.py +0 -0
  25. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/src/quantilica/py.typed +0 -0
  26. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/__init__.py +0 -0
  27. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/conftest.py +0 -0
  28. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/lake_build_fakes.py +0 -0
  29. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/lake_fixtures.py +0 -0
  30. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/test_catalog_cli.py +0 -0
  31. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/test_docs_cli.py +0 -0
  32. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/test_health.py +0 -0
  33. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/test_lake_cli.py +0 -0
  34. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/test_manifests.py +0 -0
  35. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/test_package_hygiene.py +0 -0
  36. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/test_sdk.py +0 -0
  37. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/test_sdk_backfill.py +0 -0
  38. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/test_sdk_force_probe.py +0 -0
  39. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/test_sdk_mes_string.py +0 -0
  40. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/test_sdk_onda_a2.py +0 -0
  41. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/test_sources.py +0 -0
  42. {quantilica_cli-0.17.0 → quantilica_cli-0.18.0}/tests/test_ui.py +0 -0
@@ -7,6 +7,25 @@ e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
7
7
 
8
8
  ## [Não lançado]
9
9
 
10
+ ## [0.18.0] - 2026-11-10
11
+
12
+ ### Adicionado
13
+
14
+ - `quantilica registry export` inclui `redistribuicao` e `restricao_nota` de
15
+ cada fetcher (e a coluna `Redistrib.` na tabela). `--strict` não falha por
16
+ `redistribuicao` ausente: `None` significa "não avaliada". Requer
17
+ `quantilica-core` com o campo (`>=0.20.0`).
18
+
19
+ ### Alterado
20
+
21
+ - O subcomando visível de cada fetcher que declara `info` passa a ser o id
22
+ canônico (`quantilica tesouro-direto`). O nome do entry point (`td`) e os
23
+ apelidos de `info.aliases` continuam funcionando como subcomandos ocultos
24
+ para o mesmo app, então `quantilica td sync` produz os mesmos caminhos,
25
+ `source_id` e telemetria. Apelido que colide com comando embutido, com id ou
26
+ entry point de outro plugin, ou reivindicado por dois plugins, não é montado
27
+ e sai um aviso em stderr. Plugin sem `info` segue com o nome do entry point.
28
+
10
29
  ## [0.17.0] - 2026-11-10
11
30
 
12
31
  ### Adicionado
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: quantilica-cli
3
- Version: 0.17.0
3
+ Version: 0.18.0
4
4
  Summary: Unified CLI for Quantilica open data fetchers
5
5
  Author-email: "Komesu, D.K." <daniel@dkko.me>
6
6
  License-Expression: MIT
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
16
16
  Classifier: Programming Language :: Python :: 3.13
17
17
  Classifier: Typing :: Typed
18
18
  Requires-Python: >=3.12
19
- Requires-Dist: quantilica-core>=0.19.0
19
+ Requires-Dist: quantilica-core>=0.20.0
20
20
  Requires-Dist: rich>=13.0.0
21
21
  Requires-Dist: typer>=0.15.0
22
22
  Provides-Extra: docs
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "quantilica-cli"
3
- version = "0.17.0"
3
+ version = "0.18.0"
4
4
  description = "Unified CLI for Quantilica open data fetchers"
5
5
  readme = "README.md"
6
6
  authors = [{ name = "Komesu, D.K.", email = "daniel@dkko.me" }]
@@ -20,7 +20,7 @@ classifiers = [
20
20
  "Programming Language :: Python :: 3.13",
21
21
  ]
22
22
  dependencies = [
23
- "quantilica-core>=0.19.0",
23
+ "quantilica-core>=0.20.0",
24
24
  "rich>=13.0.0",
25
25
  "typer>=0.15.0",
26
26
  ]
@@ -8,6 +8,7 @@ from importlib.metadata import entry_points
8
8
  from typing import Annotated
9
9
 
10
10
  import typer
11
+ from quantilica.core.registry import FetcherInfo
11
12
  from rich.console import Console
12
13
  from rich.logging import RichHandler
13
14
  from rich.table import Table
@@ -65,11 +66,90 @@ def _load_plugins(group: str) -> dict[str, typer.Typer]:
65
66
  return plugins
66
67
 
67
68
 
69
+ def _declared_info(plugin_app: typer.Typer) -> FetcherInfo | None:
70
+ """``FetcherInfo`` declarado pelo plugin (``None`` se não for um FetcherApp)."""
71
+ fetcher = getattr(plugin_app, "fetcher_app", None)
72
+ if fetcher is None or not getattr(fetcher, "info_declared", False):
73
+ return None
74
+ info = getattr(fetcher, "info", None)
75
+ return info if isinstance(info, FetcherInfo) else None
76
+
77
+
78
+ def _warn(message: str) -> None:
79
+ sys.stderr.write(f"Aviso: {message}\n")
80
+
81
+
82
+ def _mount_fetchers(plugins: dict[str, typer.Typer], reserved: set[str]) -> None:
83
+ """Monta um subcomando visível por fetcher e os apelidos como ocultos.
84
+
85
+ O nome visível é o id canônico (``info.id``); plugin sem ``info`` declarado
86
+ segue com o nome do entry point. O nome do entry point e os apelidos viram
87
+ subcomandos ocultos para o mesmo Typer. Precedência: embutidos > ids
88
+ canônicos > nomes de entry point > apelidos. Apelido que colide com um
89
+ nome de precedência maior, ou que dois plugins reivindicam, não é montado
90
+ (aviso em stderr); nunca derruba o CLI.
91
+ """
92
+ taken = set(reserved)
93
+ canonical: dict[str, typer.Typer] = {}
94
+ for ep_name, plugin_app in sorted(plugins.items()):
95
+ info = _declared_info(plugin_app)
96
+ name = info.id if info is not None else ep_name
97
+ canonical.setdefault(name, plugin_app)
98
+ app.add_typer(plugin_app, name=name)
99
+ taken |= set(canonical)
100
+
101
+ def claim(tier: list[tuple[str, str, typer.Typer, str]]) -> None:
102
+ owners: dict[str, set[str]] = {}
103
+ for name, owner, _, _ in tier:
104
+ owners.setdefault(name, set()).add(owner)
105
+ warned: set[str] = set()
106
+ for name, owner, plugin_app, kind in tier:
107
+ if name in warned:
108
+ continue
109
+ if name in taken:
110
+ _warn(
111
+ f"{kind} '{name}' de '{owner}' colide com um comando existente; "
112
+ "não foi montado."
113
+ )
114
+ warned.add(name)
115
+ elif len(owners[name]) > 1:
116
+ _warn(
117
+ f"{kind} '{name}' é reivindicado por mais de um plugin "
118
+ f"({', '.join(sorted(owners[name]))}); não foi montado."
119
+ )
120
+ warned.add(name)
121
+ else:
122
+ app.add_typer(plugin_app, name=name, hidden=True)
123
+ taken.update(n for n, o, _, _ in tier if len(owners[n]) == 1)
124
+
125
+ eps_tier: list[tuple[str, str, typer.Typer, str]] = []
126
+ alias_tier: list[tuple[str, str, typer.Typer, str]] = []
127
+ for ep_name, plugin_app in sorted(plugins.items()):
128
+ info = _declared_info(plugin_app)
129
+ if info is None:
130
+ continue
131
+ if ep_name != info.id:
132
+ eps_tier.append((ep_name, info.id, plugin_app, "nome de entry point"))
133
+ for alias in info.aliases:
134
+ alias_tier.append((alias, info.id, plugin_app, "apelido"))
135
+ seen: set[tuple[str, str]] = set()
136
+ for tier in (eps_tier, alias_tier):
137
+ # mesmo nome repetido pelo mesmo plugin (apelido == entry point) vale uma vez
138
+ tier[:] = [
139
+ t for t in tier if not ((t[0], t[1]) in seen or seen.add((t[0], t[1])))
140
+ ]
141
+ claim(tier)
142
+
143
+
68
144
  def _register_plugins() -> None:
69
145
  # Fetchers e comandos ficam na raiz: `quantilica <nome>`.
70
- for name, plugin_app in _load_plugins(FETCHER_GROUP).items():
71
- app.add_typer(plugin_app, name=name)
72
- for name, plugin_app in _load_plugins(COMMAND_GROUP).items():
146
+ commands = _load_plugins(COMMAND_GROUP)
147
+ reserved = {
148
+ "catalog", "docs", "lake", "manifests", "registry", "sources",
149
+ "install", "uninstall", "doctor", "health", "list-sources",
150
+ } | set(commands) # fmt: skip
151
+ _mount_fetchers(_load_plugins(FETCHER_GROUP), reserved)
152
+ for name, plugin_app in commands.items():
73
153
  app.add_typer(plugin_app, name=name)
74
154
 
75
155
 
@@ -142,7 +222,8 @@ def list_sources(
142
222
  description = ""
143
223
  if info and hasattr(info, "help") and info.help:
144
224
  description = info.help
145
- table.add_row(f"quantilica {name}", description)
225
+ declared = _declared_info(plugin_app)
226
+ table.add_row(f"quantilica {declared.id if declared else name}", description)
146
227
 
147
228
  console.print(table)
148
229
 
@@ -181,7 +181,16 @@ def cmd_export(
181
181
  sys.stdout.write(json.dumps(registry, ensure_ascii=False, indent=2) + "\n")
182
182
  else:
183
183
  table = Table(title=f"Registro de fetchers ({len(found)})")
184
- for col in ("Id", "Apelidos", "Órgão", "Cadência", "Frescor", "Info", "Lake"):
184
+ for col in (
185
+ "Id",
186
+ "Apelidos",
187
+ "Órgão",
188
+ "Cadência",
189
+ "Redistrib.",
190
+ "Frescor",
191
+ "Info",
192
+ "Lake",
193
+ ):
185
194
  table.add_column(col)
186
195
  for d, row in zip(
187
196
  sorted(found, key=lambda d: (d.info.id, d.entry_point)),
@@ -193,6 +202,7 @@ def cmd_export(
193
202
  ", ".join(d.info.aliases) or "-",
194
203
  d.info.orgao or "-",
195
204
  d.info.cadencia or "-",
205
+ d.info.redistribuicao or "-",
196
206
  d.freshness_policy or "-",
197
207
  "[green]sim[/green]" if d.info_declared else "[yellow]não[/yellow]",
198
208
  "sim" if row["lake"] else "-",
@@ -0,0 +1,180 @@
1
+ """Apelidos como subcomandos ocultos: o id é o nome canônico."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import subprocess
6
+ import sys
7
+ from types import SimpleNamespace
8
+
9
+ import pytest
10
+ import typer
11
+ from quantilica.core.registry import FetcherInfo
12
+ from typer.testing import CliRunner
13
+
14
+ from quantilica.cli import cli
15
+
16
+ runner = CliRunner()
17
+
18
+
19
+ def _plugin(
20
+ fid: str | None, aliases: tuple[str, ...] = (), source_id: str = "x"
21
+ ) -> typer.Typer:
22
+ plugin = typer.Typer(help=f"Ajuda de {fid or source_id}")
23
+
24
+ @plugin.command("sync")
25
+ def sync() -> None:
26
+ """Sincroniza."""
27
+ typer.echo(f"sync:{source_id}")
28
+
29
+ if fid is not None:
30
+ plugin.fetcher_app = SimpleNamespace( # type: ignore[attr-defined]
31
+ info=FetcherInfo(id=fid, nome=fid, aliases=aliases),
32
+ info_declared=True,
33
+ source_id=source_id,
34
+ )
35
+ return plugin
36
+
37
+
38
+ @pytest.fixture
39
+ def fresh_app(monkeypatch):
40
+ app = typer.Typer(no_args_is_help=True)
41
+
42
+ @app.command("lake")
43
+ def lake() -> None:
44
+ typer.echo("builtin")
45
+
46
+ @app.command("docs")
47
+ def docs() -> None:
48
+ typer.echo("builtin")
49
+
50
+ monkeypatch.setattr(cli, "app", app)
51
+ return app
52
+
53
+
54
+ def _mount(plugins, reserved=("lake", "docs")):
55
+ cli._mount_fetchers(plugins, set(reserved))
56
+
57
+
58
+ def _help_names(app) -> list[str]:
59
+ out = runner.invoke(app, ["--help"]).output
60
+ return out.split("Commands")[-1].split()
61
+
62
+
63
+ def test_id_e_visivel_apelidos_e_entry_point_ocultos(fresh_app):
64
+ _mount({"td": _plugin("tesouro-direto", ("td", "tddata", "tesouro_direto"), "td")})
65
+ for nome in ("tesouro-direto", "td", "tddata", "tesouro_direto"):
66
+ r = runner.invoke(fresh_app, [nome, "sync"])
67
+ assert r.exit_code == 0, nome
68
+ assert r.output.strip() == "sync:td"
69
+ visiveis = runner.invoke(fresh_app, ["--help"]).output
70
+ assert "tesouro-direto" in visiveis
71
+ assert "tddata" not in visiveis
72
+ assert "tesouro_direto" not in visiveis
73
+
74
+
75
+ def test_help_igual_pelo_id_e_pelo_nome_antigo(fresh_app):
76
+ _mount({"td": _plugin("tesouro-direto", ("tddata",))})
77
+ a = runner.invoke(fresh_app, ["td", "--help"]).output
78
+ b = runner.invoke(fresh_app, ["tesouro-direto", "--help"]).output
79
+ c = runner.invoke(fresh_app, ["tddata", "--help"]).output
80
+ norm = lambda t: [ln for ln in t.splitlines() if "Usage" not in ln] # noqa: E731
81
+ assert norm(a) == norm(b) == norm(c)
82
+
83
+
84
+ def test_plugin_sem_info_mantem_nome_do_entry_point(fresh_app):
85
+ _mount({"antigo": _plugin(None, source_id="antigo")})
86
+ assert runner.invoke(fresh_app, ["antigo", "sync"]).output.strip() == "sync:antigo"
87
+
88
+
89
+ def test_apelido_colide_com_embutido(fresh_app, capsys):
90
+ _mount({"abc": _plugin("abc", ("lake", "abcd"))})
91
+ assert runner.invoke(fresh_app, ["lake"]).output.strip() == "builtin"
92
+ assert runner.invoke(fresh_app, ["abcd", "sync"]).exit_code == 0
93
+ err = capsys.readouterr().err
94
+ assert err.count("'lake'") == 1
95
+ assert "Aviso" in err
96
+
97
+
98
+ def test_apelido_colide_com_id_de_outro_plugin(fresh_app, capsys):
99
+ _mount(
100
+ {
101
+ "a": _plugin("alfa", ("beta",), "alfa"),
102
+ "b": _plugin("beta", (), "beta"),
103
+ }
104
+ )
105
+ assert runner.invoke(fresh_app, ["beta", "sync"]).output.strip() == "sync:beta"
106
+ assert "'beta'" in capsys.readouterr().err
107
+
108
+
109
+ def test_apelido_colide_com_entry_point_de_outro(fresh_app, capsys):
110
+ _mount(
111
+ {
112
+ "a": _plugin("alfa", ("legado",), "alfa"),
113
+ "legado": _plugin(None, source_id="legado"),
114
+ }
115
+ )
116
+ assert runner.invoke(fresh_app, ["legado", "sync"]).output.strip() == "sync:legado"
117
+ assert "'legado'" in capsys.readouterr().err
118
+
119
+
120
+ def test_apelido_reivindicado_por_dois_plugins_nao_e_montado(fresh_app, capsys):
121
+ _mount(
122
+ {
123
+ "a": _plugin("alfa", ("curto",), "alfa"),
124
+ "b": _plugin("beta", ("curto",), "beta"),
125
+ }
126
+ )
127
+ assert runner.invoke(fresh_app, ["curto", "sync"]).exit_code != 0
128
+ assert runner.invoke(fresh_app, ["alfa", "sync"]).exit_code == 0
129
+ assert runner.invoke(fresh_app, ["beta", "sync"]).exit_code == 0
130
+ assert capsys.readouterr().err.count("'curto'") == 1
131
+
132
+
133
+ def test_nao_carrega_plugin_duas_vezes(monkeypatch):
134
+ chamadas = []
135
+
136
+ class EP:
137
+ name = "td"
138
+
139
+ def load(self):
140
+ chamadas.append(1)
141
+ return _plugin("tesouro-direto", ("tddata",))
142
+
143
+ monkeypatch.setattr(
144
+ cli, "entry_points", lambda group: [EP()] if "fetchers" in group else []
145
+ )
146
+ plugins = cli._load_plugins(cli.FETCHER_GROUP)
147
+ cli._mount_fetchers(plugins, set())
148
+ assert len(chamadas) == 1
149
+
150
+
151
+ def test_source_id_e_telemetria_nao_dependem_do_nome_do_subcomando():
152
+ """O source_id vem do FetcherApp, não do nome pelo qual o usuário chamou."""
153
+ from quantilica.cli.sdk import FetcherApp
154
+
155
+ fa = FetcherApp(
156
+ "tesouro-direto-fetcher",
157
+ source_id="td",
158
+ groups_dict={},
159
+ aliases_dict={},
160
+ list_datasets=lambda g: [],
161
+ info=FetcherInfo(id="tesouro-direto", nome="TD", aliases=("td",)),
162
+ )
163
+ assert fa.source_id == "td"
164
+ assert str(fa.default_output) == "/data/td"
165
+
166
+
167
+ def _help(nome: str) -> str:
168
+ r = subprocess.run(
169
+ [sys.executable, "-m", "quantilica.cli.cli", nome, "--help"],
170
+ capture_output=True,
171
+ text=True,
172
+ timeout=120,
173
+ )
174
+ return "\n".join(ln for ln in r.stdout.splitlines() if "Usage" not in ln)
175
+
176
+
177
+ def test_fumaca_real_td_e_tesouro_direto():
178
+ pytest.importorskip("tesouro_direto_fetcher")
179
+ a, b = _help("td"), _help("tesouro-direto")
180
+ assert a and a == b
@@ -163,3 +163,27 @@ def test_apelidos_do_info_instalado_nao_contradizem_a_tabela():
163
163
  if n in sources.SOURCES_REGISTRY and sources.SOURCES_REGISTRY[n] != dist
164
164
  }
165
165
  assert not conflicts, f"FetcherInfo contradiz SOURCES_REGISTRY: {conflicts}"
166
+
167
+
168
+ def test_export_inclui_redistribuicao_e_strict_nao_exige(fake_eps):
169
+ restrito = FetcherInfo(
170
+ "b3",
171
+ nome="B3",
172
+ redistribuicao="restrita",
173
+ restricao_nota="termos vedam coleta automatizada",
174
+ )
175
+ livre = FetcherInfo("cvm", nome="CVM") # redistribuicao ausente
176
+ fake_eps(
177
+ fetchers=[
178
+ _ep("b3", _fetcher("b3-fetcher", info=restrito).app, "b3-fetcher"),
179
+ _ep("cvm", _fetcher("cvm-fetcher", info=livre).app, "cvm-fetcher"),
180
+ ]
181
+ )
182
+ res = runner.invoke(app, ["export", "--strict", "--json"])
183
+ assert res.exit_code == 0
184
+ por_id = {f["id"]: f for f in json.loads(res.stdout)["fetchers"]}
185
+ assert por_id["b3"]["redistribuicao"] == "restrita"
186
+ assert por_id["b3"]["restricao_nota"] == "termos vedam coleta automatizada"
187
+ assert por_id["cvm"]["redistribuicao"] is None
188
+ assert por_id["cvm"]["restricao_nota"] is None
189
+ assert runner.invoke(app, ["export"]).exit_code == 0
File without changes