Difference between revisions of "PyUNO bridge"
From Apache OpenOffice Wiki
(→Hello World) |
m (→PyUNO tutorial for {{AOo}}) |
||
| (12 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
| − | == | + | == Introduction == |
| + | The Python-UNO bridge allows users to: | ||
| + | * use the standard {{AOo}} API from the well known Python scripting language. | ||
| + | * develop UNO components in Python (so that Python UNO components may be run within the {{AOo}} process and can be called from [https://en.wikipedia.org/wiki/JavaScript Java], [https://en.wikipedia.org/wiki/C%2B%2B C++] or the {{AOo}} built-in [https://en.wikipedia.org/wiki/StarBasic StarBasic] scripting language). | ||
| + | * create and invoke scripts with the office scripting framework (OpenOffice.org 2.0 and later). | ||
| − | + | You can find the most current version of this document from https://www.openoffice.org/udk/python/python-bridge.html | |
| − | + | ||
| − | + | === Download === | |
| − | + | You can also download this documentation for off-line work. | |
| − | + | ||
| − | + | ||
| − | + | Download [https://www.openoffice.org/udk/python/pyuno-doc.zip pyuno-doc.zip] ( less than 0.5 MB). | |
| − | + | ||
| − | + | === State === | |
| + | The '''Python-UNO bridge''' is feature complete, but has not been used extensively and therefore may contain some bugs. It is now integrated in the OpenOffice.org source trees. (OpenOffice.org 1.0.x is not supported.) | ||
| − | + | The documentation in its current state is targeted at developers who already have some experience with [[API|{{AOo}} API]] and with some other programming language (Java/C++/StarBasic). It is recommended that you read some background information from the '''developer manual''' before looking at the specifics of Python. | |
| − | + | ||
| − | + | === Translations === | |
| + | (Find here a shortened Spanish version of this document.) | ||
| − | + | == Tutorial == | |
| − | ===PyUNO tutorial for | + | |
| − | This tutorial shows | + | === PyUNO tutorial for {{AOo}} === |
| − | =====PyUNO Installation ===== | + | This tutorial shows how the '''PyUNO bridge''' can be used to automate {{AOo}}. This is not an {{AOo}} tutorial, there is lots of resources available in the office development kit and the developer manual. |
| + | |||
| + | ===== PyUNO Installation ===== | ||
Since OpenOffice.org 1.1, '''PyUNO''' is included in the default installation. | Since OpenOffice.org 1.1, '''PyUNO''' is included in the default installation. | ||
| − | |||
| + | =====PyUNO bridge modes ===== | ||
PyUNO can be used in three different modes: | PyUNO can be used in three different modes: | ||
| − | * Inside the | + | * Inside the {{AOo}} process within the scripting framework (OpenOffice.org 2.0 and later only !!) |
| − | * Inside the | + | * Inside the Python executable (and outside the {{AOo}} process) |
| + | [[Image:Mode_ipc.png]] | ||
| − | Use this mode | + | Use this mode when you: |
| − | * begin to use PyUNO (as it is the more intuitive approach). | + | * begin to use PyUNO (as it is the more intuitive approach). |
| − | * want to trigger script execution by starting a separate process (e.g. a cgi-script within a http-server) | + | * want to trigger script execution by starting a separate process (e.g. a cgi-script within a http-server) |
* want the shortest turnaround times (code - execute - code - execute ...) | * want the shortest turnaround times (code - execute - code - execute ...) | ||
| − | =====Hello World ===== | + | ===== "Hello World" Example ===== |
| + | Make sure that {{AOo}} is not running (note that on Windows you must also terminate the '''Quickstarter''' in the '''systemtray''' at the right bottom of your desktop). Start a '''system shell''' (<tt>cmd</tt> on Win NT/2000/XP, <tt>command</tt> on Win9x, <tt>tcsh</tt> or <tt>bash</tt> on Linux/Unix). Switch to the {{AOo}} 'program' directory (e.g. C:\Program Files (x86)\OpenOffice.org 2.4\program ) and start the office with the following command line parameters: | ||
| − | + | c:\Program Files (x86)\OpenOffice.org 2.4\program> soffice "-accept=socket,host=localhost,port=2002;urp;" | |
| − | + | Now, use your favorite text editor to create the following 'hello_world.py' sample program: | |
| − | + | <syntaxhighlight lang=python> | |
| − | + | ||
| − | < | + | |
import uno | import uno | ||
| − | + | """ Here is the sequence of things the lines do: | |
| − | + | 1. Get the uno component context from the PyUNO runtime | |
| + | 2. Create the UnoUrlResolver | ||
| + | 3. Get the central desktop object | ||
| + | 4. Declare the ServiceManager | ||
| + | 5. Get the central desktop object | ||
| + | 6. Access the current writer document | ||
| + | 7. Access the document's text property | ||
| + | 8. Create a cursor | ||
| + | 9. Insert the text into the document """ | ||
| − | + | localContext = uno.getComponentContext() | |
resolver = localContext.ServiceManager.createInstanceWithContext( | resolver = localContext.ServiceManager.createInstanceWithContext( | ||
"com.sun.star.bridge.UnoUrlResolver", localContext ) | "com.sun.star.bridge.UnoUrlResolver", localContext ) | ||
| − | |||
| − | |||
ctx = resolver.resolve( "uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext" ) | ctx = resolver.resolve( "uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext" ) | ||
smgr = ctx.ServiceManager | smgr = ctx.ServiceManager | ||
| − | |||
| − | |||
desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",ctx) | desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",ctx) | ||
| − | |||
| − | |||
model = desktop.getCurrentComponent() | model = desktop.getCurrentComponent() | ||
| − | |||
| − | |||
text = model.Text | text = model.Text | ||
| − | |||
| − | |||
cursor = text.createTextCursor() | cursor = text.createTextCursor() | ||
| − | |||
text.insertString( cursor, "Hello World", 0 ) | text.insertString( cursor, "Hello World", 0 ) | ||
| − | + | """ Do a nasty thing before exiting the python process. In case the | |
| − | + | last call is a one-way call (e.g. see idl-spec of insertString), | |
| − | + | it must be forced out of the remote-bridge caches before python | |
| − | + | exits the process. Otherwise, the one-way call may or may not reach | |
| − | + | the target object. | |
| − | + | I do this here by calling a cheap synchronous call (getPropertyValue).""" | |
ctx.ServiceManager | ctx.ServiceManager | ||
| − | </ | + | </syntaxhighlight> |
| − | Now start the above script with the | + | Now, to start the above script with the Python script located in the 'program' directory: |
c:\Program Files\OpenOffice1.1\program> .\python hello_world.py | c:\Program Files\OpenOffice1.1\program> .\python hello_world.py | ||
| − | Note: You must use the script/batch file in the program directory to | + | '''Note:''' You must use the script/batch file in the 'program' directory to start Python; simply starting the Python executable in the runtime directory (or from a Python installation installed somewhere else on your machine) will not work. |
| + | |||
| + | This script prints "Hello World" into the '''current writer document'''. | ||
| + | |||
| + | [[Image:Mode_component.png]] | ||
| + | |||
| + | == See also == | ||
| + | [[API/Samples/StarBasic|StarBasic Samples]] | ||
| + | |||
| − | + | [[Category:Python]][[Category:Uno]] | |
Latest revision as of 13:11, 3 February 2021
Contents
Introduction
The Python-UNO bridge allows users to:
- use the standard Apache OpenOffice API from the well known Python scripting language.
- develop UNO components in Python (so that Python UNO components may be run within the Apache OpenOffice process and can be called from Java, C++ or the Apache OpenOffice built-in StarBasic scripting language).
- create and invoke scripts with the office scripting framework (OpenOffice.org 2.0 and later).
You can find the most current version of this document from https://www.openoffice.org/udk/python/python-bridge.html
Download
You can also download this documentation for off-line work.
Download pyuno-doc.zip ( less than 0.5 MB).
State
The Python-UNO bridge is feature complete, but has not been used extensively and therefore may contain some bugs. It is now integrated in the OpenOffice.org source trees. (OpenOffice.org 1.0.x is not supported.)
The documentation in its current state is targeted at developers who already have some experience with Apache OpenOffice API and with some other programming language (Java/C++/StarBasic). It is recommended that you read some background information from the developer manual before looking at the specifics of Python.
Translations
(Find here a shortened Spanish version of this document.)
Tutorial
PyUNO tutorial for Apache OpenOffice
This tutorial shows how the PyUNO bridge can be used to automate Apache OpenOffice. This is not an Apache OpenOffice tutorial, there is lots of resources available in the office development kit and the developer manual.
PyUNO Installation
Since OpenOffice.org 1.1, PyUNO is included in the default installation.
PyUNO bridge modes
PyUNO can be used in three different modes:
- Inside the Apache OpenOffice process within the scripting framework (OpenOffice.org 2.0 and later only !!)
- Inside the Python executable (and outside the Apache OpenOffice process)
Use this mode when you:
- begin to use PyUNO (as it is the more intuitive approach).
- want to trigger script execution by starting a separate process (e.g. a cgi-script within a http-server)
- want the shortest turnaround times (code - execute - code - execute ...)
"Hello World" Example
Make sure that Apache OpenOffice is not running (note that on Windows you must also terminate the Quickstarter in the systemtray at the right bottom of your desktop). Start a system shell (cmd on Win NT/2000/XP, command on Win9x, tcsh or bash on Linux/Unix). Switch to the Apache OpenOffice 'program' directory (e.g. C:\Program Files (x86)\OpenOffice.org 2.4\program ) and start the office with the following command line parameters:
c:\Program Files (x86)\OpenOffice.org 2.4\program> soffice "-accept=socket,host=localhost,port=2002;urp;"
Now, use your favorite text editor to create the following 'hello_world.py' sample program:
import uno """ Here is the sequence of things the lines do: 1. Get the uno component context from the PyUNO runtime 2. Create the UnoUrlResolver 3. Get the central desktop object 4. Declare the ServiceManager 5. Get the central desktop object 6. Access the current writer document 7. Access the document's text property 8. Create a cursor 9. Insert the text into the document """ localContext = uno.getComponentContext() resolver = localContext.ServiceManager.createInstanceWithContext( "com.sun.star.bridge.UnoUrlResolver", localContext ) ctx = resolver.resolve( "uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext" ) smgr = ctx.ServiceManager desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",ctx) model = desktop.getCurrentComponent() text = model.Text cursor = text.createTextCursor() text.insertString( cursor, "Hello World", 0 ) """ Do a nasty thing before exiting the python process. In case the last call is a one-way call (e.g. see idl-spec of insertString), it must be forced out of the remote-bridge caches before python exits the process. Otherwise, the one-way call may or may not reach the target object. I do this here by calling a cheap synchronous call (getPropertyValue).""" ctx.ServiceManager
Now, to start the above script with the Python script located in the 'program' directory:
c:\Program Files\OpenOffice1.1\program> .\python hello_world.py
Note: You must use the script/batch file in the 'program' directory to start Python; simply starting the Python executable in the runtime directory (or from a Python installation installed somewhere else on your machine) will not work.
This script prints "Hello World" into the current writer document.
