feat(pubmed): processamento em lote (.zip) na CLI + registro como comando instalável

[Rossi-Luciano]

Nota: esta branch parte de feat/1234-pubmed-article-set-envelope (PR #1243, ainda não mergeado), porque depende de pipeline_pubmed_set para agrupar múltiplos artigos num único ArticleSet. O diff inclui os commits do #1243 até ele ser mergeado em master.

Este PR fecha a última sub-issue da quebra da #1226 — finaliza a solicitação original da issue-mãe.

O que esse PR faz?

A issue #1226 pede: "Utilitário de CLI: [...] aceitando argumentos de entrada (--input/-i) e saída (--output/-o), além de permitir o processamento em lote." Hoje pubmed_generator.py só processa um XML por vez e nem está registrado como comando instalável (diferente de pdf_generator, que já está).

• get_xml_trees_and_errors(path) (nova, testável isoladamente): usa packtools.sps.pid_provider.xml_sps_lib.get_xml_items, que já trata .xml ou .zip de forma transparente — é o mesmo componente usado pelo spsvalidator para iterar pacotes SciELO. Retorna a lista de xmltree válidos e a lista de erros por arquivo, para que um XML corrompido dentro de um .zip não derrube o lote inteiro.
• main() reescrito: usa pubmed.pipeline_pubmed_set (da Pubmed XML: adicionar envelope ArticleSet/FileHeader + DOCTYPE #1234) para gerar um único <ArticleSet> com um <Article> por XML de entrada (seja de um .xml só ou de todos os XMLs de um .zip). Avisos de arquivos com erro vão para stderr; exit code 1 só se nenhum artigo foi processado com sucesso.
• setup.py: registrado pubmed_generator=packtools.sps.formats.pubmed_generator:main em entry_points.console_scripts, no mesmo padrão de pdf_generator.

Onde a revisão poderia começar?

packtools/sps/formats/pubmed_generator.py (reescrito quase por completo) e a entrada nova em setup.py.

Como usar a funcionalidade

Depois de instalado (pip install -e . neste repo, ou após publicado o pacote), o comando fica disponível direto no terminal:

# um XML só
pubmed_generator -i artigo.xml -o saida.xml

# um pacote .zip com vários XMLs -> gera 1 ArticleSet com 1 Article por XML
pubmed_generator -i pacote.zip -o saida.xml

Sem instalar o pacote, funciona do mesmo jeito via python -m:

python -m packtools.sps.formats.pubmed_generator -i artigo.xml -o saida.xml
python -m packtools.sps.formats.pubmed_generator -i pacote.zip -o saida.xml

Se algum XML do .zip estiver corrompido, o utilitário não para o lote inteiro — processa os válidos e avisa no stderr quais falharam:

Aviso: falha ao processar corrupt.xml: Unable to get xml with pre StartTag: invalid element name...
Arquivo criado em: saida.xml (1 artigo(s), 1 erro(s))

Como testar localmente (passo a passo)

1. Ambiente:

   cd packtools
   source .venv/bin/activate  # ou seu virtualenv

2. Suíte automatizada:

   python -m pytest tests/sps/formats/test_pubmed.py tests/sps/formats/test_pubmed_generator.py -v

   Esperado: 67 passed (suíte combinada de todas as sub-issues da Implementar função e utilitário de CLI para conversão de SciELO XML (SPS 1.10) para PubMed XML #1226 já mergeadas neste branch + as 5 novas em test_pubmed_generator.py: XML único, .zip com 2 artigos, .zip com 1 artigo inválido + 1 válido, e 2 testes end-to-end via main()).

3. Rodar a CLI manualmente com artigos reais do repositório (não precisa instalar nada, roda com python -m):

   python3 - <<'PY'
   import tempfile, zipfile, os, subprocess, sys
   
   sample1 = "tests/samples/0034-7094-rba-69-03-0227.xml"
   sample2 = "tests/samples/example.xml"
   
   with tempfile.TemporaryDirectory() as tmp_dir:
       zip_path = os.path.join(tmp_dir, "package.zip")
       with zipfile.ZipFile(zip_path, "w") as zf:
           zf.write(sample1, arcname="article1.xml")
           zf.write(sample2, arcname="article2.xml")
   
       out_path = os.path.join(tmp_dir, "out.xml")
       subprocess.run(
           [sys.executable, "-m", "packtools.sps.formats.pubmed_generator", "-i", zip_path, "-o", out_path],
           check=True,
       )
       print(open(out_path, encoding="utf-8").read())
   PY

   Esperado: saída com <!DOCTYPE ArticleSet ...> + <ArticleSet> contendo 2 <Article>.

4. Validar contra a DTD oficial do PubMed (critério de aceitação original da Implementar função e utilitário de CLI para conversão de SciELO XML (SPS 1.10) para PubMed XML #1226: "O XML de saída gerado pela ferramenta deve ser validado com sucesso [...], retornando zero erros de DTD" — o validador web citado na issue-mãe não serve para este formato, ver comentário em Implementar função e utilitário de CLI para conversão de SciELO XML (SPS 1.10) para PubMed XML #1226):

   curl -o /tmp/PubMed.dtd https://dtd.nlm.nih.gov/ncbi/pubmed/in/PubMed.dtd
   python3 - <<'PY'
   from lxml import etree as ET
   dtd = ET.DTD("/tmp/PubMed.dtd")
   doc = ET.parse("<caminho do out.xml gerado no passo 3>")
   print("VALID:", dtd.validate(doc))
   for err in dtd.error_log:
       print(err)
   PY

   Resultado obtido nesta implementação: VALID: True, zero erros, tanto para o artigo único quanto para o lote de 2 artigos.

5. Testar resiliência a erro (um XML corrompido dentro do .zip não deve derrubar o lote):

   python3 - <<'PY'
   import tempfile, zipfile, os, subprocess, sys
   
   with tempfile.TemporaryDirectory() as tmp_dir:
       zip_path = os.path.join(tmp_dir, "package.zip")
       with zipfile.ZipFile(zip_path, "w") as zf:
           zf.write("tests/samples/0034-7094-rba-69-03-0227.xml", arcname="valid.xml")
           zf.writestr("corrupt.xml", "not valid xml at all <<<")
   
       out_path = os.path.join(tmp_dir, "out.xml")
       result = subprocess.run(
           [sys.executable, "-m", "packtools.sps.formats.pubmed_generator", "-i", zip_path, "-o", out_path],
           capture_output=True, text=True,
       )
       print("stdout:", result.stdout)
       print("stderr:", result.stderr)
       print("returncode:", result.returncode)
   PY

   Esperado: returncode == 0, 1 artigo processado, 1 erro reportado em stderr sem interromper o restante.

Algum cenário de contexto que queira dar?

Esta é a última sub-issue da quebra da #1226. Durante a validação end-to-end deste PR contra a DTD oficial, usando o artigo real tests/samples/example.xml, encontrei mais um bug (fora do escopo direto da #1241, mas que bloqueava a validação real do lote): um contrib desse artigo tem <given-names> sem <surname>, e a DTD do PubMed exige FirstName+LastName sempre juntos em Author — gerando Author inválido. Corrigi isso no PR #1245 (#1236), que já foi atualizado e re-testado; a #1246 (#1237) também foi atualizada para incorporar esse fix, já que reaproveita as mesmas funções.

Depois dessa correção, validei todos os 7 PRs combinados (#1243, #1244, #1245, #1246, #1247, #1248 e este) localmente — merge temporário de todas as branches, sem alterar nenhuma delas — e o resultado final é: 67 testes passando, VALID: True contra a DTD oficial tanto para artigos individuais quanto para o lote gerado via .zip, cobrindo todas as features implementadas na quebra da #1226 (ArticleSet, JournalTitle correto, Suffix/CollectiveName, GroupList, CopyrightInformation/CoiStatement, Object grant, e agora o processamento em lote).

Quais são tickets relevantes?

Closes #1241. Depende de #1243 (#1234). Relacionado a #1226 (issue-mãe, que esta PR finaliza a quebra de sub-issues).

Referências

• DTD oficial do PubMed: ArticleSet (Article+) — https://dtd.nlm.nih.gov/ncbi/pubmed/in/PubMed.dtd
• packtools.sps.pid_provider.xml_sps_lib.get_xml_items — componente já usado pelo spsvalidator para processar pacotes .xml/.zip