OooDev has a development container that can be used to develop and test code. The container is pre-configured with all the necessary tools to develop and test code. This development container is best suited for use with Vs Code.
In the development container it is possible to run LibreOffice in Gui mode (tested on Ubuntu 22.04) or in headless mode Running LibreOffice in headless mode also will work in a GitHub Codespace, even in the web browser.
When developing using the development container it is not needed to install LibreOffice on the host machine. Also, no need to set up virtual environment.
Note: The development container isolates the
.venv folder from the host machine. This is done to prevent conflicts with the host machine
in the event the host machine has a virtual environment set up.
Setting up virtual environment is not needed when running as a development container.
It is assumed https://github.com/Amourspirit/python_ooo_dev_tools has been cloned or unzipped to a folder.
poetry is required to install this project in a development environment.
OooDev uses a virtual environment for development purposes.
$ python -m venv ./.venv
Activate virtual environment.
Install requirements using Poetry.
(.venv) $ poetry install
In order to run test it is essential that
unohelper.py can be imported.
These files are part of the LibreOffice installation.
The location of these files vary depending on OS and other factors.
On Linux what is required to communicate with LibreOffice API it a copy of, or link to
unohelper.py in the virtual environment.
uno.py sets up the necessary code that makes importing from LibreOffice API possible.
OooDev has a command to accomplish this in the virtual environment on Linux.
(.venv) $ oooenv cmd-link --add
After virtual environment is set up and activated, running the above command on Linux will search in known paths for
and create links to files in the current virtual environment.
That’s it! Now should be ready for development.
For other options try:
(.venv) $ oooenv cmd-link -h
Windows is a little trickery. Creating a link to
uno.py and importing it will not work as it does in Linux.
This is due to the how LibreOffice implements the python environment on Windows.
The recommended way to is to start by creating a virtual environment using a python version that matches the LibreOffice version being target.
For instance LibreOffice
7.3 uses Python
Most likely the version of Python active on your system is not going to match the LibreOffice version.
Checking LibreOffice Python version
PS C:\>"C:\Program Files\LibreOffice\program\python.exe" --version Python 3.8.10
The details of installing a python version for use with a virtual environment is beyond the scope of this document. However, for windows I would recommend a tool such as pyenv-win.
Install command might look something link:
Lets assume Python
3.8.10 is installed to
The recommended tool for creating the virtual environments that work with OooDev is Virtualenv.
Start by using terminal to create a
.venv environment in the projects root folder
PS C:\python_ooo_dev_tools> virtualenv -p "C:\Users\user\.pyenv\pyenv-win\versions\3.8.10\python.exe" .venv
Activate Virtual environment.
PS C:\python_ooo_dev_tools> .\.venv\Scripts\activate.ps1
Install requirements using poetry.
(.venv) PS C:\python_ooo_dev_tools> poetry install
After installing using the previous command it time to set the environment to work with LibreOffice.
(.venv) PS C:\python_ooo_dev_tools> oooenv env -t
This will set the virtual environment to work with LibreOffice.
To check of the virtual environment is set for LibreOffice use the following command.
(.venv) PS C:\python_ooo_dev_tools> oooenv env -u UNO Environment
Newer versions of poetry will not work with the configuration set up for LibreOffice.
When you need to use poetry just toggle environment.
(.venv) PS C:\python_ooo_dev_tools> oooenv env -t
This will toggle between the original setup configuration and the LibreOffice configuration.
Testing Virtual Environment
For a quick test of environment import
uno If there is no import error you should be good to go.
PS C:\python_ooo_dev_tools> .\.venv\scripts\activate (.venv) PS C:\python_ooo_dev_tools> python Python 3.8.10 (default, Mar 23 2022, 15:43:48) [MSC v.1928 64 bit (AMD64)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> import uno >>>
OooDev uses git hooks to ensure document and test are building.
Pointing git to hooks is required for actions to run.
After virtual environment for OooDev is activated, run the following one time command.
git config --local core.hooksPath .githooks/
After setting up hooks, commits and push runs their corresponding hooks before committing or pushing code to repo.
Sometimes it may be prudent to not run hooks, such as adding a text file for internal purposes.
In these cases run
--no--verify flag of git.
git commit -n -m "rename somefile.txt to myfile.txt"
With virtual environment activated, open a terminal window and
(.venv) $ make html
PS C:\python_ooo_dev_tools\docs> make html
Online Docs are available. Viewing local docs can be done by starting a local web-server.
OooDev has a script to make this easier. In a separate terminal window run:
(.venv) $ python cmds/run_http.py
PS C:\python_ooo_dev_tools> python .\cmds\run_http.py
This starts a web server on localhost. Docs can the be viewed at http://localhost:8000/docs/_build/html/index.html
Doc for project are in the
Docs follow a basic style guide. If you are making any changes to docs please consult the
./docs/sytle_guide.txt for guidelines.
Manual spell check
Documents are spelled checked before commit by default when
Hooks are set up.
Manual spell check can be run in a
./docs terminal Windows.
(.venv) $ sphinx-build -b spelling . _build
Spelling custom dictionaries
Custom spelling dictionaries are found in
Any custom dictionary in this directory starting with
spelling_* is auto-loaded into spellcheck.
OooDev contains some environment variables.
ConnectorBridgeBase class has a
soffice parameter that can be passed to the class to specify the LibreOffice version to connect to.
Also there is a
ODEV_CONN_SOFFICE environment variable can be set to specify the LO version to connect to.
soffice is passed to
ConnectorBridgeBase then the
soffice parameter is used; Otherwise, if
ODEV_CONN_SOFFICE is set then the environment variable value is used.
ODEV_CONN_SOFFICE are set then the default
soffice is used.
This is useful to test a LO development version.
MacroLoader context manager is used to load and reset context for macros.
Sometimes it is useful to override the default
MacroLoader context manager such as when testing or running macros code outside of LibreOffice.
Setting the environment variable to
ODEV_MACRO_LOADER_OVERRIDE=1 will override the default
MacroLoader context manager and return
ooodev.lo.Lo.loader_current if available.
Test are written for pytest
Make sure any unnecessary extensions are disabled in LibreOffice for testing.
LanguageTool 5.8 enabled on Linux (
Ubuntu 22.04) resulted in critical failure,
but only when test were run in GUI mode. Disabling
LanguageTool 5.8 extension resolved the testing issue.