[matbrgz]

Spec 007: o dataset-names passa a usar o kit de fontes benchcommons-tools-dataset 0.1.0 (import datasettool, tag v0.1.0 do tools-dataset) e fica só com o código de nomes.

Refs BenchCommons/tools-dataset#5

Status: Em implementação.

O que mudou

• Dependência (ADR 0013): benchcommons-tools-dataset==0.1.0 com [tool.uv.sources] git fixado na tag v0.1.0; o uv.lock registra o commit f3251d8. pyyaml e xlrd saem das dependências diretas (o kit os fixa).
• Adaptadores: namescommons.adapters mantém RawRecord, RawLink e DEFAULT_PACKAGE, reexporta os objetos do kit (AdapterError, FormatError, Resource, SourceFiles, module_name, parse_count, parse_code) e embrulha load_adapter e check_adapter com optional=("links",).
• Planilhas: o adaptador do INE lê por datasettool.sources.spreadsheet (com a correção do PR fix(spreadsheet): close XLSX DTD pre-scan bypass via declared encodings #39).
• Cache: o pipeline chama datasettool.sources.cache.fetch_resource com namescommons.USER_AGENT, igual byte a byte ao anterior.
• Registro: namescommons.sources é um RegistrySchema com os campos de nomes (country, count_type, primary, suppression, uniform_case, strips_accents), as licenças do ADR 0001 (ATTRIBUTION_ONLY_LICENSES + statcan-open-licence) e a regra de uma primary; SourceError é o RegistryError do kit.
• Manifesto: describe_files do kit com contadores .csv e .parquet.
• Docs: spec, plano e tarefas em docs/specs/007-tools-dataset/, ADR 0013, nota no status do ADR 0005, AGENTS.md, seção Development do README.md, ROADMAP.md.

Arquivos e testes removidos (substitutos no tools-dataset v0.1.0, 360 testes verdes na tag)

• src/namescommons/cache.py -> datasettool.sources.cache
• src/namescommons/spreadsheet.py -> datasettool.sources.spreadsheet
• tests/test_cache.py (22 testes) -> tests/test_cache.py de lá
• tests/test_spreadsheet.py -> tests/test_spreadsheet.py de lá; test_r1_3_amostras_do_ine ficou aqui como test_leitor_do_kit_le_as_amostras_do_ine em tests/test_es_ine_residentes.py
• tests/fixtures/planilhas/tipos.xls -> tests/fixtures/spreadsheets/types.xls de lá (bytes idênticos)
• tests/test_manifest.py -> tests/test_files.py de lá
• Testes avulsos (lista exata no plano, seção "Removidos", e nas mensagens de commit): 6 em test_adapters.py, 7 em test_contrato_adaptador.py, 11 mais 3 casos em test_sources.py, 5 mais 1 caso em test_sources_extensoes.py, 1 em test_robustez.py

Critérios de aceite e verificação

1. uv sync --locked (também na CI) instala o kit da tag; tests/test_tools_dataset.py confere versão, tag, o commit f3251d805f1f7839e59c5472d54833ea7bef840d no uv.lock e o commit_id do pacote instalado (direct_url.json). git ls-remote da tag dá o mesmo commit, e git tag -v v0.1.0 mostra assinatura válida.
2. cache.py e spreadsheet.py não existem (testes test_namescommons_*_nao_existe); nenhum import yaml em src/.
3. uv run pytest -q: 586 verdes, sem rede.
4. Os dois passos offline da CI passam, e diff -r contra master (0153007) não mostra diferença (8 e 109 observações).
5. namescommons run --offline sobre o cache real completo: 4.336.051 observações, diff -r contra master sem diferença (89 s, 2,84 GB de pico).
6. tools/bench_pipeline.py --observacoes 200000: OK (1,5 s ingest, 1,3 s build, 261 MB); com --wikidata: OK (1.765 MB).
7. Lista de remoções acima e no plano.
8. Checklist de tools-dataset#5 marcado.

Diferenças aceitas (spec, R4.3): mensagens do kit em inglês; ordem das linhas numa mensagem do registro com vários erros (nenhum teste confere ordem); o cache recusa ids e nomes de arquivo inválidos; o manifesto recusa sufixo sem contador.

Decisões tomadas sozinho (com custo se estiverem erradas)

• Diferença nova encontrada: o cache do kit recusa links simbólicos (cached_path usa resolve()), mesmo com --offline e o arquivo presente. Registrei como item 5 de R4.3, troquei o link simbólico de tools/bench_pipeline.py --wikidata por link físico ou cópia, e abri cache: cached_path refuses symlinked cache entries tools-dataset#9 para o dono decidir. Custo: quem guardava arquivos baixados à mão como link simbólico no cache recebe ValueError até copiá-los.
• Reexportar os objetos do kit em namescommons.adapters em vez de trocar os imports dos nove adaptadores. Custo: uma camada fina a mais; trocar depois é mecânico.
• Mensagens de nomes ficam em português, as do kit em inglês, então algumas mensagens misturam as línguas (issue Língua das mensagens de erro depois da adoção do tools-dataset #40). Custo: só texto.
• parse_count sem invólucro: o campo padrão das mensagens passa de contagem a count. Custo: só texto de erro.
• SourceError = RegistryError para manter o nome usado pela CLI. Custo: nenhum.
• Testes de registro com campos de nomes ficaram aqui (o kit testa um espelho com lista fixa de países, não o esquema real com pycountry e strips_accents); saíram só os genéricos. Custo: alguns testes parecidos nos dois repositórios.
• pyyaml e xlrd fora das dependências diretas. Custo: se um módulo daqui voltar a importá-los, precisa declarar de novo.

Rodada de correções da revisão

• CI com uv sync --locked (README e AGENTS.md também), teste de test_ci.py atualizado.
• Commit completo da tag fixado no teste do uv.lock e conferido no pacote instalado.
• ADR 0013: passo de integridade (git ls-remote da tag contra o uv.lock, git tag -v), constantes VERSAO e COMMIT no procedimento, alinhado com AGENTS.md; consequência sobre o nome não registrado no PyPI (PyPI name benchcommons-tools-dataset is unregistered: reserve it or document uv-only installs tools-dataset#10).
• pyyaml==6.0.3 no grupo dev, porque os testes importam yaml.
• Opcional não feito: test_fetch_com_falha_nomeia_a_fonte em tests/test_cli_pipeline.py passa pela CLI (main), que não expõe backoff; o monkeypatch de datasettool.sources.cache.BACKOFF continua sendo o único caminho sem mudar a CLI.

Issues

• Criadas: Língua das mensagens de erro depois da adoção do tools-dataset #40 (língua das mensagens), cache: cached_path refuses symlinked cache entries tools-dataset#9 (links simbólicos no cache), PyPI name benchcommons-tools-dataset is unregistered: reserve it or document uv-only installs tools-dataset#10 (nome no PyPI).

🤖 Generated with Claude Code