quantilica-cli 0.16.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.16.0 → quantilica_cli-0.18.0}/CHANGELOG.md +39 -0
  2. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/PKG-INFO +2 -2
  3. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/pyproject.toml +2 -2
  4. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/src/quantilica/cli/cli.py +87 -4
  5. quantilica_cli-0.18.0/src/quantilica/cli/registry.py +233 -0
  6. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/src/quantilica/cli/sdk.py +24 -0
  7. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/src/quantilica/cli/sources.py +24 -2
  8. quantilica_cli-0.18.0/tests/test_cli_apelidos.py +180 -0
  9. quantilica_cli-0.18.0/tests/test_registry_cli.py +189 -0
  10. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/.githooks/pre-commit +0 -0
  11. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/.githooks/pre-push +0 -0
  12. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/.github/workflows/public-hygiene.yml +0 -0
  13. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/.github/workflows/publish.yml +0 -0
  14. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/.github/workflows/test.yml +0 -0
  15. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/.gitignore +0 -0
  16. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/LICENSE +0 -0
  17. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/README.md +0 -0
  18. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/src/quantilica/cli/__init__.py +0 -0
  19. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/src/quantilica/cli/catalog.py +0 -0
  20. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/src/quantilica/cli/docs.py +0 -0
  21. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/src/quantilica/cli/health.py +0 -0
  22. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/src/quantilica/cli/lake.py +0 -0
  23. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/src/quantilica/cli/manifests.py +0 -0
  24. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/src/quantilica/cli/ui.py +0 -0
  25. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/src/quantilica/py.typed +0 -0
  26. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/__init__.py +0 -0
  27. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/conftest.py +0 -0
  28. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/lake_build_fakes.py +0 -0
  29. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/lake_fixtures.py +0 -0
  30. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/test_catalog_cli.py +0 -0
  31. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/test_docs_cli.py +0 -0
  32. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/test_health.py +0 -0
  33. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/test_lake_cli.py +0 -0
  34. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/test_manifests.py +0 -0
  35. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/test_package_hygiene.py +0 -0
  36. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/test_sdk.py +0 -0
  37. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/test_sdk_backfill.py +0 -0
  38. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/test_sdk_force_probe.py +0 -0
  39. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/test_sdk_mes_string.py +0 -0
  40. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/test_sdk_onda_a2.py +0 -0
  41. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/test_sources.py +0 -0
  42. {quantilica_cli-0.16.0 → quantilica_cli-0.18.0}/tests/test_ui.py +0 -0
@@ -7,6 +7,45 @@ 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
+
29
+ ## [0.17.0] - 2026-11-10
30
+
31
+ ### Adicionado
32
+
33
+ - `FetcherApp(info=FetcherInfo(...))`: o fetcher declara os fatos da fonte
34
+ (id canônico, apelidos, órgão, licença, página, cadência). Sem `info`, um
35
+ `FetcherInfo` mínimo é derivado de `name` e `info_declared` fica `False`;
36
+ `source_id` segue como antes.
37
+ - `quantilica registry export [--json] [--strict]`: descobre os entry points
38
+ `quantilica.fetchers` e `quantilica.lake` e monta o registro (info,
39
+ `freshness_policy`, `default_output`, grupos, `lake` e `lake_source_id`).
40
+ `--strict` falha se algum fetcher não declarar `info`, não carregar ou houver
41
+ id/apelido duplicado.
42
+
43
+ ### Alterado
44
+
45
+ - `quantilica install` e afins: para fetchers instalados que declaram `info`,
46
+ id e apelidos vêm do `FetcherInfo`; `SOURCES_REGISTRY` fica como reserva
47
+ para instalar fontes ausentes. Teste garante que os dois não se contradizem.
48
+
10
49
  ## [0.16.0] - 2026-11-08
11
50
 
12
51
  ### Adicionado
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: quantilica-cli
3
- Version: 0.16.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.16.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.16.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.16.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
@@ -18,6 +19,7 @@ from quantilica.cli.docs import app as docs_app
18
19
  from quantilica.cli.health import cmd_health
19
20
  from quantilica.cli.lake import app as lake_app
20
21
  from quantilica.cli.manifests import app as manifests_app
22
+ from quantilica.cli.registry import app as registry_app
21
23
  from quantilica.cli.sources import (
22
24
  app as sources_app,
23
25
  )
@@ -40,6 +42,7 @@ app.add_typer(catalog_app, name="catalog")
40
42
  app.add_typer(docs_app, name="docs")
41
43
  app.add_typer(lake_app, name="lake")
42
44
  app.add_typer(manifests_app, name="manifests")
45
+ app.add_typer(registry_app, name="registry")
43
46
  app.add_typer(sources_app, name="sources")
44
47
 
45
48
  # Adiciona comandos top-level install, uninstall, doctor e health
@@ -63,11 +66,90 @@ def _load_plugins(group: str) -> dict[str, typer.Typer]:
63
66
  return plugins
64
67
 
65
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
+
66
144
  def _register_plugins() -> None:
67
145
  # Fetchers e comandos ficam na raiz: `quantilica <nome>`.
68
- for name, plugin_app in _load_plugins(FETCHER_GROUP).items():
69
- app.add_typer(plugin_app, name=name)
70
- 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():
71
153
  app.add_typer(plugin_app, name=name)
72
154
 
73
155
 
@@ -140,7 +222,8 @@ def list_sources(
140
222
  description = ""
141
223
  if info and hasattr(info, "help") and info.help:
142
224
  description = info.help
143
- 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)
144
227
 
145
228
  console.print(table)
146
229
 
@@ -0,0 +1,233 @@
1
+ """Comando ``quantilica registry`` — o registro dos fetchers instalados.
2
+
3
+ Descobre os entry points ``quantilica.fetchers`` (e ``quantilica.lake``) e monta
4
+ o ``registry.json`` com :func:`quantilica.core.registry.build_registry`.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import contextlib
10
+ import json
11
+ import sys
12
+ from dataclasses import dataclass
13
+ from importlib.metadata import entry_points
14
+ from typing import Annotated, Any
15
+
16
+ import typer
17
+ from quantilica.core.registry import (
18
+ FetcherInfo,
19
+ RegistryError,
20
+ build_registry,
21
+ check_unique,
22
+ )
23
+ from rich.console import Console
24
+ from rich.table import Table
25
+
26
+ FETCHER_GROUP = "quantilica.fetchers"
27
+ LAKE_GROUP = "quantilica.lake"
28
+
29
+ app = typer.Typer(
30
+ help="Registro dos fetchers instalados (ids, apelidos, fatos da fonte).",
31
+ no_args_is_help=True,
32
+ )
33
+
34
+
35
+ @app.callback()
36
+ def _registry_group() -> None:
37
+ """Registro dos fetchers instalados."""
38
+
39
+
40
+ @dataclass
41
+ class DiscoveredFetcher:
42
+ """Um fetcher instalado, com o que o registro precisa saber dele."""
43
+
44
+ info: FetcherInfo
45
+ info_declared: bool
46
+ entry_point: str
47
+ distribution: str | None
48
+ source_id: str | None = None
49
+ freshness_policy: str | None = None
50
+ default_output: str | None = None
51
+ groups: list[str] | None = None
52
+ lake: bool = False
53
+ lake_source_id: str | None = None
54
+ error: str | None = None
55
+
56
+ def to_dict(self) -> dict[str, Any]:
57
+ """Info do fetcher mais os campos de execução."""
58
+ return {
59
+ **self.info.to_dict(),
60
+ "info_declared": self.info_declared,
61
+ "entry_point": self.entry_point,
62
+ "distribution": self.distribution,
63
+ "source_id": self.source_id,
64
+ "freshness_policy": self.freshness_policy,
65
+ "default_output": self.default_output,
66
+ "groups": self.groups,
67
+ "lake": self.lake,
68
+ "lake_source_id": self.lake_source_id,
69
+ "error": self.error,
70
+ }
71
+
72
+
73
+ def _fallback_info(ep_name: str, dist: str | None) -> FetcherInfo:
74
+ from quantilica.cli.sdk import derive_fetcher_info
75
+
76
+ return derive_fetcher_info(dist or ep_name)
77
+
78
+
79
+ def _find_fetcher_app(obj: Any) -> Any | None:
80
+ """Acha o ``FetcherApp`` a partir do objeto carregado do entry point."""
81
+ from quantilica.cli.sdk import FetcherApp
82
+
83
+ if isinstance(obj, FetcherApp):
84
+ return obj
85
+ candidate = getattr(obj, "fetcher_app", None)
86
+ return candidate if isinstance(candidate, FetcherApp) else None
87
+
88
+
89
+ def discover_fetchers() -> list[DiscoveredFetcher]:
90
+ """Carrega os entry points de fetchers e devolve o que cada um declara.
91
+
92
+ Nunca levanta por causa de um plugin quebrado: o erro vai em ``error``.
93
+ A saída padrão durante o carregamento é desviada para o stderr (módulos de
94
+ fetchers podem imprimir ao importar).
95
+ """
96
+ lake_eps = list(entry_points(group=LAKE_GROUP))
97
+ found: list[DiscoveredFetcher] = []
98
+ with contextlib.redirect_stdout(sys.stderr):
99
+ for ep in entry_points(group=FETCHER_GROUP):
100
+ dist = ep.dist.name if ep.dist is not None else None
101
+ try:
102
+ fetcher = _find_fetcher_app(ep.load())
103
+ error = None
104
+ except Exception as exc:
105
+ fetcher, error = None, f"{type(exc).__name__}: {exc}"
106
+ if fetcher is not None:
107
+ policy = fetcher.freshness_policy
108
+ item = DiscoveredFetcher(
109
+ info=fetcher.info,
110
+ info_declared=fetcher.info_declared,
111
+ entry_point=ep.name,
112
+ distribution=dist,
113
+ source_id=fetcher.source_id,
114
+ freshness_policy=(
115
+ None
116
+ if policy is None
117
+ else str(getattr(policy, "value", policy))
118
+ ),
119
+ default_output=str(fetcher.default_output),
120
+ groups=sorted(fetcher.groups),
121
+ )
122
+ else:
123
+ item = DiscoveredFetcher(
124
+ info=_fallback_info(ep.name, dist),
125
+ info_declared=False,
126
+ entry_point=ep.name,
127
+ distribution=dist,
128
+ error=error,
129
+ )
130
+ for lep in lake_eps:
131
+ ldist = lep.dist.name if lep.dist is not None else None
132
+ if (dist is not None and ldist == dist) or lep.name in (
133
+ item.info.names
134
+ ):
135
+ item.lake = True
136
+ item.lake_source_id = lep.name
137
+ break
138
+ found.append(item)
139
+ return found
140
+
141
+
142
+ def build_export(found: list[DiscoveredFetcher]) -> tuple[dict[str, Any], str | None]:
143
+ """Monta o registro; devolve também a mensagem de duplicidade, se houver."""
144
+ infos = [d.info for d in found]
145
+ problem: str | None = None
146
+ try:
147
+ registry = build_registry(infos)
148
+ except RegistryError as exc:
149
+ problem = str(exc)
150
+ registry = {"version": 1, "fetchers": []}
151
+ extras = sorted(found, key=lambda d: (d.info.id, d.entry_point))
152
+ registry["fetchers"] = [d.to_dict() for d in extras]
153
+ return registry, problem
154
+
155
+
156
+ @app.command("export")
157
+ def cmd_export(
158
+ as_json: Annotated[
159
+ bool, typer.Option("--json", help="Saída em JSON puro no stdout.")
160
+ ] = False,
161
+ strict: Annotated[
162
+ bool,
163
+ typer.Option(
164
+ "--strict",
165
+ help="Falha se algum fetcher não declarar info, não carregar "
166
+ "ou houver id/apelido duplicado.",
167
+ ),
168
+ ] = False,
169
+ ) -> None:
170
+ """Exporta o registro dos fetchers instalados (entry points)."""
171
+ found = discover_fetchers()
172
+ registry, duplicate = build_export(found)
173
+ if duplicate is None:
174
+ with contextlib.suppress(RegistryError):
175
+ check_unique(d.info for d in found)
176
+ undeclared = [d.info.id for d in found if not d.info_declared]
177
+ errors = [f"{d.entry_point}: {d.error}" for d in found if d.error]
178
+
179
+ err = Console(stderr=True)
180
+ if as_json:
181
+ sys.stdout.write(json.dumps(registry, ensure_ascii=False, indent=2) + "\n")
182
+ else:
183
+ table = Table(title=f"Registro de fetchers ({len(found)})")
184
+ for col in (
185
+ "Id",
186
+ "Apelidos",
187
+ "Órgão",
188
+ "Cadência",
189
+ "Redistrib.",
190
+ "Frescor",
191
+ "Info",
192
+ "Lake",
193
+ ):
194
+ table.add_column(col)
195
+ for d, row in zip(
196
+ sorted(found, key=lambda d: (d.info.id, d.entry_point)),
197
+ registry["fetchers"],
198
+ strict=True,
199
+ ): # mesma ordenação de build_export
200
+ table.add_row(
201
+ d.info.id,
202
+ ", ".join(d.info.aliases) or "-",
203
+ d.info.orgao or "-",
204
+ d.info.cadencia or "-",
205
+ d.info.redistribuicao or "-",
206
+ d.freshness_policy or "-",
207
+ "[green]sim[/green]" if d.info_declared else "[yellow]não[/yellow]",
208
+ "sim" if row["lake"] else "-",
209
+ )
210
+ Console().print(table)
211
+ if duplicate:
212
+ err.print(f"[red]Duplicidade:[/red] {duplicate}", markup=True)
213
+ for line in errors:
214
+ err.print(f"[red]Falha ao carregar[/red] {line}", markup=True, highlight=False)
215
+ if undeclared:
216
+ err.print(
217
+ f"[yellow]{len(undeclared)} fetcher(s) sem info declarada:[/yellow] "
218
+ + ", ".join(sorted(undeclared)),
219
+ markup=True,
220
+ highlight=False,
221
+ )
222
+ if strict and (duplicate or undeclared or errors):
223
+ raise typer.Exit(1)
224
+
225
+
226
+ def declared_source_names() -> dict[str, str]:
227
+ """Mapa ``id/apelido -> distribuição`` dos fetchers instalados que declaram info."""
228
+ names: dict[str, str] = {}
229
+ for d in discover_fetchers():
230
+ if d.info_declared and d.distribution:
231
+ for name in d.info.names:
232
+ names[name] = d.distribution
233
+ return names
@@ -12,6 +12,7 @@ import email.utils
12
12
  import inspect
13
13
  import json
14
14
  import os
15
+ import re
15
16
  import threading
16
17
  import time
17
18
  from collections.abc import Callable, Iterable
@@ -33,6 +34,7 @@ from quantilica.core.http import (
33
34
  )
34
35
  from quantilica.core.logging import get_logger
35
36
  from quantilica.core.manifests import manifest_sidecar_path
37
+ from quantilica.core.registry import FetcherInfo
36
38
  from quantilica.core.storage import (
37
39
  StampedDataRepository,
38
40
  expected_format_for_path,
@@ -55,7 +57,20 @@ from quantilica.cli.ui import (
55
57
 
56
58
  logger = get_logger(__name__)
57
59
 
60
+
61
+ def derive_fetcher_info(name: str) -> FetcherInfo:
62
+ """Deriva um :class:`FetcherInfo` mínimo do nome do fetcher.
63
+
64
+ Usado quando o fetcher ainda não declara ``info``: o id é o ``name`` sem o
65
+ sufixo ``-fetcher``, normalizado (``bcb_sgs-fetcher`` -> ``bcb-sgs``).
66
+ """
67
+ slug = re.sub(r"[^a-z0-9]+", "-", name.lower().removesuffix("-fetcher"))
68
+ slug = slug.strip("-") or "fetcher"
69
+ return FetcherInfo(id=slug, nome=slug)
70
+
71
+
58
72
  __all__ = [
73
+ "derive_fetcher_info",
59
74
  "CheckPlan",
60
75
  "CheckPlanItem",
61
76
  "DataRepository",
@@ -469,6 +484,9 @@ class FetcherApp:
469
484
  source_id: Source ID recorded in download manifests. Defaults to
470
485
  ``name`` without the ``-fetcher`` suffix. When ``default_output``
471
486
  is omitted it is derived as ``/data/{source_id}``.
487
+ info: Fatos da fonte (:class:`~quantilica.core.registry.FetcherInfo`).
488
+ Sem ele, um ``FetcherInfo`` mínimo é derivado de ``name`` e
489
+ ``info_declared`` fica ``False`` (compatibilidade com fetchers antigos).
472
490
  build_default_commands: If True (default), registers the built-in
473
491
  ``sync`` and ``list`` commands. Set to False to register only
474
492
  custom commands via :meth:`attach_command`.
@@ -489,6 +507,7 @@ class FetcherApp:
489
507
  source_id: str | None = None,
490
508
  client: HttpClient | FtpClient | None = None,
491
509
  freshness_policy: Any = None,
510
+ info: FetcherInfo | None = None,
492
511
  build_default_commands: bool = True,
493
512
  ):
494
513
  self.name = name
@@ -503,6 +522,8 @@ class FetcherApp:
503
522
  self.default_output = default_output or Path(f"/data/{self.source_id}")
504
523
  self.client = client or default_client()
505
524
  self.freshness_policy = freshness_policy
525
+ self.info_declared = info is not None
526
+ self.info: FetcherInfo = info or derive_fetcher_info(name)
506
527
 
507
528
  self.all_group_keys = list(self.groups.keys())
508
529
  self.all_keys = self.all_group_keys + list(self.aliases.keys())
@@ -510,6 +531,9 @@ class FetcherApp:
510
531
 
511
532
  # O objeto typer principal
512
533
  self.app = typer.Typer(help=help)
534
+ # O entry point `quantilica.fetchers` aponta para o Typer; este atributo
535
+ # deixa `quantilica registry export` chegar ao FetcherApp.
536
+ self.app.fetcher_app = self # type: ignore[attr-defined]
513
537
  if build_default_commands:
514
538
  self._build_commands()
515
539
 
@@ -287,9 +287,31 @@ def reexec_cli(args: list[str]) -> None:
287
287
  os.execv(sys.executable, [sys.executable, "-m", "quantilica.cli.cli", *args])
288
288
 
289
289
 
290
+ def installed_declared_names() -> dict[str, str]:
291
+ """Ids e apelidos dos fetchers instalados que declaram ``FetcherInfo``.
292
+
293
+ Mapeia ``id/apelido -> distribuição``. Falhas na descoberta não impedem o
294
+ uso da tabela manual.
295
+ """
296
+ try:
297
+ from quantilica.cli.registry import declared_source_names
298
+
299
+ return declared_source_names()
300
+ except Exception: # pragma: no cover - a reserva manual cobre
301
+ return {}
302
+
303
+
290
304
  def _merged_registry() -> dict[str, str]:
291
- """Combina o registro remoto (sources.json) com o local; o local tem precedência."""
292
- return {**fetch_remote_sources(), **SOURCES_REGISTRY}
305
+ """Combina o registro remoto, a tabela manual e o ``FetcherInfo`` instalado.
306
+
307
+ A tabela manual (``SOURCES_REGISTRY``) é a reserva para instalar fontes
308
+ ausentes; para o que está instalado, id e apelidos do ``FetcherInfo`` mandam.
309
+ """
310
+ return {
311
+ **fetch_remote_sources(),
312
+ **SOURCES_REGISTRY,
313
+ **installed_declared_names(),
314
+ }
293
315
 
294
316
 
295
317
  _EXTRA_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
@@ -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
@@ -0,0 +1,189 @@
1
+ """Testes de `quantilica registry export` e da compatibilidade do FetcherApp."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from types import SimpleNamespace
7
+
8
+ import pytest
9
+ from quantilica.core.registry import FetcherInfo
10
+ from typer.testing import CliRunner
11
+
12
+ from quantilica.cli import registry as reg
13
+ from quantilica.cli import sources
14
+ from quantilica.cli.registry import app
15
+ from quantilica.cli.sdk import FetcherApp, derive_fetcher_info
16
+
17
+ runner = CliRunner()
18
+
19
+
20
+ def _fetcher(name: str, info: FetcherInfo | None = None, **kw) -> FetcherApp:
21
+ return FetcherApp(
22
+ name,
23
+ groups_dict={"g1": {"name": "g1"}, "g0": {"name": "g0"}},
24
+ aliases_dict={},
25
+ list_datasets=lambda g: [],
26
+ client=object(), # type: ignore[arg-type]
27
+ info=info,
28
+ **kw,
29
+ )
30
+
31
+
32
+ def _ep(name: str, obj, dist: str | None = None, boom: bool = False):
33
+ def load():
34
+ if boom:
35
+ raise ImportError("quebrado")
36
+ return obj
37
+
38
+ d = SimpleNamespace(name=dist) if dist else None
39
+ return SimpleNamespace(name=name, dist=d, load=load)
40
+
41
+
42
+ @pytest.fixture
43
+ def fake_eps(monkeypatch: pytest.MonkeyPatch):
44
+ def install(fetchers=(), lake=()):
45
+ def fake(group: str):
46
+ return {
47
+ "quantilica.fetchers": list(fetchers),
48
+ "quantilica.lake": list(lake),
49
+ }[group]
50
+
51
+ monkeypatch.setattr(reg, "entry_points", fake)
52
+
53
+ return install
54
+
55
+
56
+ def test_sem_info_deriva_do_name():
57
+ f = _fetcher("tesouro-direto-fetcher")
58
+ assert f.info_declared is False
59
+ assert f.info.id == "tesouro-direto" and f.info.nome == "tesouro-direto"
60
+ assert f.source_id == "tesouro-direto"
61
+ assert derive_fetcher_info("bcb_sgs-fetcher").id == "bcb-sgs"
62
+ assert f.app.fetcher_app is f
63
+
64
+
65
+ def test_com_info_declarada_e_source_id_independente():
66
+ info = FetcherInfo("tesouro-direto", nome="Tesouro Direto", aliases=("td",))
67
+ f = _fetcher("tddata-fetcher", info=info, source_id="td")
68
+ assert f.info_declared is True and f.info is info
69
+ assert f.source_id == "td"
70
+
71
+
72
+ def test_export_json(fake_eps):
73
+ info = FetcherInfo(
74
+ "tesouro-direto", nome="Tesouro Direto", aliases=("td",), cadencia="daily"
75
+ )
76
+ a = _fetcher("tesouro-direto-fetcher", info=info, freshness_policy="remote_only")
77
+ b = _fetcher("anp-fetcher")
78
+ fake_eps(
79
+ fetchers=[
80
+ _ep("td", a.app, "tesouro-direto-fetcher"),
81
+ _ep("anp", b.app, "anp-fetcher"),
82
+ _ep("morto", None, "morto-fetcher", boom=True),
83
+ ],
84
+ lake=[_ep("tesouro-direto", object(), "tesouro-direto-fetcher")],
85
+ )
86
+ res = runner.invoke(app, ["export", "--json"])
87
+ assert res.exit_code == 0
88
+ data = json.loads(res.stdout)
89
+ assert data["version"] == 1
90
+ assert [f["id"] for f in data["fetchers"]] == ["anp", "morto", "tesouro-direto"]
91
+ anp, morto, td = data["fetchers"]
92
+ assert td["info_declared"] is True and td["aliases"] == ["td"]
93
+ assert td["lake"] is True and td["lake_source_id"] == "tesouro-direto"
94
+ assert td["entry_point"] == "td" and td["freshness_policy"] == "remote_only"
95
+ assert td["groups"] == ["g0", "g1"] and td["cadencia"] == "daily"
96
+ assert anp["info_declared"] is False and anp["lake"] is False
97
+ assert "ImportError" in morto["error"]
98
+
99
+
100
+ def test_export_tabela(fake_eps):
101
+ fake_eps(fetchers=[_ep("anp", _fetcher("anp-fetcher").app, "anp-fetcher")])
102
+ res = runner.invoke(app, ["export"])
103
+ assert res.exit_code == 0
104
+ assert "anp" in res.stdout and "Registro de fetchers" in res.stdout
105
+
106
+
107
+ def test_strict_falha_sem_info(fake_eps):
108
+ fake_eps(fetchers=[_ep("anp", _fetcher("anp-fetcher").app, "anp-fetcher")])
109
+ assert runner.invoke(app, ["export", "--strict"]).exit_code == 1
110
+ assert runner.invoke(app, ["export"]).exit_code == 0
111
+
112
+
113
+ def test_strict_ok_com_info_e_duplicidade_falha(fake_eps):
114
+ def decl(i: str, aliases=()):
115
+ info = FetcherInfo(i, nome=i, aliases=aliases)
116
+ return _fetcher(f"{i}-fetcher", info=info).app
117
+
118
+ fake_eps(fetchers=[_ep("a", decl("a"), "a-fetcher")])
119
+ assert runner.invoke(app, ["export", "--strict", "--json"]).exit_code == 0
120
+
121
+ fake_eps(
122
+ fetchers=[
123
+ _ep("a", decl("a"), "a-fetcher"),
124
+ _ep("b", decl("b", aliases=("a",)), "b-fetcher"),
125
+ ]
126
+ )
127
+ res = runner.invoke(app, ["export", "--strict", "--json"])
128
+ assert res.exit_code == 1
129
+ plain = runner.invoke(app, ["export", "--json"])
130
+ assert plain.exit_code == 0 and len(json.loads(plain.stdout)["fetchers"]) == 2
131
+
132
+
133
+ def test_fonte_instalada_usa_apelidos_do_info(fake_eps, monkeypatch):
134
+ info = FetcherInfo("tesouro-direto", nome="TD", aliases=("td", "tddata"))
135
+ fake_eps(
136
+ fetchers=[
137
+ _ep(
138
+ "td",
139
+ _fetcher("tesouro-direto-fetcher", info=info).app,
140
+ "tesouro-direto-fetcher",
141
+ ),
142
+ _ep("anp", _fetcher("anp-fetcher").app, "anp-fetcher"),
143
+ ]
144
+ )
145
+ names = reg.declared_source_names()
146
+ assert names == {
147
+ "tesouro-direto": "tesouro-direto-fetcher",
148
+ "td": "tesouro-direto-fetcher",
149
+ "tddata": "tesouro-direto-fetcher",
150
+ }
151
+ monkeypatch.setattr(sources, "fetch_remote_sources", lambda: {})
152
+ merged = sources._merged_registry()
153
+ assert merged["tddata"] == "tesouro-direto-fetcher"
154
+ assert merged["anp"] == "anp-fetcher" # reserva manual
155
+
156
+
157
+ def test_apelidos_do_info_instalado_nao_contradizem_a_tabela():
158
+ """Falha se um fetcher instalado apelida algo que a tabela manual aponta para outro pacote."""
159
+ names = reg.declared_source_names()
160
+ conflicts = {
161
+ n: (dist, sources.SOURCES_REGISTRY[n])
162
+ for n, dist in names.items()
163
+ if n in sources.SOURCES_REGISTRY and sources.SOURCES_REGISTRY[n] != dist
164
+ }
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