Referencia de configuración

Configurar legal-expand

Todo lo que puedes ajustar en el paquete: opciones de expansión, formatos, configuración global, enriquecimiento del BOE y EUR-Lex, diccionarios propios y la CLI. Cero dependencias en tiempo de ejecución, type hints completos y compatible con Python 3.9 o superior.

Introducción

Instala el paquete desde PyPI:

pip install legal-expand

La expansión básica no necesita configuración: expandir_siglas(texto) devuelve el texto con cada sigla seguida de su significado entre paréntesis. A partir de ahí, cada función acepta un objeto de opciones para ajustar su comportamiento.

from legal_expand import expandir_siglas, ExpansionOptions

expandir_siglas('La AEAT revisa el IVA.')
# 'La AEAT (Agencia Estatal de Administración Tributaria) revisa el IVA (Impuesto sobre el Valor Añadido).'

Expansión de siglas

ExpansionOptions controla cómo se expanden las siglas. Se pasa como segundo argumento aexpandir_siglas() y funciones relacionadas.

Opción	Tipo	Defecto	Descripción
`format`	`'plain' \| 'html' \| 'structured'`	`'plain'`	Formato de salida: texto con la expansión entre paréntesis, HTML semántico con <abbr>, o salida estructurada con posiciones y estadísticas.
`force_expansion`	`bool \| None`	`None`	Fuerza (True) o desactiva (False) la expansión para esta llamada, por encima de la configuración global. None respeta la global.
`preserve_case`	`bool`	`True`	Mantiene mayúsculas/minúsculas de la variante detectada (AEAT, aeat, A.E.A.T.).
`expand_only_first`	`bool`	`False`	Expande solo la primera aparición de cada sigla; las siguientes se dejan intactas.
`exclude`	`list[str]`	`[]`	Siglas que nunca se expanden (por ejemplo, ["BOE"]).
`include`	`list[str] \| None`	`None`	Siglas que se expanden incluso si son palabras funcionales ("LA", "LO") normalmente omitidas.
`auto_resolve_duplicates`	`bool`	`False`	Resuelve automáticamente siglas con varios significados usando el contexto y la prioridad.
`duplicate_resolution`	`dict[str, str]`	`{}`	Mapa manual sigla → significado para forzar la resolución de ambigüedades concretas.
`custom_dictionaries`	`list[str]`	`[]`	Rutas a diccionarios propios (.json o .csv) que se añaden al base.

from legal_expand import expandir_siglas, ExpansionOptions

opts = ExpansionOptions(expand_only_first=True, exclude=['BOE'])
expandir_siglas('AEAT y BOE. AEAT otra vez.', opts)

Formatos de salida

El campo format de ExpansionOptions admite tres valores:

'plain' — texto con la expansión entre paréntesis (por defecto).
'html' — HTML semántico con etiquetas <abbr> y tooltips; el texto se escapa siempre.
'structured' — objeto con el texto expandido, la lista de siglas (con posiciones) y estadísticas.

html = expandir_siglas('La AEAT publica el IVA.', ExpansionOptions(format='html'))
datos = expandir_siglas('La AEAT publica el IVA.', ExpansionOptions(format='structured'))
datos.stats.total_acronyms_found  # 2

Configuración global

configurar_globalmente(GlobalConfig(...)) fija opciones por defecto para toda la aplicación, sin repetirlas en cada llamada. Recuerda resetear con resetear_configuracion() al terminar.

Opción	Tipo	Defecto	Descripción
`enabled`	`bool`	`True`	Activa o desactiva la expansión en toda la aplicación.
`default_options`	`ExpansionOptions \| None`	`None`	Opciones por defecto que se aplican cuando una llamada no las especifica.

from legal_expand import configurar_globalmente, resetear_configuracion, GlobalConfig, ExpansionOptions

configurar_globalmente(GlobalConfig(
    default_options=ExpansionOptions(format='html', expand_only_first=True),
))
# ... tu aplicación ...
resetear_configuracion()

Enriquecimiento BOE y EUR-Lex

enriquecer_boe(texto, BOEOptions(...)) detecta referencias normativas, enlaza cada norma (BOE para España, EUR-Lex para la UE) y, en modo online, descarga el texto íntegro del artículo citado. Es determinista: ante una cita ambigua no inventa, la marca para revisión.

Modos

'offline' — no consulta red. Resuelve normas por alias curados y por el índice del catálogo, y la normativa UE a su página de EUR-Lex por número CELEX.
'online' — además descarga el texto íntegro de los artículos (BOE y EUR-Lex).
'cache-first' — usa la caché local y solo va a la red cuando falta.

Opción	Tipo	Defecto	Descripción
`mode`	`'offline' \| 'cache-first' \| 'online'`	`'offline'`	offline no consulta red; online descarga el texto de los artículos; cache-first usa la caché y solo va a la red si falta.
`include_unit_text`	`bool`	`True`	Si es True y el modo consulta red, inserta el texto íntegro del artículo o anexo citado.
`use_boe_index`	`bool`	`True`	Resuelve cualquier norma española por su rango y número usando el índice local del catálogo consolidado (10.555 normas).
`use_curated_aliases`	`bool`	`True`	Usa los alias curados (LEC, CC, LECrim, Constitución…) además del índice.
`infer_single_active_norm`	`bool`	`True`	Si en un párrafo hay una sola norma inequívoca, asocia a ella las unidades citadas sin norma explícita.
`timeout_seconds`	`float`	`4.0`	Tiempo máximo por petición a las fuentes oficiales.
`max_results`	`int`	`5`	Máximo de candidatos a considerar al resolver una referencia.
`max_retries`	`int`	`2`	Reintentos ante errores de red transitorios.
`retry_backoff_seconds`	`float`	`0.5`	Espera base entre reintentos (crece de forma progresiva).
`cache_path`	`str \| None`	`None`	Carpeta de caché para las respuestas de BOE/EUR-Lex (modos cache-first y online).
`cache_ttl_days`	`int`	`30`	Días que se considera válida una respuesta cacheada.
`overrides_path`	`str \| None`	`None`	Ruta a un JSON de referencias manuales para corregir ambigüedades sin tocar el código.

from legal_expand import enriquecer_boe, BOEOptions

informe = enriquecer_boe(
    'El art. 14 de la Ley 39/2015 y el art. 6 del RGPD.',
    BOEOptions(mode='online', include_unit_text=True),
)
for ref in informe.references:
    print(ref.status, ref.original_text)

Diccionarios personalizados

Añade siglas propias sin tocar el diccionario base pasando rutas en custom_dictionaries. Se admite JSON (lista de entradas o un objeto con entries) y CSV con las mismas columnas. Cada entrada necesita al menos la sigla y su significado; el resto es opcional.

Campo	Alias admitidos	Descripción
`original`	`sigla`, `acronym`	La sigla (obligatorio).
`significado`	`meaning`, `expansion`	El significado completo (obligatorio).
`variants`	—	Variantes adicionales; lista o valores separados por coma/punto y coma.
`context_keywords`	`keywords`	Palabras de contexto para desambiguar significados.
`priority`	—	Prioridad al resolver conflictos (por defecto 100).
`source`	—	Origen de la entrada (informativo).

[
  {"original": "LXP", "significado": "Legal Expand Python", "variants": ["L.X.P."], "priority": 200}
]

from legal_expand import expandir_siglas, ExpansionOptions

opts = ExpansionOptions(custom_dictionaries=['mis_siglas.json'])
expandir_siglas('LXP junto a AEAT.', opts)

Interfaz de línea de comandos

Al instalar el paquete queda disponible el comando legal-expand:

Subcomando	Qué hace
`legal-expand expand`	Expande un archivo o la entrada estándar (stdin).
`legal-expand audit`	Audita un texto sin modificarlo: conocidas, desconocidas, omitidas, repetidas.
`legal-expand glossary`	Exporta el glosario de siglas de un texto (Markdown, CSV o JSON).
`legal-expand batch`	Procesa una carpeta completa de forma recursiva (.txt, .md, .html).
`legal-expand boe`	Detecta y enlaza referencias del BOE y EUR-Lex; con --mode online trae el articulado.
`legal-expand info`	Muestra la metadata del diccionario (número de siglas, versión, fuentes).
`legal-expand benchmark`	Mide el rendimiento de expansión sobre un texto.

Ejemplos

# Expandir un documento a HTML
legal-expand expand documento.txt --format html --output salida.html

# Auditar sin modificar el texto
legal-expand audit escrito.txt --report-format markdown

# BOE/EUR-Lex con el texto íntegro de los artículos
legal-expand boe escrito.txt --mode online --report-format markdown

# Procesar una carpeta completa
legal-expand batch ./entrada ./salida --format html

Los flags --include/--exclude aceptan listas separadas por comas y se pueden repetir. El subcomando boe admite --mode, --overrides, --cache-path y--no-unit-text, entre otros; consulta legal-expand boe --help.

← Volver a la página principal