Detectar alterações de numeração ao comparar arquivos Word em Python

Quando você compara dois arquivos Word e a única diferença está em como uma lista é numerada, por exemplo cláusulas que eram 1. e 2. agora são a. e b., ou uma lista numerada se transformou em uma com marcadores, o Aspose.Words não relata diferenças por padrão. Este tutorial mostra como detectar alterações de numeração ao comparar arquivos Word em Python. Ele também explica como revisar, aceitar ou rejeitar as alterações encontradas.

Principais pontos

• Por padrão, uma alteração no estilo de numeração ou no caractere de marcador de uma lista não gera revisões ao comparar arquivos Word.
• Definir options.advanced_options.compare_list_definitions = True relata cada parágrafo de lista afetado como uma revisão FORMAT_CHANGE.
• Alterações de texto dentro dos itens da lista são relatadas de qualquer forma. A opção apenas adiciona alterações de numeração e marcadores.
• ignore_formatting=True oculta alterações de numeração mesmo quando a opção está ativada.

Por que as alterações de numeração não são exibidas por padrão

Numeração e marcadores no Word vêm de uma definição de lista. Ela descreve como cada nível da lista aparece: o estilo de número (1., a., i.), o caractere de marcador e a formatação relacionada. Quando você compara documentos, Aspose.Words segue o Microsoft Word por padrão e deixa as definições de lista fora da comparação. Portanto, se apenas a numeração foi alterada, a comparação não detecta nada a relatar.

A opção compare_list_definitions não tem equivalente no Word. Ela informa ao Aspose.Words para incluir definições de lista na comparação. Aqui está o que vimos ao comparar listas de dois itens na versão 26.9:

A última linha é importante na prática. Ativar a opção não cria revisões extras para listas que são iguais em ambos os arquivos.

Pré-requisitos

Você precisa de Aspose.Words for Python via .NET 26.9 ou posterior. Instale ou atualize‑o a partir de PyPI:

pip install --upgrade "aspose-words>=26.9"

Sem uma licença, o Aspose.Words funciona no modo de avaliação com limitações. Uma licença temporária remove essas limitações enquanto você testa.

Veja a Diferença: Alterações de Numeração Com e Sem a Opção

O script a seguir cria dois documentos que contêm os mesmos dois itens. O primeiro usa uma lista numerada e o segundo usa uma lista com marcadores. Ele os compara duas vezes, uma vez com a opção desativada e outra com a opção ativada, para que você possa ver exatamente o que a opção altera.

import datetime
import aspose.words as aw

def build_list_document(bulleted: bool) -> aw.Document:
    """Create a two-item list, either numbered or bulleted."""
    doc = aw.Document()
    builder = aw.DocumentBuilder(doc=doc)
    if bulleted:
        builder.list_format.apply_bullet_default()
    else:
        builder.list_format.apply_number_default()
    builder.writeln("Item 1")
    builder.writeln("Item 2")
    builder.list_format.remove_numbers()
    return doc

def compare_lists(compare_list_definitions: bool) -> aw.Document:
    original = build_list_document(bulleted=False)
    edited = build_list_document(bulleted=True)

options = aw.comparing.CompareOptions()
    options.advanced_options.compare_list_definitions = compare_list_definitions

# compare() writes revisions into `original`; it returns nothing.
    original.compare(
        document=edited,
        author="Reviewer",
        date_time=datetime.datetime.now(),
        options=options,
    )
    return original

for flag in (False, True):
    result = compare_lists(flag)
    print(f"compare_list_definitions={flag}: {result.revisions.count} revision(s)")
    for revision in result.revisions:
        revision_type = aw.RevisionType(revision.revision_type).name
        text = revision.parent_node.get_text().strip()
        print(f"  {revision_type}: {text}")

result.save("compared-lists.docx")

Executando o script imprime:

compare_list_definitions=False: 0 revision(s)
compare_list_definitions=True: 2 revision(s)
  FORMAT_CHANGE: Item 1
  FORMAT_CHANGE: Item 2

Como o Código Funciona

• build_list_document usa DocumentBuilder.list_format para iniciar uma lista numerada ou com marcadores padrão, escreve dois itens e então chama remove_numbers() para que quaisquer parágrafos posteriores não façam parte da lista.
• CompareOptions.advanced_options expõe compare_list_definitions, que tem o padrão False.
• original.compare(...) compara original com edited e registra as diferenças como revisões dentro de original. O método retorna None, portanto sempre leia os resultados do documento no qual ele foi chamado.
• O parent_node de cada revisão é o parágrafo da lista cuja formatação foi alterada. revision_type é RevisionType.FORMAT_CHANGE para alterações de numeração e marcadores.

Detect Numbering Changes Between Two Word Files

Em um fluxo de trabalho real, você compara dois arquivos existentes, como duas versões de um contrato. Essas comparações geralmente contêm outras revisões também, portanto o script abaixo mantém apenas as alterações de formatação que estão em parágrafos de lista.

import datetime
import aspose.words as aw

original = aw.Document("contract-v1.docx")
edited = aw.Document("contract-v2.docx")

options = aw.comparing.CompareOptions()
options.advanced_options.compare_list_definitions = True

original.compare(edited, "Reviewer", datetime.datetime.now(), options)

# Keep only formatting revisions that sit on list paragraphs.
list_changes = [
    rev for rev in original.revisions
    if rev.revision_type == aw.RevisionType.FORMAT_CHANGE
    and rev.parent_node is not None
    and rev.parent_node.node_type == aw.NodeType.PARAGRAPH
    and rev.parent_node.as_paragraph().list_format.is_list_item
]

print(f"Total revisions: {original.revisions.count}")
print(f"Formatting changes on list paragraphs: {len(list_changes)}")
for rev in list_changes:
    print(f"  {rev.parent_node.get_text().strip()}")

original.save("contract-compared.docx")

Em nosso teste, a versão 2 do contrato mudou uma lista numerada para marcadores e também deixou uma frase não relacionada em negrito. A saída foi:

Total revisions: 5
Formatting changes on list paragraphs: 2
  Invoices are due in 30 days.
  Late fees apply after 45 days.

O filtro seleciona os dois itens da lista e ignora a alteração em negrito, porque essa revisão está no texto em vez de em um parágrafo da lista. Lembre‑se de que ele corresponde a qualquer alteração de formatação em nível de parágrafo em um item da lista, como uma mudança de recuo, não apenas à numeração. Verifique o documento salvo se precisar distinguir esses casos.

Revisar, Aceitar ou Rejeitar Alterações de Numeração

Como as alterações de numeração são revisões de formato comuns, você as trata da mesma forma que qualquer outra revisão:

• revisions.accept_all() aplica a formatação de lista editada. No primeiro exemplo, ambos os itens se tornam marcadores.
• revisions.reject_all() mantém a formatação original, de modo que os itens permanecem numerados 1. e 2..
• Salvar o documento grava as revisões como alterações rastreadas, permitindo que os revisores abram o arquivo no Microsoft Word e decidam sobre cada alteração eles mesmos.

Você também pode chamar accept() ou reject() em objetos individuais Revision, por exemplo, apenas nos itens da lista list_changes da seção anterior.

Quando Detectar Alterações de Numeração

Ative a opção quando a numeração de uma lista tem significado para seus revisores. Documentos legais e de políticas são um caso comum: renumerar cláusulas de 1. para (a) altera a forma como outros documentos as referenciam, portanto um revisor precisa vê‑la. Também é útil quando você migra documentos entre sistemas e deseja confirmar que a numeração da lista sobreviveu à transferência sem alterações.

Desative-o quando você se preocupa apenas com a redação. Revisões de conteúdo, verificações de tradução e diffs em nível de texto são mais fáceis de ler sem revisões de formatação misturadas.

Coisas a observar

• ignore_formatting substitui a opção. Se você definir options.ignore_formatting = True, as alterações de numeração não são relatadas, mesmo com compare_list_definitions = True.
• Os arquivos não devem conter revisões antes de compará-los. Se algum dos documentos já possuir alterações rastreadas, compare gera um RuntimeError informando que os documentos comparados não devem ter revisões. Aceite ou rejeite as revisões existentes primeiro. Isso também significa que você não pode executar uma segunda comparação em um documento que já contém os resultados da primeira; recarregue os arquivos a cada vez.
• Outras revisões ainda aparecem. Texto inserido ou excluído em um item de lista é relatado independentemente de a opção estar ativada ou desativada, portanto verifique revision_type se precisar separar alterações de numeração de alterações de texto.

Próximos passos

O artigo Comparar Documentos na documentação do Aspose.Words for Python cobre as outras configurações de comparação, incluindo granularidade, o alvo da comparação e as opções de ignorar.

Perguntas Frequentes

1. Por que o Aspose.Words não detecta alterações de numeração ao comparar arquivos Word? Por padrão, o Aspose.Words segue o Microsoft Word e deixa as definições de lista, como o estilo de numeração ou o caractere de marcador, fora da comparação. Uma lista que muda de números para marcadores não gera revisões, a menos que você habilite compare_list_definitions.

2. Como detectar alterações de numeração em Python? Crie CompareOptions, defina options.advanced_options.compare_list_definitions como True e passe as opções para Document.compare. Cada parágrafo de lista cuja numeração ou marcador foi alterado recebe uma revisão FORMAT_CHANGE.

3. Que tipo de revisão uma mudança de numeração cria? Cada parágrafo de lista afetado recebe uma revisão do tipo RevisionType.FORMAT_CHANGE. Aceitá‑la aplica a formatação de lista do arquivo editado, e rejeitá‑la mantém o original.

4. A opção funciona junto com ignore_formatting?
   Não. Quando CompareOptions.ignore_formatting é True, as alterações de numeração não são relatadas, mesmo se compare_list_definitions for True.

5. O que o Document.compare retorna? Nada. Ele grava as diferenças como revisões no documento em que você o chama, portanto você as lê da coleção revisions desse documento.

6. Qual versão do Aspose.Words for Python adicionou esta opção? A propriedade compare_list_definitions de AdvancedCompareOptions foi adicionada no Aspose.Words for Python via .NET 26.9.

Obtenha uma Licença Gratuita e Suporte

• Licença Temporária Gratuita
• Documentação
• Referência da API
• Fórum de Suporte do Aspose.Words