FAQ - Amourspirit/live-libreoffice-python GitHub Wiki

FAQ TOC

How do I install a python package into the LibreOffice Environment?

By default there should be a requirements.txt file in the .devcontainer/res/req folder. This file is used to install packages that are used in the development environment but are not part of your project. If the requirementst.txt file does not exist it can be created.

For instance if you want to install the OOO Development Tools package into the development environment then you would add ooo-dev-tools to the requirements.txt file. This will install the package into the development environment but not into your project. This is useful for packages that are used for development but are not part of your project.

Back to Top

What the macro folder for?

The python files in the macro folder are directly available in the LibreOffice Macros. If the macro is edited in Vs Code and then run in LibreOffice the results are immediate. No need to restart LibreOffice to have changes take effect.

The code in the macro folder can not be launched from Vs Code. It must be launched from LibreOffice.

Using the macro folder has some limitations. The python files in the macro folder are not available to the Vs Code debugger.

Back to Top

image

Why is there a pyproject.toml file?

This project uses poetry for managing packages for your local project. You may have other dependencies that you need for your project. For instance to add type stubs for LibreOffice Access2Base the command is poetry add types-access2base. When the development container is started all dependencies in the pyproject.toml file are automatically added to the virtual environment.

Back to Top

Whats the difference between installing python packages via toml file vs requirements file?

When installing packages via the .devcontainer/res/req/requirements.txt the packages are available to LibreOffice running in the container only. This option is available for cases where you want packages installed into development environment but not part of the pyproject.toml file. The packages are installed into the system's python site_packages of the container. Any packages installed in the LibreOffice container are not accessible to your project when it is invoked via the command line or in Vs Code.

In short for most projects, all of the dependencies will be managed by poetry.

Runtime Python Paths (sys.path) when python was run from app/ folder.

['/workspace/libreoffice_python_app/app',
 '/usr/lib/libreoffice/program',
 '/workspace/libreoffice_python_app',
 '/usr/lib/python311.zip',
 '/usr/lib/python3.11',
 '/usr/lib/python3.11/lib-dynload',
 '/workspace/libreoffice_python_app/.venv/lib/python3.11/site-packages',
 '/usr/lib/python3.11/site-packages']

Runtime Python Paths for LibreOffice started manually in Development Container.

['/usr/lib/libreoffice/program',
 '/config',
 '/usr/lib/python311.zip',
 '/usr/lib/python3.11',
 '/usr/lib/python3.11/lib-dynload',
 '/workspace/libreoffice_python_app/.venv/lib/python3.11/site-packages',
 '/workspace/libreoffice_python_app',
 '/usr/lib/python3.11/site-packages',
 '/usr/lib/libreoffice/share/extensions/apso/python/pythonpath']

Back to Top

What is the VS Browser?

The Vs Browser is an extension for Vs Code. In this case It allows LibreOffice to be run in Vs Code. Running LibreOffice inside the Vs Browser extension has some limitations. Some of the features offered by Kasm VNC are not available while running LibreOffice in the VS Browser such as copy and paste. LibreOffice can also be accessed in a standard browser and there is no dependency on the Vs Browser extension. If you need to access copy and paste then use your normal web browser.

One nice feature of Vs Browser is it also works when running your project in a GitHub Codespace via a web browser.

Back to Top

How do I run my project in a GitHub Codespace?

See Getting Started - Running

Back to Top

How do I access the LibreOffice in a GitHub Codespace?

When running your project in a GitHub Codespace you can access LibreOffice via the Vs Browser extension. The Vs Browser extension is installed by default in all GitHub Codespaces.

However in a Codespace the http://localhost:3002 address will not be directly available.

Codespace automatically creates port forwarding for port 3002 and therefore the http://localhost:3002 address is not directly available. Instead the LibreOffice browser address is locates in the ports section of the Codespace. If you don't see the ports try the Ctl+` (control backtick) shortcut to open the terminal. The ports section is located at the as a separate tab.

Find then entry in the ports listed as LibreOffice http server 3002, then under the local address column, click the Open in Browser link to open LibreOffice in a new browser tab or alternatively copy the address and paste it into the VS browser.

Codespace automatic port forwarding:

image

If you open up a Codespace in VS Code that http://localhost:3002 address may be be available; However, it it not recommended to use that address because it sometime does not display the LibreOffice window correctly. Instead use the port forwarding address as mentioned above

Can I run this project outside of a container?

While this project is set to run in a container with very little configuration it is possible to run it outside of a container. Some prerequisites are needed. LibreOffice must be installed on your system. On windows this project would need to be run on WSL2. Poetry must be installed on your system. A virtual environment must be created, this can be done by running poetry install in the folder of this project (the place where pyproject.toml file lives). LibreOffice would need to be linked into the virtual environment. A tool such as oooenv can aid in this i.e. oooenv cmd-link -a. The linking of LibreOffice allows your project to be aware of uno.py which is critical when running outside of a development container.

When project is started from development environment (command line or invoked from VS Code) it will automatically add its virtual environment path to LibreOffice's python path so any dependencies in your virtual environment will automatically be available to LibreOffice.

If you need to install dependencies directly into LibreOffice see these guides as a reference. See Also OOO Development Tools's Dev Docs Note that it is recommended to run your project as a Development Container because removes all this extra configuration.

Back to Top

Do I need to install project dependencies locally?

No, not unless you plan on running you project without a container ( not recommended ).

When container is built all dependencies are automatically installed. If you need to add a dependency then the recommended way is to start the Development Container and then do a poetry add <some_package>. Any packages added in this manor will persist when the container is restarted or rebuilt.

See also Can I run poetry install on my local machine?

Back to Top

How do I add an extension to Containerized LibreOffice?

Extensions ( oxt files) placed in the .devcontainer/res/ext folder will automatically be installed when the container is built. See also LibreOffice Extensions. Note some extension may cause minor startup issues. I noticed with the MRI extension LibreOffice sometimes has to be opened a second time before it actually starts. The first time it appeared like it would start but did no. This is only after a fresh rebuild of the container.

Back to Top

Can I rename the app folder?

Yes, the app folder can be renamed. If you are planing on packaging your project when poetry the pyproject.toml also need to have the packages -> include name updated to match the new folder name.

[tool.poetry]
# other settings ...
license = "MIT"
readme = "README.md"
packages = [
    { include = "My_Awesome_App" }
]

Back to Top

Can I package my project using poetry?

Yes, rename the app folder should be renamed to the package name you want for you package, then update the [tool.poetry] section of the pyproject.toml to match your project information. Running poetry build will create a packaged version of your app in a newly created folder named dist (excluded from git source control). Once your poetry is properly configure to publish then you can run poetry publish to publish your package to a package index such as pypi.org. See also Can I rename the app folder?

Awesome example:

[tool.poetry]
name = "My Awesome Package"
version = "0.1.0"
description = "Just Awesome"
authors = ["Awesome Coder <[email protected]>"]
license = "MIT"
readme = "README.md"
packages = [
    { include = "awesome" }
]

Can I run poetry install on my local machine?

Yes, however, this would only be done if you plan on running the your project outside of the container ( not recommended ). When the development container is started it will create it own folder for .vevn virtual environment files. This means if a .venv folder exist on you local machine it is completely ignored by while the development container is running. Any new packages installed into the development environment (via poetry add some_package) will not be reflected outside of the development environment, however, the pyproject.toml file changes are reflected.

Because the pyproject.toml file is reflected in and out of the development it means poetry install can be run to ensure all packages are installed in any state.

See also Do I need to install project dependencies locally?

How do I run my project?

If your only running a macro then there is no need to run your project. Just run the macro from LibreOffice. The macro folder is directly available to LibreOffice. See What is the macro folder for? section for more information.

If you are running a python script then you can run your project from the command line or from Vs Code. Usually the entry point for your project is a file such as main.py. In this templete there is the hello.py file as an example. This file is located in the app folder. If you rename the app folder then the entry point will be the folder name you renamed it to.

In the template example the hello.py file is the entry point. To run the project from the command line you would run python ./app/hello.py on the command line from the root folder of the project. If you are running from Vs Code then with the hello.py file open in the editor you can use the Run button in the top right corner of Vs Code. This will run the hello.py file.

LibreOffice is running in the container and is available to your project. LibreOffice can be accessed via the VS Browser plugin or vis your normal web browser.

image

Back to Top

How do I debug my project?

Debugging in Vs Code is available for python files in the app folder. The macro folder is not available to the Vs Code debugger; However, a macro can be debugged if it launched from a python file. For instance the Calc Add Range of Data Example example has a run.py file that can be launched from Vs Code. This file in turn starts LibreOffice and launches the macro that can be debugged in Vs Code.

In order to debug a python file in the app folder you must first open the file in the Vs Code editor. Then you can use the Run button in the top right corner of Vs Code. This will run the python file in the Vs Code debugger. If you have a breakpoint set then the debugger will stop at the breakpoint.

In some case you may want your script to start LibreOffice and in other cases you may want to start LibreOffice manually and connect to a running instance via localhost and port.

When a LibreOffice application is started via the launch bar see below it will always be started accepting connections on host="localhost" and port=2002.

image

In other case you may start your script that in turn starts LibreOffice and then connects to it. This is the case with the hello.py example in the app folder that uses OooDev to start LibreOffice.

image

It is possible to debug macros using the APSO extension; However it is out of the scope of this FAQ. See APSO for more information.

Back to Top

How do I run tests?

See: Testing

Back to Top

How can I compile my project if I have multiple python files?

The Calc Add Range of Data Example demonstrates how to compile a project with multiple python files.

By default LibreOffice does not support multiple python files. The oooscript tool will compile your multiple python files into a single python file. This single python file can then be run in LibreOffice. The oooscript can also embed the single script into a LibreOffice document such as a Calc spreadsheet.

The oooscript tool is installed in the development container. To use it you must first start the development container. Then you can run the oooscript command from the command line or alternatively run the commands from a Makefile file as seen in the example.

The Calc Add Range of Data Example has a Makefile to aid in compiling the script.

make macro

The above command will compile the example into odev_add_range.py and place it in the macro folder. Now the macros can be run from LibreOffice.

make build

The above command will compile the example into odev_add_range.py and embed the script into odev_add_range.ods. The files will be written into the build/add_range_data/ folder.

Note that the oooscript tool requires a config.json file which is included in the example.

Note also that oooscript expects there to be an .env file in the project root folder (in a container this would be the /workspace/libreoffice_python_app/ folder). See the Quick Start for more information.

Note also that each time that make macro is run LibreOffice will need to be restarted before the changes will take effect. This is mainly due to multi-script macro need to import other modules. If you are only running a single script macro then restarting LibreOffice is not needed.

Back to Top

How do I update the python packages?

Packages are managed by poetry. To update packages run poetry update in the root folder of running container.

(libreoffice python template-py3.11) root ➜ /workspace/libreoffice_python_app (container) 
$ poetry update
Updating dependencies
Resolving dependencies... (2.2s)

Package operations: 0 installs, 1 update, 0 removals

  • Updating ooo-dev-tools (0.11.10 /workspace/libreoffice_python_app -> 0.11.10)

Writing lock file

Back to Top