fn_registry/python/functions/infra/oo_bridge_send.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, tested, tests, test_file_path, file_path, params, output

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path	params	output
oo_bridge_send	function	py	infra	1.0.0	impure	def oo_bridge_send(cmd: str, ref: str = '', text: str = '', opts: dict = None, target: str = 'cell', port: int = 8791, wait_s: float = 6.0) -> dict	Cliente programatico del puente OnlyOffice (app onlyoffice_bridge): encola un comando de la Automation API contra el documento OnlyOffice Desktop abierto y en foco, hace polling del resultado y lo devuelve como dict no-throw ({status: ok, result} o {status: error, error}). Lee y edita en vivo hojas (Cell), documentos (Word) y presentaciones sin cerrar/reabrir. Solo stdlib.	onlyoffice bridge live-edit http automation spreadsheet infra				false	error_go_core	json time urllib.request urllib.error	false			python/functions/infra/oo_bridge_send.py	name desc cmd Nombre del comando de la Automation API. Cell lectura: get_cell, get_range, get_formula, get_used_range, get_sheets. Cell escritura: set_cell, set_range, set_formula. Estructura: insert_rows, delete_rows, insert_cols, delete_cols, merge, add_sheet, rename_sheet, delete_sheet, activate_sheet. Formato: set_format, set_borders, set_colwidth, set_rowheight. Datos: add_named_range, sort, autofilter. Graficos/tablas: add_chart, format_as_table, table_chart. Word: insert_text, get_text. name desc ref Referencia A1 o rango sobre la que actua el comando: celda ('B2'), rango ('A1:C10'), filas ('4:6' para insert_rows/delete_rows), columnas ('B:C' para insert_cols/delete_cols). Vacio para comandos sin ref (get_sheets, add_sheet, get_used_range, insert_text). name desc text Valor textual para comandos de escritura: valor de celda (set_cell), formula '=SUM(A1:A9)' (set_formula), nombre de hoja (add_sheet/rename_sheet/activate_sheet), texto a insertar (insert_text). Vacio para lecturas. name desc opts Dict con parametros extra segun el comando. values (matriz 2D para set_range), sheet (hoja destino por nombre en cualquier comando cell, sin cambiar la activa), bold/italic/underline/fill=[r,g,b]/fontColor=[r,g,b]/numFormat/fontName/fontSize/wrap/alignH/alignV (set_format), style (set_borders), width (set_colwidth), height (set_rowheight), by/desc (sort), type/dataRange/pos (add_chart), dataRange/type (table_chart). None se trata como {}. name desc target Editor destino: 'cell' (Spreadsheet, por defecto), 'word' (Document), 'slide' (Presentation). El server enruta el comando al editor con foco que coincida. name desc port Puerto del server puente loopback (server.py). Default 8791. name desc wait_s Segundos de polling a /pull antes de devolver un error de timeout. Default 6.0. Subir si el editor tarda en responder comandos pesados (add_chart, set_range grande).	Dict no-throw. Exito: {'status': 'ok', 'result': <valor>} donde <valor> es lo que devuelve el plugin (string de celda, matriz 2D para get_range, lista de nombres de hoja para get_sheets, o 'ok' para escrituras). Error: {'status': 'error', 'error': <msg>} si el plugin devolvio {error:...}, si vencio el timeout (editor sin foco o plugin no arrancado), o si hubo fallo de red (server no corriendo). NUNCA lanza excepcion.

Ejemplo

import sys, os
sys.path.insert(0, os.path.join("python", "functions"))
from infra import oo_bridge_send

# Leer una celda de la hoja con foco
r = oo_bridge_send("get_cell", ref="B2")
print(r)                       # {'status': 'ok', 'result': '42'}

# Escribir una celda
oo_bridge_send("set_cell", ref="B2", text="123")

# Escritura batch 2D en un rango
oo_bridge_send("set_range", ref="D1:E2",
               opts={"values": [["a", 1], ["b", 2]]})

# Formula
oo_bridge_send("set_formula", ref="F1", text="=SUM(A1:A9)")

# Leer un rango entero (matriz 2D)
r = oo_bridge_send("get_range", ref="A1:C10")
for row in r["result"]:
    print(row)

# Listar hojas y crear una nueva
print(oo_bridge_send("get_sheets")["result"])   # ['Hoja1', 'Datos']
oo_bridge_send("add_sheet", text="Resumen")

# Formato: negrita + relleno + formato numerico, sobre otra hoja por nombre
oo_bridge_send("set_format", ref="A1:C1",
               opts={"bold": True, "fill": [230, 230, 250],
                     "numFormat": "0.00%", "sheet": "Datos"})

# Insertar 3 filas en la fila 4 / borrar columnas B y C
oo_bridge_send("insert_rows", ref="4:6")
oo_bridge_send("delete_cols", ref="B:C")

# Ordenar un rango por una columna, descendente
oo_bridge_send("sort", ref="A1:D20", opts={"by": "B1", "desc": True})

# Grafico de barras a partir de un rango
oo_bridge_send("add_chart",
               opts={"type": "bar", "dataRange": "A1:B10", "pos": [5, 1]})

# Word: insertar y leer texto
oo_bridge_send("insert_text", text="Nuevo parrafo", target="word")
print(oo_bridge_send("get_text", target="word")["result"])

Cuando usarla

Cuando necesites leer o editar EN VIVO un documento OnlyOffice Desktop ya abierto (hoja de calculo, documento o presentacion) sin cerrarlo ni reabrirlo — por ejemplo para rellenar celdas, aplicar formato, crear graficos o volcar una matriz calculada directamente sobre la ventana que el usuario tiene delante. Es el bloque de construccion de bajo nivel: un comando por llamada. Componla en pipelines o heredocs para secuencias (crear hoja -> volcar datos -> formatear cabecera -> anadir grafico). Prefierela sobre editar el .xlsx/.docx en disco (write_xlsx_sheets_py_infra, etc.) cuando el archivo esta abierto en OnlyOffice, porque el editor Desktop NO recarga cambios externos del disco (GitHub issue #2313).

Gotchas

• El editor debe estar ABIERTO y con la ventana en FOCO para que el plugin de sistema arranque y procese comandos. Si no hay foco en el editor destino, el polling vence y devuelve {"status": "error", "error": "timeout: ..."}. Abrir con open_onlyoffice_file_bash_shell y traer la ventana al frente antes de enviar.
• El server puente (apps/onlyoffice_bridge/server.py) debe estar corriendo en el puerto indicado (python3 apps/onlyoffice_bridge/server.py 8791 &, idealmente como service systemd --user). Si no corre, la funcion devuelve {"status": "error", "error": "push failed: ... (is server.py running ...)"}.
• Persistencia a disco = Ctrl+S del usuario. Estas ediciones ocurren sobre el documento vivo en memoria; el guardado automatizado es intermitente. Para dejar el cambio en el archivo, el usuario guarda con Ctrl+S (o usar save_onlyoffice_file_bash_shell, que no siempre confirma).
• Tablas nativas (ListObjects): solo se pueden CREAR con format_as_table. Este build de la Automation API NO soporta listar ni re-estilizar tablas nativas existentes — get_tables/set_table_style no devuelven datos utiles. Para visualizar datos tabulados usa rangos + set_format o crea la tabla de cero.
• La funcion NUNCA lanza: SIEMPRE inspecciona result["status"] antes de usar result["result"]. Un {"status": "ok", "result": None} significa que el plugin respondio vacio (comando aplicado sin valor de retorno).
• opts.sheet apunta a una hoja por nombre en cualquier comando cell sin cambiar la hoja activa; util para editar en segundo plano.
• Comandos pesados (set_range de miles de celdas, add_chart) pueden tardar mas de 6s; subir wait_s para esos casos.