Mensagem do TypeError de extra_forbidden cita o metodo interno (cjsg_download) quando o usuario chamou o wrapper (cjsg)

[bdcdo]

Contexto

Identificado na review do PR #257 (wiring TJPE etapa 2 da #197), mas e cross-tribunal.

Quando um scraper segue o padrao "wrapper publico (cjsg) → metodo de download (cjsg_download) com a validacao via apply_input_pipeline_search", o method_name passado ao helper e o do metodo interno:

# courts/tjpe/client.py:54-56 (idem TJRN, TJBA, ...)
inp = apply_input_pipeline_search(
    InputCJSGTJPE,
    \"TJPEScraper.cjsg_download()\",  # ← interno, mesmo quando user chamou .cjsg
    ...
)

A mensagem resultante e:

>>> jus.scraper(\"tjpe\").cjsg(\"dano moral\", kwarg_inventado=\"x\")
TypeError: TJPEScraper.cjsg_download() got unexpected keyword argument(s): 'kwarg_inventado'

O usuario chamou cjsg, mas a mensagem fala de cjsg_download. Friccao leve de UX — o usuario pode ate procurar cjsg_download no codigo e ficar confuso por nao ter chamado.

Onde acontece

Mesmo padrao em:

• courts/tjpe/client.py:54-56
• courts/tjrn/client.py:165-167
• courts/tjba/client.py:103-105
• courts/tjap/client.py, courts/tjmt/client.py, courts/tjpa/client.py,
  courts/tjes/client.py, courts/tjgo/client.py, courts/tjmg/client.py,
  courts/tjpb/client.py, courts/tjrr/client.py, courts/tjrj/client.py,
  courts/tjrs/client.py, courts/tjsc/client.py, courts/tjto/client.py,
  courts/tjpr/client.py, courts/tjpi/client.py, courts/tjro/client.py,
  courts/tjmt/client.py, courts/tjdft/client.py

(grep apply_input_pipeline_search em src/juscraper/courts/.)

Opcoes de fix

1. Cosmetico — passar o nome do metodo publico (\"TJPEScraper.cjsg()\" em vez de \"TJPEScraper.cjsg_download()\"). Mas ai quando o usuario chamar cjsg_download diretamente a mensagem fica errada no outro sentido.
2. Detectar caller frame com inspect.stack() — funciona mas e fragil e adiciona custo a cada validacao.
3. Adicionar parametro method_name em cjsg_download (com default = \"<TJxx>.cjsg_download()\") e o wrapper cjsg passa o seu proprio nome. Mudanca pequena, propaga bem entre tribunais, sem magia.
4. Mover a validacao para o wrapper (cjsg), pular em cjsg_download quando ja validado — mas se cjsg_download for chamado direto, valida la. Da pra fazer com flag _skip_validation, mas vira tres jeitos de validar.

Sugestao: opcao (3). Eh um refactor mecanico, sem mudanca de comportamento alem da mensagem.

Out of scope

• Mudar o formato da mensagem de erro de raise_on_extra_kwargs (o \"got unexpected keyword argument(s)\" esta canonizado em tests/_helpers.py::assert_unknown_kwarg_raises).
• Tocar em endpoints que ja sao um metodo so (TJSP cjsg/cjpg, ComunicaCNJ, DataJud — la o wrapper nao existe).

Refs

• Identificada em feat(tjpe): wirar InputCJSGTJPE em cjsg/cjsg_download (#197 etapa 2) #257 (TJPE etapa 2 da track(tjpe): contratos + wiring + refactor — etapas em PRs separados #197), observacao 2 da review.
• tests/_helpers.py::assert_unknown_kwarg_raises so checa o nome do kwarg via regex, entao o fix nao quebra contratos existentes.

[bdcdo]

Alternativa: tornar cjsg_download / cjsg_parse privados em vez do fix mecânico

Revendo a #263 antes de implementar. A opção 3 resolve o sintoma — passar o nome do método público ao apply_input_pipeline_search — mas mantém cjsg_download na API pública só para, na prática, o usuário nunca chamá-lo direto.

Levanto uma alternativa de raiz: tornar cjsg_download e cjsg_parse privados (_cjsg_download / _cjsg_parse), deixando cjsg como único método público. Sem wrapper exposto, a ambiguidade do nome no TypeError some sem precisar threadar method_name.

O custo é que o split cjsg / cjsg_download / cjsg_parse hoje é decisão arquitetural documentada, não acidente:

• CONTRIBUTING.md (Adding an eSAJ tribunal): "O scraper herda cjsg, cjsg_download, cjsg_parse".
• CLAUDE.md tem uma seção inteira de padrão de docstring para cjsg_download / cjpg_download como métodos públicos, com a regra do :meth: fiscalizada por test_docstring_parity.py::test_download_docstring_references_toplevel (4 casos).
• docs/api-conventions.qmd usa cjsg_download(...) em exemplos.
• A base EsajSearchScraper expõe os três, herdados por 6 tribunais da família eSAJ.

O valor de expor *_download / *_parse: re-parsear sem re-baixar (debug de parser, captura de samples) e a própria pirâmide de testes *_download / *_parse. Pode ser que ninguém use de fato — mas tornar privado é breaking e reverte a decisão em ~21 clients + base eSAJ + docs + testes.

@jtrecenti — antes de eu seguir, qual caminho prefere?

1. Opção 3 (mecânica) como a issue propõe — fix pequeno, não-breaking, mantém o split.
2. Colapsar a API — _cjsg_download / _cjsg_parse privados, cjsg único público. Resolve a Mensagem do TypeError de extra_forbidden cita o metodo interno (cjsg_download) quando o usuario chamou o wrapper (cjsg) #263 de raiz, mas é breaking e exige atualizar a doc/teste do padrão de docstring.

Inclino a que (2), se for o caminho, vire issue própria — a #263 some como efeito colateral, mas a discussão real ("queremos a API de três métodos?") é maior que o escopo original.