Crear secuencias de órdenes Python con ScriptForge

Contenido

# Creating Python Scripts with ScriptForge

## Diferencias entre BASIC y Python

La biblioteca ScriptForge está disponible tanto para BASIC como para Python. La mayor parte de los servicios, los métodos y las propiedades actúan de idéntica manera en ambos lenguajes de programación. Sin embargo, debido a diferencias de funcionamiento entre ambos, los usuarios de ScriptForge deben estar al tanto de ciertas características de la biblioteca cuando se utiliza Python:

- Methods and Property names: In Python, all methods and properties can be used in lowercased, ProperCased or camelCased formats.

- Arguments: All keyword arguments passed on to methods are lowercased.

- Dates: All date objects are passed and returned as datetime.datetime native Python objects.

- Arrays: One-dimensional arrays are passed and returned as tuples (which is an immutable object). Two-dimensional arrays are passed and returned as tuples of tuples.

- None: Python's None keyword is equivalent to Basic's Null, Empty or Nothing.

- UNO objects: All UNO structures are exchanged between Basic and Python without any changes.

- Debugging: Whenever an error occurs in Python scripts that use ScriptForge, the error message provided by the Python execution stack displays the line of code that triggered the error. In Basic error messages do not display this information.

Visit LibreOffice Python Scripts Help for more information on Python scripting using LibreOffice.

## Editing Python scripts in IDEs

Python typing hints - relating to ScriptForge services public methods and properties - can be obtained from IDEs that support such facility. Visually, while editing a user script:

- hovering an object instance, a method or a property displays its detailed description.

- a "." after an object instance displays a drop-down box listing all available interfaces.

- brackets after a method-name start code-completion by displaying its arguments.

Typing hints are displayed when editing methods and properties with propercase letters.

## Ejecutar secuencias Python en LibreOffice

Depending on what you intend to achieve, you may choose one of the following approaches to running Python scripts in LibreOffice:

- Run Scripts inside the current LibreOffice process: Python scripts are executed from within the LibreOffice process by using the Tools - Macros - Run Macro menu or the APSO extension to call user scripts stored in the Python scripts folder. You can also use the APSO Python shell to interactively run Python scripts.

- Run Scripts separately from the LibreOffice process: Python scripts are executed from an external process that connects to an ongoing LibreOffice process using a pipe or a socket.

If you plan to run scripts from inside the LibreOffice process, it is recommended to install the APSO (Alternative Script Organizer for Python) extension. However, to develop Python scripts from outside LibreOffice, you can choose your preferred Python IDE.

### Ejecutar secuencias de órdenes dentro del proceso de LibreOffice

#### Usar la extensión APSO

La forma más sencilla de empezar a utilizar secuencias de órdenes Python en LibreOffice es instalando la extensión APSO. Una vez instalada, abra cualquier componente de LibreOffice y diríjase a Herramientas ▸ Macros ▸ Organizar secuencias de Python.

In APSO's main window go to Menu - Python Shell.

Alternatively you can open APSO using the default shortcut Alt + Shift + F11.

Ahora puede empezar a escribir órdenes de Python y el intérprete mostrará el resultado correspondiente tras la ejecución de cada renglón de código.

Para empezar a utilizar la biblioteca ScriptForge, debe importar el método CreateScriptService, con el que podrá acceder a los servicios que ofrece la biblioteca. En el ejemplo siguiente se utiliza el servicio Basic para mostrar un cuadro de mensaje.

            from scriptforge import CreateScriptService
            bas = CreateScriptService("Basic")
            bas.MsgBox("Hello!")

Para ejecutar el ejemplo anterior, introduzca los renglones de código en el intérprete de Python, uno por uno, presionando la tecla Intro después de escribir cada renglón.

Ahora ya puede empezar a ejecutar órdenes de Python utilizando cualquiera de los servicios de ScriptForge. Por ejemplo, el fragmento de código que aparece a continuación utiliza el servicio UI para crear un documento en blanco en Writer.

            ui = CreateScriptService("UI")
            doc = ui.CreateDocument("Writer")

#### Crear archivos de secuencias de órdenes en Python

Puede crear sus propios archivos Python y editarlos con su editor de texto preferido. Más adelante, podrá llamarlos desde cualquier componente de LibreOffice.

El primer paso es localizar dónde se guardan sus secuencias de órdenes de usuario. Para ello, consulte la página de ayuda Organización y ubicación de las secuencias de órdenes de Python.

Ahora puede crear un archivo de texto dentro de la carpeta de secuencias de órdenes de usuario de Python, por ejemplo, my_script.py, y empezar a escribir sus secuencias de órdenes.

A continuación se muestra un ejemplo sencillo que obtiene el valor numérico de una celda de Calc y lo incrementa en 1. Solo tiene que escribir el código siguiente en el archivo my_script.py.

        from scriptforge import CreateScriptService
        doc = CreateScriptService("Calc")

        def increment_cell(args=None):
            value = doc.GetValue("A1")
            value += 1
            doc.SetValue("A1", value)

        g_exportedScripts = (increment_cell, )

En este ejemplo se crea la función increment_cell. Observe que g_exportedScripts es una tupla que indica qué funciones se mostrarán en LibreOffice como secuencias de órdenes de usuario.

Para ejecutar esta secuencia de órdenes desde un documento de Calc:

1. Cree o abra un archivo de Calc.

2. Introduzca un valor numérico en la celda «A1» de la hoja actual.

3. Vaya a Herramientas ▸ Macros ▸ Ejecutar macros.

4. Choose My Macros - my_script in the library selector. Then choose the increment_cell function under the Macro Name list.

5. Click Run. Note that the value in cell "A1" was incremented by 1.

You can also use APSO to run Python scripts in a similar manner:

1. Primero abra APSO yendo a Herramientas ▸ Macros ▸ Organizar secuencias de Python.

2. In the macro list, navigate to My Macros - my_script - increment_cell.

3. Pulse en Ejecutar.

### Ejecutar secuencias de órdenes separadas del proceso de LibreOffice

#### Determinar la ruta de instalación

El primer paso para ejecutar secuencias de órdenes desde un proceso independiente es localizar la carpeta en la que está instalado LibreOffice. Hay varias formas de hacerlo, pero ScriptForge ofrece una forma rápida de identificar la ruta de instalación. Para ello, abra el intérprete de Python de APSO y escriba:

          from scriptforge import CreateScriptService
          fs = CreateScriptService("FileSystem")
          fs.FileNaming = "SYS"
          inst_dir = fs.InstallFolder
          print(inst_dir)

El resultado del código anterior es el directorio base en el que está instalado LibreOffice. Ahora debe añadir la subcarpeta «program» a la ruta resultante. Esta es la carpeta base desde la que ejecutará las secuencias de órdenes de Python en un proceso independiente.

Por ejemplo, supongamos que al ejecutar el código de Python anterior se obtiene como resultado /usr/lib/libreoffice/. En ese caso, debe considerar /usr/lib/libreoffice/program como la ruta para ejecutar sus secuencias de órdenes de Python.

#### Inicie LibreOffice con configuraciones de pipe o socket

To run Python scripts from a separate process, you need to start LibreOffice with a few additional options that specify pipe name or the hostname and port through which the external process will communicate with the LibreOffice component process.

Open the your operating system's command prompt, navigate to the program folder of your LibreOffice installation directory and type either:

En Linux y macOS:

libreoffice --accept='pipe,name=aPipeName;urp;'

En Windows:

soffice.exe --accept='socket,host=localhost,port=2021;urp;'

como Flatpak:

flatpak run org.libreOffice.LibreOffice accept='socket,host=localhost,port=2021;urp;'

Either command above will start LibreOffice with a communication channel open so that other processes can exchange messages with it.

Observe que el ejemplo anterior abre el centro de bienvenida de LibreOffice. Si desea abrir un componente específico, por ejemplo Writer, puede añadir el parámetro --writer a la orden, tal y como se muestra a continuación.

./soffice --writer --accept='socket,host=localhost,port=2021;urp;'

Take note of the name, or host and port parameters, which in this example are aPipeName, or localhost and 2021, respectively.

#### Ejecutar un intérprete de órdenes Python externo

Start the Python shell from within the program folder inside your LibreOffice installation path. Follow the steps above to learn how to find your installation path.

En Linux y macOS:

$ cd /usr/lib/libreoffice/program

$ python

En Windows:

$ cd C:\\Program Files\\LibreOffice\\program\

$ python.exe

Esto abrirá el intérprete de órdenes de Python; ahora podrá empezar a escribir órdenes que LibreOffice ejecutará. Pero antes necesita configurar la conexión pipe o socket. La instrucción ScriptForge() de más abajo debe preceder a la primera llamada a CreateScriptService().

Run either:

       from scriptforge import ScriptForge, CreateScriptService
       ScriptForge(pipe='aPipeName')

        from scriptforge import ScriptForge, CreateScriptService
        ScriptForge(hostname='localhost', port=2021)

Lea la sección Configurar PYTHONPATH que aparece a continuación si se producen errores al importar scriptforge.py o uno.py.

El segundo renglón de código de más arriba define las configuraciones pipe o host y port para que el intérprete de Python pueda comunicarse con un proceso de LibreOffice en ejecución que se haya abierto con los mismas configuraciones de canalización o «socket».

Ahora puede ejecutar otras órdenes de Python y estas podrán comunicarse con el proceso de LibreOffice. Por ejemplo:

        ui = CreateScriptService("UI")
        bas = CreateScriptService("Basic")
        doc = ui.OpenDocument("~/Documents/myFile.ods")
        bas.MsgBox(doc.DocumentType)

#### Establecer PYTHONPATH

Dependiendo de la configuración de su sistema operativo, tendrá que establecer la variable de entorno PYTHONPATH para poder importar la biblioteca scriptforge.py, que a su vez requiere importar la biblioteca uno.py.

Sírvase de la herramienta de búsqueda del sistema operativo para determinar el directorio en que se encuentran ambos archivos.

Por ejemplo, en una instalación predeterminada de Ubuntu, ambos archivos pueden encontrarse en:

- scriptforge.py: se localiza en /usr/lib/libreoffice/program

- uno.py: se localiza en /usr/lib/python3/dist-packages

En este caso, establezca la variable de entorno PYTHONPATH de la siguiente manera antes de iniciar el intérprete de Python:

export PYTHONPATH=/usr/lib/libreoffice/program:/usr/lib/python3/dist-packages

La ubicación de estos archivos variará en función del sistema operativo y del método de instalación de LibreOffice.

Temas relacionados

La biblioteca ScriptForge

Ayuda con las macros en Python en LibreOffice

Iniciar un programa de LibreOffice con parámetros

¡Necesitamos su ayuda!