1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
|
<?xml version="1.0" encoding="UTF-8"?>
<helpdocument version="1.0">
<!--
* This file is part of the LibreOffice project.
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
*
-->
<meta>
<topic id="text/sbasic/python/Python_Programming" indexer="include" status="PUBLISH">
<title id="tit" xml-lang="en-US">Python : Programming with Python</title>
<filename>/text/sbasic/python/python_programming.xhp</filename>
</topic>
</meta>
<body>
<bookmark branch="index" id="N0218">
<bookmark_value>Python;Programming</bookmark_value>
<bookmark_value>XSCRIPTCONTEXT;Python</bookmark_value>
<bookmark_value>XSCRIPTCONTEXT;getComponentContext</bookmark_value>
<bookmark_value>XSCRIPTCONTEXT;getDesktop</bookmark_value>
<bookmark_value>XSCRIPTCONTEXT;getDocument</bookmark_value>
<bookmark_value>uno.py;getComponentContext</bookmark_value>
<bookmark_value>uno.py;getDesktop</bookmark_value>
<bookmark_value>uno.py;getDocument</bookmark_value>
</bookmark>
<section id="pythonprogramming">
<h1 id="hd_id691546462755220"><variable id="pythonprogrammingheading"><link href="text/sbasic/python/python_programming.xhp">Programming with Python Scripts</link></variable></h1>
</section>
<paragraph role="paragraph" id="N0220">A Python macro is a function within a .py file, identified as a module. Unlike %PRODUCTNAME Basic and its dozen of <link href="text/sbasic/shared/uno_objects.xhp">UNO objects functions or services</link>, Python macros use the <literal>XSCRIPTCONTEXT</literal> UNO single object, shared with JavaScript and BeanShell. The <literal>g_exportedScripts</literal> global tuple explicitly lists selectable macros from a module. Python modules hold autonomous code logic, and are independent from one another.</paragraph>
<h2 id="N0221">XSCRIPTCONTEXT Global Variable</h2>
<paragraph role="paragraph" id="N0222">Genuine Basic UNO facilities can be inferred from <literal>XSCRIPTCONTEXT</literal> global variable. Refer to %PRODUCTNAME API for a complete <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1script_1_1provider_1_1XScriptContext.html">description of XSCRIPTCONTEXT</link>. <literal>XSCRIPTCONTEXT</literal> methods summarize as:</paragraph>
<table id="N0223">
<tablerow>
<tablecell>
<paragraph role="tablehead" id="N0224">Methods</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablehead" id="N0225">Description</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablehead" id="N0226">Mapped in Basic as</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0227">getDocument()</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" id="N0228">The document reference on which the script can operate.</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0229">ThisComponent</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0230">getDesktop()</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" id="N0231">The desktop reference on which the script can operate.</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0232">StarDesktop</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0233">getComponentContext()</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" id="N0234">The component context which the script can use to create other uno components.</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0235">GetDefaultContext</paragraph>
</tablecell>
</tablerow>
</table>
<paragraph role="paragraph" id="N0237"><emph>HelloWorld</emph> and <emph>Capitalise</emph> installation shared scripts illustrate UNO-related macros making use of <literal>XSCRIPTCONTEXT</literal> global variable.</paragraph>
<tip id="N0238">Python standard output file is not available when running Python macros from <menuitem>Tools - Macros - Run Macro</menuitem> menu. Refer to <emph>Input/Output to Screen</emph> for more information.</tip>
<h2 id="N0239">Module import</h2>
<warning id="N0240"><literal>XSCRIPTCONTEXT</literal> is not provided to imported modules.</warning>
<section id="PythonFileSystemImport" >
<paragraph role="paragraph" id="N0241">%PRODUCTNAME Basic libraries contain classes, routines and variables, Python modules contain classes, functions and variables. Common pieces of reusable Python or UNO features must be stored in <link href="text/sbasic/python/python_locations.xhp">My macros</link> within <literal>(User Profile)/Scripts/python/pythonpath</literal>. Python libraries help organize modules in order to prevent module name collisions. Import <literal>uno.py</literal> inside shared modules.</paragraph>
</section>
<section id="uno">
<paragraph role="paragraph" id="N0242">Genuine BASIC UNO facilities can be inferred using <literal>uno.py</literal> module. Use <link href="text/sbasic/python/python_shell.xhp">Python interactive shell</link> to get a complete module description using <literal>dir()</literal> and <literal>help()</literal> Python commands.</paragraph>
<bookmark xml-lang="en-US" branch="index" id="bm_id391659034206678">
<bookmark_value>uno.py</bookmark_value>
<bookmark_value>uno.py;absolutize</bookmark_value>
<bookmark_value>uno.py;createUnoStruct</bookmark_value>
<bookmark_value>uno.py;fileUrlToSystemPath</bookmark_value>
<bookmark_value>uno.py;getClass</bookmark_value>
<bookmark_value>uno.py;getComponentContext</bookmark_value>
<bookmark_value>uno.py;Enum</bookmark_value>
<bookmark_value>uno.py;getConstantByName</bookmark_value>
<bookmark_value>uno.py;isInterface</bookmark_value>
<bookmark_value>uno.py;systemPathToFileUrl</bookmark_value>
</bookmark>
<table id="N0243">
<tablerow>
<tablecell>
<paragraph role="tablehead" id="N0244">Functions</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablehead" id="N0245">Description</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablehead" id="N0246">Mapped in Basic as</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0247">absolutize()</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" id="N0248">Returns an absolute file url from the given urls.</paragraph>
</tablecell>
<tablecell>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0250">createUnoStruct()</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" id="N0251">Creates a UNO struct or exception given by typeName.</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0252">CreateUNOStruct()</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0253">fileUrlToSystemPath()</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" id="N0254">Returns a system path.</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0255">ConvertFromURL()</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0256">getClass()</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" id="N0257">Returns the class of a concrete UNO exception, struct, or interface.</paragraph>
</tablecell>
<tablecell>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0259">getComponentContext()</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" id="N0260">Returns the UNO component context used to initialize the Python runtime.</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0261">GetDefaultContext()</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0262">Enum()</paragraph>
<paragraph role="tablecontent" localize="false" id="N0263">getConstantByName()</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" id="N0264">Looks up the value of an IDL constant by giving its explicit name.</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" id="N0265">See API constant groups</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0266">isInterface()</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" id="N0267">Returns True, when obj is a class of a UNO interface.</paragraph>
</tablecell>
<tablecell>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0269">systemPathToFileUrl()</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" id="N0270">Returns a file URL for the given system path.</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0271">ConvertToURL()</paragraph>
</tablecell>
</tablerow>
</table>
</section>
<paragraph role="paragraph" id="N0272"><emph>LibreLogo</emph>, <emph>NamedRanges</emph>, <emph>SetCellColor</emph> and <emph>TableSample</emph> preinstalled scripts use <literal>uno.py</literal> module.</paragraph>
<h2 id="N0273">More Python-Basic samples</h2>
<table id="N0274">
<tablerow>
<tablecell>
<paragraph role="tablehead" id="N0275">Python UNO</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablehead" id="N0276">Basic UNO features</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0277">ctx = uno.getComponentContext()</paragraph>
<paragraph role="tablecontent" localize="false" id="N0278">smgr = ctx.getServiceManager()</paragraph>
<paragraph role="tablecontent" localize="false" id="N0279">obj = smgr.createInstanceWithContext( .. , ctx)</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0280">CreateUnoService()</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" id="N0284">See <link href="text/sbasic/python/python_dialogs.xhp">Opening a Dialog</link></paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0285">CreateUnoDialog()</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" id="N0286">See <link href="text/sbasic/python/python_listener.xhp">Creating a Listener</link></paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0287">CreateUnoListener()</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" id="N0288">See UNO data types</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0289">CreateUnoValue()</paragraph>
<paragraph role="tablecontent" localize="false" id="N0290">CreateObject()</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N1244">EqualUnoObjects()</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0281">ctx = uno.getComponentContext()</paragraph>
<paragraph role="tablecontent" localize="false" id="N0282">smgr = ctx.getServiceManager()</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0283">GetProcessServiceManager()</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0292">def hasUnoInterfaces(obj, *interfaces):</paragraph>
<paragraph role="tablecontent" localize="false" id="N0293">return set(interfaces).issubset(t.typeName for t in obj.Types)</paragraph>
<!-- Credits:
[Python]Equivalent 'supportsService' by Hubert Lambert
@ https://forum.openoffice.org/fr/forum/viewtopic.php?f=8&t=56597
-->
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0294">HasUnoInterfaces()</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0296">IsUnoStruct()</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0297">ctx = uno.getComponentContext()</paragraph>
<paragraph role="tablecontent" localize="false" id="N0298">smgr = ctx.getServiceManager()</paragraph>
<paragraph role="tablecontent" localize="false" id="N0299">DESK = 'com.sun.star.frame.Desktop'</paragraph>
<paragraph role="tablecontent" localize="false" id="N0300">desktop = smgr.createInstanceWithContext(DESK , ctx)</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N0301">StarDesktop</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N2298">desktop = smgr.createInstanceWithContext(DESK , ctx)</paragraph>
<paragraph role="tablecontent" localize="false" id="N1299">doc = desktop.CurrentComponent</paragraph>
</tablecell>
<tablecell>
<paragraph role="tablecontent" localize="false" id="N1301">ThisComponent</paragraph>
</tablecell>
</tablerow>
</table>
<h2 id="N1297">Importing an embedded Module</h2>
<section id="PythonEmbeddedImport" >
<paragraph role="paragraph" id="N1298">Similarly to %PRODUCTNAME Basic that supports browsing and dynamic loading of libraries, Python libraries can be explored and imported on demand. For more information on library containers, visit <link href="https://api.libreoffice.org/">%PRODUCTNAME Application Programming Interface</link> (API) or download <link href="https://www.libreoffice.org/download/download/">%PRODUCTNAME Software Development Kit</link> (SDK).</paragraph>
<paragraph role="paragraph" id="N3299">Importing a Python document embedded module is illustrated below, exception handling is not detailed:</paragraph>
<pycode>
<paragraph role="pycode" localize="false" id="N1300">import uno, sys, zipimport</paragraph>
<paragraph role="pycode" localize="false" id="N3301"></paragraph>
<paragraph role="pycode" localize="false" id="N0302">def load_library(library_name: str, module_name=None):</paragraph>
<paragraph role="pycode" id="N0303"> """ load library and import module</paragraph>
<paragraph role="pycode" localize="false" id="N0304"> </paragraph>
<paragraph role="pycode" id="N0305"> Adapted from 'Bibliothèque de fonctions' by Hubert Lambert</paragraph>
<paragraph role="pycode" id="N0306"> at https://forum.openoffice.org/fr/forum/viewtopic.php?p=286213"""</paragraph>
<paragraph role="pycode" id="N0307"> doc = XSCRIPTCONTEXT.getDocument() # current document</paragraph>
<paragraph role="pycode" localize="false" id="N0308"> url = uno.fileUrlToSystemPath( \</paragraph>
<paragraph role="pycode" localize="false" id="N0309"> '{}/{}'.format(doc.URL, 'Scripts/python'+library_name)) # ConvertToURL()</paragraph>
<paragraph role="pycode" id="N0310"> if not url in sys.path: # add path if necessary</paragraph>
<paragraph role="pycode" id="N0311"> sys.path.insert(0, url) # doclib takes precedence</paragraph>
<paragraph role="pycode" id="N0312"> if module_name: # import if requested</paragraph>
<paragraph role="pycode" localize="false" id="N0313"> return zipimport.zipimporter(url).load_module(module_name)</paragraph>
<paragraph role="pycode" localize="false" id="N1314"></paragraph>
<paragraph role="pycode" localize="false" id="N0315">def import_embedded_python():</paragraph>
<paragraph role="pycode" id="N0316"> ui = load_library("my_gui",'screen_io') # add <lib> path + import <module> </paragraph>
<paragraph role="pycode" localize="false" id="N0317"> ui.MsgBox(sys.modules.keys())</paragraph>
<paragraph role="pycode" localize="false" id="N0314"></paragraph>
<paragraph role="pycode" localize="false" id="N0319">g_exportedScripts = (import_embedded_python,) # Public macros</paragraph>
</pycode>
</section>
<section id="relatedtopics">
<paragraph role="paragraph" id="N0321"><link href="text/sbasic/shared/uno_objects.xhp">Basic UNO Objects, Functions and Services</link></paragraph>
<embed href="text/sbasic/python/python_import.xhp#pythonimporth1"/>
<embed href="text/sbasic/python/python_screen.xhp#ioscreen"/>
<embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/>
</section>
</body>
</helpdocument>
|
