Criar função para completar pub-date com valores padrão

[Copilot]

Descrição

Implementa a função complete_pub_date que completa automaticamente elementos pub-date incompletos com valores padrão para dia e mês, garantindo que todos os artigos tenham datas de publicação completas e válidas.

Motivação

Durante o processo de migração, muitos artigos possuem elementos pub-date incompletos, contendo apenas o ano ou ano e mês. Esta função automatiza o preenchimento dessas datas com valores padrão configuráveis, facilitando o processo de migração e garantindo a conformidade com o schema SciELO Publishing Schema (SPS).

Mudanças Implementadas

Nova Função: complete_pub_date

Localização: /packtools/sps/utils/xml_fixer.py

Assinatura:

def complete_pub_date(xmltree, default_day=15, default_month=6)

Funcionalidades:

• ✅ Processa apenas elementos pub-date com pub-type='pub' ou publication-format='electronic'
• ✅ Adiciona elemento <month> quando ausente (valor padrão: 6)
• ✅ Adiciona elemento <day> quando ausente (valor padrão: 15)
• ✅ Mantém a ordem correta dos elementos (year, month, day)
• ✅ Valida que default_day está entre 1-31 e default_month entre 1-12
• ✅ Não modifica elementos day/month já existentes
• ✅ Retorna lista de mudanças realizadas com xpath, element_added e value

Exemplo de Uso

Antes:

<pub-date pub-type="pub">
  <year>2024</year>
</pub-date>

Código:

from lxml import etree
from packtools.sps.utils.xml_fixer import complete_pub_date

tree = etree.fromstring(xml)
changes = complete_pub_date(tree)
# Retorna: [
#   {'xpath': '/article/front/article-meta/pub-date', 'element_added': 'month', 'value': '6'},
#   {'xpath': '/article/front/article-meta/pub-date', 'element_added': 'day', 'value': '15'}
# ]

Após:

<pub-date pub-type="pub">
  <year>2024</year>
  <month>6</month>
  <day>15</day>
</pub-date>

Testes

Implementados 12 testes abrangentes cobrindo:

• ✅ pub-date completo (sem modificações)
• ✅ pub-date apenas com year
• ✅ pub-date com year e month
• ✅ Diferentes pub-types (pub, collection)
• ✅ pub-date com publication-format='electronic'
• ✅ Validação de valores inválidos (dia/mês fora do intervalo)
• ✅ Múltiplos elementos pub-date
• ✅ Preservação de outros elementos (season, etc)
• ✅ XPath nos registros de mudanças

Resultado: Todos os 12 testes passando ✅

Documentação

A função possui docstring completa em português com:

• Descrição detalhada da funcionalidade
• Documentação de parâmetros e retorno
• Documentação de exceções
• Exemplos de uso práticos

Referências

• JATS Tag Library - pub-date
• SciELO PS - Datas de publicação

Fixes #[issue-number]

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Criar função para completar pub-date com valores padrão</issue_title>
<issue_description>### Descrição da nova funcionalidade
Como operador da migração, eu quero uma função que complete automaticamente elementos pub-date incompletos com dia e mês padrão para que todos os artigos tenham datas de publicação completas e válidas.

Critérios de aceitação

• A função deve receber um xmltree e parâmetros opcionais default_day (padrão=15) e default_month (padrão=6)
• Deve processar apenas elementos pub-date com atributo pub-type='pub' ou publication-format='electronic'
• Deve adicionar elemento <day> com valor default_day quando ausente
• Deve adicionar elemento <month> com valor default_month quando ausente
• Deve validar que default_day está entre 1-31 e default_month entre 1-12, lançando ValueError se inválido
• Deve manter a ordem correta dos elementos: year, month, day
• Deve retornar lista de dicionários com campos: xpath, element_added, value
• Não deve modificar elementos day/month já existentes
• A função deve estar localizada em /packtools/sps/utils/xml_fixer.py
• Deve ter docstring completa com exemplos de uso
• Deve ter testes para: pub-date completo, só com year, com year e month, diferentes pub-types, valores inválidos

Anexos

Exemplo de XML antes:

<pub-date pub-type="pub">
  <year>2024</year>
</pub-date>

Exemplo de XML após:

<pub-date pub-type="pub">
  <year>2024</year>
  <month>6</month>
  <day>15</day>
</pub-date>

Assinatura da função:

def complete_pub_date(xmltree, default_day=15, default_month=6):
    """Completa pub-date com day e month quando ausentes."""

Referências

• JATS Tag Library - pub-date
• SciELO PS - Datas de publicação
  </issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #1038

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Rossi-Luciano]

Revisão Técnica - PR #1041

Verificação de Requisitos

Realizei revisão completa da implementação conforme especificação:

Requisito	Status	Observação
Assinatura: complete_pub_date(xmltree, default_day=15, default_month=6)	[OK]	Conforme especificado
Processar pub-type='pub' ou publication-format='electronic'	[OK]	XPath correto implementado
Adicionar <month> quando ausente	[OK]	Implementado com default_month
Adicionar <day> quando ausente	[OK]	Implementado com default_day
Validar default_day (1-31) e default_month (1-12)	[OK]	Lanca ValueError adequadamente
Manter ordem: year -> month -> day	[OK]	Insercao posicional correta
Retornar lista com xpath, element_added, value	[OK]	Estrutura de retorno conforme
Nao modificar elementos existentes	[OK]	Apenas adiciona quando ausente
Localizacao: /packtools/sps/utils/xml_fixer.py	[OK]	Arquivo no local correto
Docstring completa com exemplos	[OK]	Documentacao em portugues com 3 exemplos
Cobertura de testes	[OK]	12 testes implementados

Execução dos Testes

Comando executado:

python3 -m unittest tests.sps.utils.test_xml_fixer -v

Resultado:

test_complete_pub_date_already_complete ............................ ok
test_complete_pub_date_custom_defaults ............................. ok
test_complete_pub_date_ignores_other_pub_types ..................... ok
test_complete_pub_date_invalid_day ................................. ok
test_complete_pub_date_invalid_month ............................... ok
test_complete_pub_date_multiple_pub_dates .......................... ok
test_complete_pub_date_no_year ..................................... ok
test_complete_pub_date_only_year ................................... ok
test_complete_pub_date_preserves_other_elements .................... ok
test_complete_pub_date_with_publication_format_electronic .......... ok
test_complete_pub_date_xpath_in_changes ............................ ok
test_complete_pub_date_year_and_month .............................. ok

----------------------------------------------------------------------
Ran 12 tests in 0.007s

OK

Cobertura de Testes

Os testes cobrem todos os cenários especificados:

• [PASS] pub-date completo (não deve modificar)
• [PASS] Apenas <year> presente
• [PASS] <year> e <month> presentes
• [PASS] Diferentes pub-types (deve ignorar tipos não especificados)
• [PASS] Validação de valores inválidos (day e month)
• [PASS] Valores personalizados (default_day e default_month)
• [PASS] Múltiplos elementos pub-date
• [PASS] Elemento sem <year> (deve ignorar)
• [PASS] Preservação de outros elementos (ex: <season>)
• [PASS] Suporte a publication-format='electronic'
• [PASS] XPath no retorno das mudanças

Conclusão

Status: APROVADO

A implementação atende 100% dos requisitos especificados:

• Código limpo e bem estruturado
• Validações robustas
• Documentação completa em português
• 12/12 testes passando

---

Revisado por: @Rossi-Luciano
Data: 2024-11-21