unotools 0.3.3
Interacting with OpenOffice.org/LibreOffice using UNO
License: Apache License 2.0
Keywords: uno,pyuno,office,OOo

unotools
========

UnoTools allows you to interact with OpenOffice.org/LibreOffice using
the "UNO bridge". The aim is to make handling OpenDocument easy than
using the original UNO/PyUNO for scripting.

The unotools is quite simple, but you ought to understand UNO APIs.

-  `The Apache OpenOffice API
   Document <http://www.openoffice.org/api/>`__
-  `UNO <https://wiki.openoffice.org/wiki/Uno>`__
-  `PyUNO <https://wiki.openoffice.org/wiki/Python>`__

There're other tools.

-  `pyoo <https://pypi.python.org/pypi/pyoo>`__
-  `unoconv <https://pypi.python.org/pypi/unoconv>`__

How to install
--------------

Requirements
~~~~~~~~~~~~

-  OpenOffice.org/LibreOffice 3.4 or lator
-  Python 3.3 or lator

On Ubuntu 14.04
~~~~~~~~~~~~~~~

Install libreoffice, uno library and python3:

.. code:: bash

    $ sudo aptitude install -y libreoffice libreoffice-script-provider-python uno-libs3 python3-uno python3

I like virtualenvwrapper to make temporary environment:

.. code:: bash

    $ sudo aptitude install -y virtualenvwrapper
    $ mkvirtualenv -p /usr/bin/python3.4 --system-site-packages tmp3

Confirm importing uno module:

.. code:: bash

    (tmp3)$ python 
    Python 3.4.0 (default, Apr 11 2014, 13:05:11) 
    [GCC 4.8.2] on linux
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import uno

Install unotools from PyPI:

.. code:: bash

    (tmp3)$ pip install unotools

On Mac OS X
~~~~~~~~~~~

Download LibreOffice DMG package from https://www.libreoffice.org/ and
install.

.. code:: bash

    $ hg clone ssh://hg@bitbucket.org/t2y/unotools

In Python 3.3 case, need singledispatch package. Confirm Python
interpreter version included in LibreOffice.

.. code:: bash

    $ hg clone ssh://hg@bitbucket.org/ambv/singledispatch

Set *PYTHONPATH* to resolve additional packages in LibreOffice's Python
interpreter.

.. code:: bash

    $ export PYTHONPATH="/path/to/singledispatch/:/path/to/unotools/"

On Mac OS X, soffice and python commands are as below.

.. code:: bash

    $ /Applications/LibreOffice.app/Contents/MacOS/soffice --version
    LibreOffice 4.4.0.3 de093506bcdc5fafd9023ee680b8c60e3e0645d7

Confirm importing unotools package:

.. code:: bash

    $ /Applications/LibreOffice.app/Contents/MacOS/python
    Python 3.3.5 (default, Jan 22 2015, 17:12:45) 
    [GCC 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.51)] on darwin
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import unotools

How to use (on Ubuntu 14.04)
----------------------------

Startup libreoffice:

.. code:: bash

    (tmp3)$ soffice --accept='socket,host=localhost,port=8100;urp;StarOffice.Service'

Download sample-scripts from
https://bitbucket.org/t2y/unotools/raw/default/sample-scripts:

.. code:: bash

    (tmp3)$ python sample-scripts/writer-sample1.py -s localhost
    (tmp3)$ python sample-scripts/calc-sample1.py -s localhost -d sample-scripts/datadir/
    (tmp3)$ ls
    sample-calc.html  sample-calc.pdf  sample-calc_html_eaf26d01.png
    sample-scripts  sample-writer.html  sample-writer.pdf
    sample.csv  sample.doc  sample.ods  sample.odt  sample.xls

There's a sample script to convert odt/ods to pdf.

.. code:: bash

    (tmp3)$ python sample-scripts/pdf-convert-sample1.py -s localhost -f sample.odt
    (tmp3)$ python sample-scripts/pdf-convert-sample1.py -s localhost -f sample.ods
    (tmp3)$ ls sample.pdf

Look through these sample script, then it help you how to use unotools.

Interact with interpreter step by step
--------------------------------------

Interacting documents with UNO make you learn how to use unotools.

Startup LibreOffice:

.. code:: bash

    $ soffice --accept='socket,host=localhost,port=8100;urp;StarOffice.Service'

.. code:: python

    >>> from unotools import Socket, connect
    >>> from unotools.component.writer import Writer
    >>> context = connect(Socket('localhost', 8100))
    >>> writer = Writer(context)

Now, you can see new document window on LibreOffice.

.. code:: python

    >>> writer.set_string_to_end('Hello\n')
    >>> writer.set_string_to_end('World\n')

Then, *Hello* and *World* are put into the document window.

.. code:: python

    >>> text = writer.text
    >>> text
    <unotools.component.writer.Text object at 0x1064a8e10>

Writer inherits
`XTextRange <http://www.openoffice.org/api/docs/common/ref/com/sun/star/text/XTextRange.html>`__
interface and has those methods. To make full use of unotools, you have
to understand UNO APIs.

There's a tip to confirm what methods are exist in the component. The
``_show_attributes()`` is a helper method that unotools component
inherit.

.. code:: python

    >>> text._show_attributes()
    [ ...
     'getElementType',
     'getEnd',
     'getImplementationId',
     'getImplementationName',
     'getPropertySetInfo',
     'getPropertyValue',
     'getSomething',
     'getStart',
     'getString',
     'getSupportedServiceNames',
     'getText',
     'getTypes',
      ...
    ]

Though these methods are CamelCase, you can also invoke Python style
methods.

.. code:: python

    >>> text.getString()
    'Hello\nWorld\n'

    >>> text.get_string()
    'Hello\nWorld\n'

Both are same method and unotools component handles to convert Python
style to original method.

Let's save this document as *odt*.

.. code:: python

    >>> from unotools.unohelper import convert_path_to_url
    >>> url = convert_path_to_url('./test1.odt')
    >>> url
    'file:///Users/t2y/work/repo/unotools/test1.odt'
    >>> writer.store_to_url(url, 'FilterName', 'writer8')
    >>> writer.close(True)

If you want to read OpenDocument on file system, like this.

.. code:: python

    >>> writer = Writer(context, convert_path_to_url('./test1.odt'))


ChangeLog
---------

0.3.3 (2015-03-21)
~~~~~~~~~~~~~~~~~~

-  added PDF conversion sample script
-  updated README as tutorial

0.3.2 (2014-06-07)
~~~~~~~~~~~~~~~~~~

-  added some classes for calc
-  changed data directory option of command line argument (-d,
   --datadirs) to be able to store multiple directories

0.3.1 (2014-05-07)
~~~~~~~~~~~~~~~~~~

-  added command line argument (-f, --file) to be able to read
   OpenDocument file

0.3.0 (2014-05-05)
~~~~~~~~~~~~~~~~~~

-  first release