This project allow typings for the full LibreOffice API <https://api.libreoffice.org/>_
Working with LibreOffice API <https://api.libreoffice.org/>_ in a modern code editor such as Visual Studio Code <https://code.visualstudio.com/>_
there is not type support for LibreOffice API <https://api.libreoffice.org/>_ This project solves that Issue.
This package is for Version 2024.2 + of LibreOffice API <https://api.libreoffice.org/>_.
From one version of LibreOffice to the next, generally speaking, the API does not changed much.
Because this is the case it is very likely this current version of LibreOffice API Typings
will work fine with other versions of LibreOffice. This a typing package so not much can go wrong in other versions.
types-unopy on PyPI <https://pypi.org/project/types-unopy/>_
.. code-block:: bash
$ pip install types-unopy
types-unopy on Anaconda <https://anaconda.org/conda-forge/types-unopy>_
.. code-block:: bash
$ conda install -c conda-forge types-unopy
Types-ScriptForge leverages <https://github.com/Amourspirit/python-types-scriptforge>_ types-unopy. By installing
Types-ScriptForge into your project you will also automatically install types-unopy.
Not all object in LibreOffice API <https://api.libreoffice.org/>_ can be directly imported.
Any UNO object that is a service cannot be imported at runtime.
For instance if you need to import SheetCellRange so it can be used
as type the following will fail at runtime.
.. code-block:: python
>>> from com.sun.star.sheet import SheetCellRange
ImportError: No module named 'com' (or 'com.sun.star.sheet.SheetCellRange' is unknown)
The solution is to use TYPE_CHECKING <https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING>_.
.. code-block:: python
>>> from __future__ import annotations
>>> from typing import TYPE_CHECKING
>>> if TYPE_CHECKING:
... from com.sun.star.sheet import SheetCellRange
...
Anything imported in the TYPE_CHECKING block will not be available at runtime.
For this reason types inside the TYPE_CHECKING must be wrapped in quotes OR from __future__ import annotations must be the first line of the module.
Example of wrapping type in quotes.
.. code-block:: python
def do_work(range: 'SheetCellRange') -> None: ...
There is no enum classes in API only enum members.
To access the enum members they must be imported directly.
For example to import com.sun.star.beans.PropertyState.DIRECT_VALUE
If you need the behavior of regular Enum Classes consider using ooouno <https://github.com/Amourspirit/python-ooouno>_
.. code-block:: python
>>> from com.sun.star.beans import PropertyState
ImportError: No module named 'com' (or 'com.sun.star.beans.PropertyState' is unknown
>>>
>>> from com.sun.star.beans.PropertyState import DIRECT_VALUE
>>> DIRECT_VALUE.value
'DIRECT_VALUE'
>>>
>>> type(DIRECT_VALUE)
<class 'uno.Enum'>
.. figure:: https://user-images.githubusercontent.com/4193389/163689461-ab349f19-81b0-450b-bf49-50303a5c4da4.gif :alt: Example image.
By default an ImportError is raised when importing form com.sun.star at runtime.
This is by design as the import error triggers uno to search LibreOffice API for actual import;
Otherwise, com.sun.star is seen a namespace import and uno is ignored.
In some cases the ImportError may need to be suppressed.
Suppressing ImportError is accomplished by adding "ooouno_ignore_import_error" to environment and setting it to "True"
.. code-block:: python
>>> import os
>>> os.environ["ooouno_ignore_import_error"] = "True" # must be string
When building with Sphinx_ and autodoc_ it may be necessary to exclude uno related imports.
This can be accomplished using the autodoc_mock_imports <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports>_ option.
.. code-block:: python
# docs conf.py
autodoc_mock_imports = ['uno', 'unohelper', 'com']
For a reference see ooo-dev-tools conf.py <https://github.com/Amourspirit/python_ooo_dev_tools/blob/main/docs/conf.py>__.
As mentioned above there are no enum classes in API only enum members.
For this reason this package implements protocols for enums.
.. code-block:: python
from com.sun.star.beans.PropertyState import DIRECT_VALUE
# DIRECT_VALUE is a type of PropertyStateProto
The implemented protocol for PropertyState is as follows:
.. code-block:: python
class PropertyStateProto(Protocol):
"""Protocol for PropertyState"""
@property
def typeName(self) -> Literal["com.sun.star.beans.PropertyState"]:
...
value: Any
AMBIGUOUS_VALUE: PropertyStateProto
DEFAULT_VALUE: PropertyStateProto
DIRECT_VALUE: PropertyStateProto
Implemented methods such as com.sun.star.beans.PropertyState.XPropertyState.getPropertyState() return a protocol, in this case PropertyStateProto.
If you need to import a protocol for type hinting in your project then it will need to be guarded.
Type Guarding Protocol ^^^^^^^^^^^^^^^^^^^^^^
Since typing.TYPE_CHECKING is always False at runtime we can use it.
There are two way to handle importing a protocol class.
The first way is by importing annotations
.. code-block:: python
from __future__ import annotations
import uno
from com.sun.star.sheet.SolverConstraintOperator import SolverConstraintOperatorProto
# ...
def solve_operation(value: int, x: SolverConstraintOperatorProto) -> int:
...
Note when using annotations the cast to protocol must be wrapped in a string.
.. code-block:: python
from typing import cast
from com.sun.star.sheet.SolverConstraintOperator import SolverConstraintOperatorProto
from ooo.dyn.sheet.solver_constraint_operator import SolverConstraintOperator
# ...
# SolverConstraintOperatorProto must be wrapped in a string
# if it has not been assigned to object at runtime.
solve_operation(
11, cast("SolverConstraintOperatorProto", SolverConstraintOperator.BINARY)
)
The other way is to assign the protocol class as an object at runtime.
.. code-block:: python
from typing import TYPE_CHECKING
import uno
from com.sun.star.sheet.SolverConstraintOperator import SolverConstraintOperatorProto
if TYPE_CHECKING:
# While writing code we have the advantages of protocol
from com.sun.star.sheet.SolverConstraintOperator import SolverConstraintOperatorProto
else:
# code is executing. Now protocol is an object and basically ignored
SolverConstraintOperatorProto = object
OOO Development Tools <https://github.com/Amourspirit/python_ooo_dev_tools>__ooouno <https://github.com/Amourspirit/python-ooouno>__ScriptForge Typings <https://github.com/Amourspirit/python-types-scriptforge>__Access2base Typings <https://github.com/Amourspirit/python-types-access2base>__LibreOffice Python UNO Examples <https://github.com/Amourspirit/python-ooouno-ex>__LibreOffice UNO Typings <https://github.com/Amourspirit/python-types-uno-script>__LibreOffice Developer Search <https://github.com/Amourspirit/python_lo_dev_search>__OOO UNO TEMPLATE <https://github.com/Amourspirit/ooo_uno_tmpl>__.. _Sphinx: https://www.sphinx-doc.org/en/master/ .. _autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
FAQs
Type annotations for LibreOffice API
We found that types-unopy demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.