O módulo html.entities da biblioteca padrão do Python reúne tabelas que relacionam nomes de entidades HTML, caracteres Unicode e pontos de código. Ele é útil quando uma aplicação precisa entender referências como &, ©, ou ☃, gerar relatórios sobre entidades, validar conversões ou implementar ferramentas de processamento de texto.
O módulo não é um parser HTML completo e também não sanitiza conteúdo. Sua função principal é fornecer dados de referência. Para analisar tags, atributos e texto, use o guia de html.parser no Python. Para converter uma string inteira com referências HTML, normalmente html.unescape() é mais direto.
O que é uma entidade HTML
Entidades são representações textuais de caracteres. Em HTML, o caractere & inicia uma referência. A forma nomeada usa um identificador, como < para o sinal de menor. A forma numérica usa um ponto de código decimal ou hexadecimal, como < ou <.
Essas referências existem porque alguns caracteres têm significado especial na marcação ou são difíceis de digitar. Entretanto, nem todo caractere precisa ser transformado em entidade. HTML moderno e UTF-8 permitem representar diretamente a maioria dos símbolos. O uso correto depende do contexto em que o texto será inserido.
Os quatro dicionários do módulo
A documentação oficial apresenta quatro estruturas principais:
html.entities.html5: nomes definidos pelo padrão HTML5 e seus caracteres equivalentes.html.entities.name2codepoint: nomes HTML4 associados a pontos de código Unicode.html.entities.codepoint2name: caminho inverso, do ponto de código para um nome HTML4.html.entities.entitydefs: definições de entidades XHTML 1.0 em texto de substituição.
Essas tabelas não são idênticas. HTML5 possui um conjunto maior e algumas referências produzem mais de um caractere Unicode. Por isso, escolha a tabela conforme o padrão e o objetivo da aplicação.
Consultando entidades HTML5
from html.entities import html5
print(html5["copy;"])
print(html5["nbsp;"])
print(html5["NotEqualTilde;"])
As chaves de html5 normalmente incluem o ponto e vírgula final. Algumas referências aceitas pelo padrão também aparecem sem ;. Não remova esse caractere de forma automática ao procurar uma chave, porque a ausência pode alterar a interpretação em determinados contextos.
O valor pode conter um ou vários caracteres. Portanto, não presuma que len(valor) sempre será um. Essa diferença importa ao calcular posições, limitar tamanho, destacar texto ou gerar mapeamentos reversos.
Listando entidades por nome
from html.entities import html5
prefixo = "copy"
resultados = {
nome: valor
for nome, valor in html5.items()
if nome.lower().startswith(prefixo)
}
for nome, valor in resultados.items():
print(nome, repr(valor))
Essa técnica é útil para construir documentação, autocompletar em editores ou ferramentas educativas. Em aplicações web, limite a quantidade retornada e não transforme nomes fornecidos pelo usuário em HTML sem escape adequado.
HTML4 com name2codepoint
from html.entities import name2codepoint
codigo = name2codepoint["euro"]
caractere = chr(codigo)
print(codigo)
print(caractere)
name2codepoint retorna inteiros. A função chr() converte o ponto de código em uma string Unicode. O caminho inverso existe em codepoint2name:
from html.entities import codepoint2name
nome = codepoint2name.get(ord("©"))
print(nome)
Use get() quando a ausência de um nome for esperada. Muitos caracteres Unicode não possuem uma entidade HTML4 nomeada. Nesse caso, a aplicação pode manter o caractere, produzir uma referência numérica ou usar uma política de fallback.
Criando uma referência numérica
def referencia_decimal(caractere: str) -> str:
if len(caractere) != 1:
raise ValueError("Informe exatamente um caractere")
return f"&#{ord(caractere)};"
print(referencia_decimal("☃"))
Para hexadecimal, use f"&#x{ord(caractere):X};". Referências numéricas são mais gerais do que nomes, mas ainda devem ser geradas conforme o contexto. Transformar todos os caracteres em referências aumenta o tamanho e dificulta a leitura sem necessariamente melhorar a segurança.
Quando usar html.escape e html.unescape
O módulo html possui funções de alto nível. html.escape() protege caracteres especiais ao inserir texto em conteúdo HTML simples. html.unescape() interpreta referências nomeadas e numéricas conforme as regras HTML.
import html
texto = "Tom & Jerry <3 programação"
seguro = html.escape(texto)
original = html.unescape(seguro)
print(seguro)
print(original)
html.entities é mais apropriado quando você precisa consultar as tabelas, entender nomes específicos, gerar índices ou implementar uma transformação controlada. Para conversão comum de strings inteiras, prefira as funções prontas.
Decodificar não significa sanitizar
Esse é o erro mais importante. html.unescape("<script>") produz uma string que contém uma tag script. A função apenas converte referências; ela não verifica se o resultado é seguro para ser renderizado.
Se conteúdo não confiável será exibido como texto, faça escape no momento da saída. Se a aplicação permite um subconjunto de HTML, use uma biblioteca de sanitização com allowlist de tags e atributos. Nunca tente criar um sanitizador apenas removendo entidades, expressões regulares ou algumas palavras proibidas.
Entidades em atributos
O contexto de atributo possui regras próprias. Inserir um valor dentro de href, src, style ou manipuladores de eventos exige mais do que substituir < e >. URLs devem ser validadas quanto a esquema e origem. Atributos perigosos não devem ser permitidos em conteúdo fornecido pelo usuário.
Ao trabalhar com URLs, use o artigo de urllib.parse no Python para decompor componentes, mas lembre-se de que parsing também não é validação completa.
Ponto e vírgula opcional
O HTML5 aceita algumas referências nomeadas sem o ponto e vírgula em condições específicas, principalmente por compatibilidade histórica. A tabela html5 pode conter versões com e sem ;. Ao gerar novo HTML, use a forma com ponto e vírgula. Ela é mais clara e reduz ambiguidades com letras e números que aparecem logo depois.
from html.entities import html5
print("amp;" in html5)
print("amp" in html5)
Ao analisar conteúdo existente, deixe um parser compatível aplicar as regras. Não tente dividir a string apenas procurando & e o próximo ;, pois documentos reais podem conter casos incompletos ou ambíguos.
Valores com múltiplos caracteres
Algumas entidades HTML5 representam sequências Unicode. Um processamento que assume relação um-para-um pode cortar o valor ou gerar um índice incorreto. Use strings completas e teste entidades complexas.
from html.entities import html5
for nome, valor in html5.items():
if len(valor) > 1:
print(nome, [f"U+{ord(c):04X}" for c in valor])
break
Isso também afeta normalização Unicode. Dois textos visualmente semelhantes podem ter sequências diferentes. Para comparar identificadores ou pesquisar conteúdo, avalie unicodedata.normalize(), abordado no guia de unicodedata no Python.
Construindo um catálogo de entidades
from html.entities import html5
catalogo = []
for nome, valor in sorted(html5.items()):
catalogo.append({
"nome": nome,
"texto": valor,
"codepoints": [f"U+{ord(c):04X}" for c in valor],
})
print(catalogo[:3])
Esse catálogo pode ser exportado para JSON, CSV ou uma página de documentação. Ao gerar HTML, faça escape tanto do nome quanto do valor. Mesmo dados vindos da biblioteca padrão devem passar pelo mecanismo correto de template para evitar que futuras mudanças no código introduzam uma saída insegura.
Tratando nomes desconhecidos
from html.entities import html5
def resolver(nome: str) -> str | None:
chave = nome if nome.endswith(";") else nome + ";"
return html5.get(chave)
print(resolver("copy"))
print(resolver("entidade_inexistente"))
Não substitua silenciosamente nomes desconhecidos por string vazia, pois isso pode causar perda de dados. Preserve a entrada, retorne None, registre um aviso ou rejeite conforme o contexto. Logs devem limitar tamanho e evitar conteúdo sensível.
Desempenho e memória
As tabelas já são carregadas como dicionários e consultas por chave são rápidas. Na maioria das aplicações, não há motivo para copiar todo o conteúdo repetidamente. Importe uma vez, reutilize as estruturas e crie índices adicionais apenas quando uma busca frequente realmente exigir.
Ao processar documentos grandes, não aplique substituições em cascata para cada entidade. Use html.unescape() ou um parser incremental. O artigo de html.parser mostra como alimentar dados em blocos.
Testes recomendados
Inclua entidades comuns, referências numéricas decimais e hexadecimais, nomes sem ponto e vírgula, valores com múltiplos caracteres, nomes desconhecidos, texto já escapado e entradas malformadas. Teste também a saída no contexto real: texto, atributo, JSON, log ou banco de dados.
Um teste deve verificar não apenas o caractere resultante, mas a política de segurança. Uma string corretamente decodificada pode continuar inadequada para renderização como HTML.
Erros comuns
Os erros frequentes são usar a tabela HTML4 quando o conteúdo exige HTML5, presumir que todo valor tem um caractere, esquecer o ponto e vírgula, substituir nomes desconhecidos sem aviso, usar unescape() como sanitizador, escapar cedo demais e depois escapar novamente, ou inserir o resultado em atributos e URLs sem validação contextual.
Conclusão
html.entities oferece acesso direto às relações entre nomes HTML e Unicode. Ele é ideal para catálogos, ferramentas de análise, conversores especializados e validações. Para tarefas comuns, combine o módulo com html.escape(), html.unescape() e um parser adequado.
Consulte a documentação oficial de html.entities e a lista de referências nomeadas do padrão HTML. Mantenha sempre a separação entre decodificar, analisar, validar e sanitizar.
