=======================
LibreOffice API Typings
=======================
This project allow typings for the full `LibreOffice API <https://api.libreoffice.org/>`_
WHY
===
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.
VERSION
=======
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.
Installation
============
PIP
---
**types-unopy** on `PyPI <https://pypi.org/project/types-unopy/>`_
.. code-block:: bash
$ pip install types-unopy
CONDA
-----
**types-unopy** on `Anaconda <https://anaconda.org/conda-forge/types-unopy>`_
.. code-block:: bash
$ conda install -c conda-forge types-unopy
Related
=======
`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``.
USAGE
=====
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: ...
Known Issues
============
Enums
-----
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'>
Demo
====
.. figure:: https://user-images.githubusercontent.com/4193389/163689461-ab349f19-81b0-450b-bf49-50303a5c4da4.gif
:alt: Example image.
Special Cases
=============
ImportError
-----------
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>`__.
Enum Protocols
--------------
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
Related Projects
================
* `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
Raw data
{
"_id": null,
"home_page": "https://github.com/Amourspirit/python-types-unopy",
"name": "types-unopy",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": ":Barry-Thomas-Paul: Moss",
"author_email": "bigbytetech@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/29/c9/35d81c34d98239178c246cc095f5d62168498be6c51f6020138aa572ea6a/types_unopy-2.0.0.tar.gz",
"platform": null,
"description": "=======================\nLibreOffice API Typings\n=======================\n\nThis project allow typings for the full `LibreOffice API <https://api.libreoffice.org/>`_\n\nWHY\n===\n\nWorking with `LibreOffice API <https://api.libreoffice.org/>`_ in a modern code editor such as `Visual Studio Code <https://code.visualstudio.com/>`_\nthere is not type support for `LibreOffice API <https://api.libreoffice.org/>`_ This project solves that Issue.\n\nVERSION\n=======\n\nThis package is for Version ``2024.2`` + of `LibreOffice API <https://api.libreoffice.org/>`_.\n\nFrom one version of LibreOffice to the next, generally speaking, the API does not changed much.\nBecause this is the case it is very likely this current version of ``LibreOffice API Typings``\nwill work fine with other versions of LibreOffice. This a typing package so not much can go wrong in other versions.\n\nInstallation\n============\n\nPIP\n---\n\n**types-unopy** on `PyPI <https://pypi.org/project/types-unopy/>`_\n\n.. code-block:: bash\n\n $ pip install types-unopy\n\n\nCONDA\n-----\n\n**types-unopy** on `Anaconda <https://anaconda.org/conda-forge/types-unopy>`_\n\n.. code-block:: bash\n\n $ conda install -c conda-forge types-unopy\n\n\nRelated\n=======\n\n`Types-ScriptForge leverages <https://github.com/Amourspirit/python-types-scriptforge>`_ ``types-unopy``. By installing\nTypes-ScriptForge into your project you will also automatically install ``types-unopy``.\n\nUSAGE\n=====\n\nNot all object in `LibreOffice API <https://api.libreoffice.org/>`_ can be directly imported.\n\nAny UNO object that is a *service* cannot be imported at runtime.\n\nFor instance if you need to import ``SheetCellRange`` so it can be used\nas type the following will fail at runtime.\n\n.. code-block:: python\n\n >>> from com.sun.star.sheet import SheetCellRange\n ImportError: No module named 'com' (or 'com.sun.star.sheet.SheetCellRange' is unknown)\n\nThe solution is to use `TYPE_CHECKING <https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING>`_.\n\n.. code-block:: python\n\n >>> from __future__ import annotations\n >>> from typing import TYPE_CHECKING\n >>> if TYPE_CHECKING:\n ... from com.sun.star.sheet import SheetCellRange\n ...\n\nAnything imported in the ``TYPE_CHECKING`` block will not be available at runtime.\nFor 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.\n\nExample of wrapping type in quotes.\n\n.. code-block:: python\n\n def do_work(range: 'SheetCellRange') -> None: ...\n\nKnown Issues\n============\n\nEnums\n-----\n\nThere is no enum classes in API only enum members.\n\nTo access the enum members they must be imported directly.\n\nFor example to import ``com.sun.star.beans.PropertyState.DIRECT_VALUE``\n\n\nIf you need the behavior of regular Enum Classes consider using `ooouno <https://github.com/Amourspirit/python-ooouno>`_\n\n.. code-block:: python\n\n >>> from com.sun.star.beans import PropertyState\n ImportError: No module named 'com' (or 'com.sun.star.beans.PropertyState' is unknown\n >>>\n >>> from com.sun.star.beans.PropertyState import DIRECT_VALUE\n >>> DIRECT_VALUE.value\n 'DIRECT_VALUE'\n >>>\n >>> type(DIRECT_VALUE)\n <class 'uno.Enum'>\n\nDemo\n====\n\n.. figure:: https://user-images.githubusercontent.com/4193389/163689461-ab349f19-81b0-450b-bf49-50303a5c4da4.gif\n :alt: Example image.\n\nSpecial Cases\n=============\n\nImportError\n-----------\n\nBy default an ``ImportError`` is raised when importing form ``com.sun.star`` at runtime.\nThis is by design as the import error triggers ``uno`` to search LibreOffice API for actual import;\nOtherwise, ``com.sun.star`` is seen a namespace import and ``uno`` is ignored.\n\nIn some cases the ``ImportError`` may need to be suppressed.\n\nSuppressing ``ImportError`` is accomplished by adding ``\"ooouno_ignore_import_error\"`` to environment and setting it to ``\"True\"``\n\n.. code-block:: python\n\n >>> import os\n >>> os.environ[\"ooouno_ignore_import_error\"] = \"True\" # must be string\n\nWhen building with `Sphinx`_ and `autodoc`_ it may be necessary to exclude uno related imports.\nThis can be accomplished using the `autodoc_mock_imports <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports>`_ option.\n\n.. code-block:: python\n\n # docs conf.py\n autodoc_mock_imports = ['uno', 'unohelper', 'com']\n\nFor a reference see ``ooo-dev-tools`` `conf.py <https://github.com/Amourspirit/python_ooo_dev_tools/blob/main/docs/conf.py>`__.\n\nEnum Protocols\n--------------\n\nAs mentioned above there are no enum classes in API only enum members.\n\nFor this reason this package implements protocols for enums.\n\n.. code-block:: python\n\n from com.sun.star.beans.PropertyState import DIRECT_VALUE\n # DIRECT_VALUE is a type of PropertyStateProto\n\nThe implemented protocol for ``PropertyState`` is as follows:\n\n.. code-block:: python\n\n class PropertyStateProto(Protocol):\n \"\"\"Protocol for PropertyState\"\"\"\n\n @property\n def typeName(self) -> Literal[\"com.sun.star.beans.PropertyState\"]:\n ...\n value: Any\n AMBIGUOUS_VALUE: PropertyStateProto\n DEFAULT_VALUE: PropertyStateProto\n DIRECT_VALUE: PropertyStateProto\n\nImplemented methods such as ``com.sun.star.beans.PropertyState.XPropertyState.getPropertyState()`` return a protocol, in this case ``PropertyStateProto``.\n\nIf you need to import a protocol for type hinting in your project then it will need to be guarded.\n\nType Guarding Protocol\n^^^^^^^^^^^^^^^^^^^^^^\n\nSince ``typing.TYPE_CHECKING`` is always ``False`` at runtime we can use it.\n\nThere are two way to handle importing a protocol class.\nThe first way is by importing ``annotations``\n\n.. code-block:: python\n\n from __future__ import annotations\n import uno\n from com.sun.star.sheet.SolverConstraintOperator import SolverConstraintOperatorProto\n # ...\n\n def solve_operation(value: int, x: SolverConstraintOperatorProto) -> int:\n ...\n\nNote when using ``annotations`` the ``cast`` to protocol must be wrapped in a string.\n\n.. code-block:: python\n\n from typing import cast\n from com.sun.star.sheet.SolverConstraintOperator import SolverConstraintOperatorProto\n from ooo.dyn.sheet.solver_constraint_operator import SolverConstraintOperator\n # ...\n\n # SolverConstraintOperatorProto must be wrapped in a string\n # if it has not been assigned to object at runtime.\n solve_operation(\n 11, cast(\"SolverConstraintOperatorProto\", SolverConstraintOperator.BINARY)\n )\n\nThe other way is to assign the protocol class as an object at runtime.\n\n.. code-block:: python\n\n from typing import TYPE_CHECKING\n import uno\n from com.sun.star.sheet.SolverConstraintOperator import SolverConstraintOperatorProto\n\n if TYPE_CHECKING:\n # While writing code we have the advantages of protocol\n from com.sun.star.sheet.SolverConstraintOperator import SolverConstraintOperatorProto\n else:\n # code is executing. Now protocol is an object and basically ignored\n SolverConstraintOperatorProto = object\n\nRelated Projects\n================\n\n* `OOO Development Tools <https://github.com/Amourspirit/python_ooo_dev_tools>`__\n* `ooouno <https://github.com/Amourspirit/python-ooouno>`__\n* `ScriptForge Typings <https://github.com/Amourspirit/python-types-scriptforge>`__\n* `Access2base Typings <https://github.com/Amourspirit/python-types-access2base>`__\n* `LibreOffice Python UNO Examples <https://github.com/Amourspirit/python-ooouno-ex>`__\n* `LibreOffice UNO Typings <https://github.com/Amourspirit/python-types-uno-script>`__\n* `LibreOffice Developer Search <https://github.com/Amourspirit/python_lo_dev_search>`__\n* `OOO UNO TEMPLATE <https://github.com/Amourspirit/ooo_uno_tmpl>`__\n\n.. _Sphinx: https://www.sphinx-doc.org/en/master/\n.. _autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Type annotations for LibreOffice API",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/Amourspirit/python-types-unopy",
"Repository": "https://github.com/Amourspirit/python-types-unopy"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3d510717c18e667d53cff55b30af07ccd00f4bdbce9ab278fcc57724d340f1f3",
"md5": "d47b988b2535750dd3ac726d282988ef",
"sha256": "748673362338851088d7ab88b51132c5f42a4e56600a55c27448b44327b023bf"
},
"downloads": -1,
"filename": "types_unopy-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d47b988b2535750dd3ac726d282988ef",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 5200911,
"upload_time": "2024-08-31T22:24:54",
"upload_time_iso_8601": "2024-08-31T22:24:54.131210Z",
"url": "https://files.pythonhosted.org/packages/3d/51/0717c18e667d53cff55b30af07ccd00f4bdbce9ab278fcc57724d340f1f3/types_unopy-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "29c935d81c34d98239178c246cc095f5d62168498be6c51f6020138aa572ea6a",
"md5": "4f750aea74094a9e9891593bc9ac25bf",
"sha256": "b3bacd0cc95d63efd5c8db052d72c7edd4756acbd90761d88ea51cf171f7223d"
},
"downloads": -1,
"filename": "types_unopy-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "4f750aea74094a9e9891593bc9ac25bf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 1445954,
"upload_time": "2024-08-31T22:24:59",
"upload_time_iso_8601": "2024-08-31T22:24:59.642569Z",
"url": "https://files.pythonhosted.org/packages/29/c9/35d81c34d98239178c246cc095f5d62168498be6c51f6020138aa572ea6a/types_unopy-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-31 22:24:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Amourspirit",
"github_project": "python-types-unopy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "types-unopy"
}
JSON
