diff options
Diffstat (limited to 'helpcontent2/source/text/sbasic/python/python_programming.xhp')
| -rw-r--r-- | helpcontent2/source/text/sbasic/python/python_programming.xhp | 321 |
1 files changed, 321 insertions, 0 deletions
diff --git a/helpcontent2/source/text/sbasic/python/python_programming.xhp b/helpcontent2/source/text/sbasic/python/python_programming.xhp new file mode 100644 index 000000000..96deb8606 --- /dev/null +++ b/helpcontent2/source/text/sbasic/python/python_programming.xhp @@ -0,0 +1,321 @@ +<?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"> + <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>uno.py</bookmark_value> + <bookmark_value>uno.py;getComponentContext()</bookmark_value> + </bookmark> + <section id="pythonprogramming"> + <h1 id="hd_id691546462755220"><variable id="pythonprogrammingheading"><link href="text/sbasic/python/python_programming.xhp" name="python programming">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" name="UNO objects functions or services">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" name="description of XSCRIPTCONTEXT">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" name="My macros">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> + <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" name="Python interactive shell">Python interactive shell</link> to get a complete module description using <literal>dir()</literal> and <literal>help()</literal> Python commands.</paragraph> + <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> + <paragraph role="paragraph" id="N0272"><emph>LibreLogo</emph> and <emph>TableSample</emph> installation shared 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" name="Opening a Dialog">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" name="Creating a Listener">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="N0292">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="N0298">desktop = smgr.createInstanceWithContext(DESK , ctx)</paragraph> + <paragraph role="tablecontent" localize="false" id="N0299">doc = desktop.CurrentComponent</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0301">ThisComponent</paragraph> + </tablecell> + </tablerow> + </table> + <h2 id="N0297">Importing an embedded Module</h2> + <section id="PythonEmbeddedImport" > + <paragraph role="paragraph" id="N0298">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/" name="API Documentation site">%PRODUCTNAME Application Programming Interface</link> (API) or download <link href="https://www.libreoffice.org/download/download/" name="SDK download page">%PRODUCTNAME Software Development Kit</link> (SDK).</paragraph> + <paragraph role="paragraph" id="N0299">Importing a Python document embedded module is illustrated below, exception handling is not detailed:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="N0300">import uno, sys</paragraph> + <paragraph role="pycode" localize="false" id="N0301"></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="N0314"></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" name="UNO objects page">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> |