diff options
Diffstat (limited to 'helpcontent2/source/text/sbasic/guide/basic_2_python.xhp')
| -rw-r--r-- | helpcontent2/source/text/sbasic/guide/basic_2_python.xhp | 181 |
1 files changed, 181 insertions, 0 deletions
diff --git a/helpcontent2/source/text/sbasic/guide/basic_2_python.xhp b/helpcontent2/source/text/sbasic/guide/basic_2_python.xhp new file mode 100644 index 000000000..4ea2d89f4 --- /dev/null +++ b/helpcontent2/source/text/sbasic/guide/basic_2_python.xhp @@ -0,0 +1,181 @@ +<?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/guide/basic_2_python"> + <title id="tit" xml-lang="en-US">Basic to Python</title> + <filename>/text/sbasic/guide/basic_2_python.xhp</filename> + </topic> + </meta> + <body> + <bookmark branch="index" id="N0430"> + <bookmark_value>Basic;Calling Python</bookmark_value> + <bookmark_value>API;SimpleFileAccess</bookmark_value> + <bookmark_value>API;PathSettings</bookmark_value> + <bookmark_value>API;XScript</bookmark_value> + </bookmark> + <h1 id="hd_id811571848401485"><variable id="basic2python"><link href="text/sbasic/guide/basic_2_python.xhp" name="Basic Programming Examples">Calling Python Scripts from Basic</link></variable></h1> + <paragraph role="paragraph" id="N0432">Calling Python scripts from %PRODUCTNAME Basic macros is possible, and valuable features can be obtained such as:</paragraph> + <list type="unordered"> + <listitem><paragraph role="listitem" id="N0433"><literal>ComputerName</literal> identification or <literal>OSName</literal> detection are possible,</paragraph></listitem> + <listitem><paragraph role="listitem" id="N0434">Basic <literal>FileLen()</literal> function and <link href="https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1ucb_1_1SimpleFileAccess.html" name="ucb.SimpleFileAccess">com.sun.star.ucb.SimpleFileAccess.</link><literal>getSize()</literal> API function exhibit a 2 Gigabytes file size upper limit that Python helps to overcome,</paragraph></listitem> + <listitem><paragraph role="listitem" id="N0435"><link href="https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1util_1_1PathSettings.html" name="util.PathSettings">com.sun.star.util.PathSettings</link> can be normalized,</paragraph></listitem> + <listitem><paragraph role="listitem" id="N0436">and many more.</paragraph></listitem> + </list> + <tip id="N0437">A reasonable exposure to %PRODUCTNAME Basic and to <link href="https://api.libreoffice.org/" name="Application Programming Interface">Application Programming Interface (API)</link> features is recommended prior to perform inter-language calls from Basic to Python, to JavaScript or any other script engine.</tip> + <h2 id="N0438">Retrieving Python Scripts</h2> + <paragraph role="paragraph" id="N0439">Python scripts can be personal, shared, or embedded in documents. In order to execute them, %PRODUCTNAME Basic needs to be provided with Python script locations. Locating <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1script_1_1provider_1_1XScript.html" name="script.provider.XScript">com.sun.star.script.provider.XScript</link> interface compliant UNO objects allows the execution of Python scripts:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="N0440">Option Explicit</paragraph> + <paragraph role="bascode" localize="false" id="N0441"> </paragraph> + <paragraph role="bascode" localize="false" id="N0442">Public Function GetPythonScript(macro As String, _</paragraph> + <paragraph role="bascode" localize="false" id="N0443"> Optional location As String) As com.sun.star.script.provider.Xscript</paragraph> + <paragraph role="bascode" id="N0444"> ''' Grab Python script object before execution</paragraph> + <paragraph role="bascode" id="N0445"> ' Arguments:</paragraph> + <paragraph role="bascode" id="N0446"> ' macro : as "library/module.py$macro" or "module.py$macro"</paragraph> + <paragraph role="bascode" id="N0447"> ' location: as "document", "share", "user" or ENUM(eration)</paragraph> + <paragraph role="bascode" id="N0448"> ' Result:</paragraph> + <paragraph role="bascode" id="N0449"> ' located com.sun.star.script.provider.XScript UNO service'''</paragraph> + <paragraph role="bascode" localize="false" id="N0450"> If IsMissing(location) Then location = "user"</paragraph> + <paragraph role="bascode" localize="false" id="N0451"> Dim mspf As Object ' com.sun.star.script.provider.MasterScriptProviderFactory</paragraph> + <paragraph role="bascode" id="N0452"> Dim sp As Object ' com.sun.star.script.provider.XScriptProvider compatible</paragraph> + <paragraph role="bascode" localize="false" id="N0453"> Dim uri As String</paragraph> + <paragraph role="bascode" localize="false" id="N0454"> If location="document" Then</paragraph> + <paragraph role="bascode" localize="false" id="N0455"> sp = ThisComponent.getScriptProvider()</paragraph> + <paragraph role="bascode" localize="false" id="N0456"> Else</paragraph> + <paragraph role="bascode" localize="false" id="N0457"> mspf = CreateUNOService("com.sun.star.script.provider.MasterScriptProviderFactory")</paragraph> + <paragraph role="bascode" localize="false" id="N0458"> sp = mspf.createScriptProvider("")</paragraph> + <paragraph role="bascode" localize="false" id="N0459"> End If</paragraph> + <paragraph role="bascode" localize="false" id="N0460"> uri = "vnd.sun.star.script:"& macro &"?language=Python&location="& location</paragraph> + <paragraph role="bascode" localize="false" id="N0461"> GetPythonScript = sp.getScript(uri)</paragraph> + <paragraph role="bascode" localize="false" id="N0462">End Function ' GetPythonScript</paragraph> + </bascode> + <h2 id="N0463">Executing Python Scripts</h2> + <embed href="text/sbasic/python/python_2_basic.xhp#APIScriptingFramework" /> + <h3 id="N0464">Syntax</h3> + <paragraph role="paragraph" localize="false" id="N0465"><literal>workstation_name = script.invoke(Array(), Array(), Array())</literal></paragraph> + <paragraph role="paragraph" id="N0466"><literal>opSysName = script.invoke(Array(), in_outs, Array())</literal> ' in_out is an Array</paragraph> + <paragraph role="paragraph" localize="false" id="N0467"><literal>file_len = script.invoke(Array(systemFilePath), Array(), Array())</literal></paragraph> + <paragraph role="paragraph" localize="false" id="N0468"><literal>normalizedPath = script.invoke(Array(systemFilePath), Array(), Array())</literal></paragraph> + <h3 id="N0469">Embedded Scripts Examples</h3> + <paragraph role="paragraph" id="N0470">Below <literal>ComputerName</literal>, and <literal>GetFilelen</literal> routines are calling their Python counterparts, using aforementioned <literal>GetPythonScript</literal> function. Exception handling is not detailed.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="N0471">Option Explicit</paragraph> + <paragraph role="bascode" id="N0472">Option Compatible ' Properties are supported</paragraph> + <paragraph role="bascode" localize="false" id="N0473"> </paragraph> + <paragraph role="bascode" localize="false" id="N0474">Private scr As Object ' com.sun.star.script.provider.XScript</paragraph> + <paragraph role="bascode" localize="false" id="N0475"> </paragraph> + <paragraph role="bascode" localize="false" id="N0476">Private Property Get ComputerName As String</paragraph> + <paragraph role="bascode" id="N0477"> '''Workstation name'''</paragraph> + <paragraph role="bascode" localize="false" id="N0478"> scr = GetPythonScript("Platform.py$computer_name", "document")</paragraph> + <paragraph role="bascode" localize="false" id="N0479"> ComputerName = scr.invoke(Array(), Array(), Array())</paragraph> + <paragraph role="bascode" localize="false" id="N0480">End Property ' ComputerName</paragraph> + <paragraph role="bascode" localize="false" id="N0481"> </paragraph> + <paragraph role="bascode" localize="false" id="N0482">Private Function GetFilelen(systemFilePath As String) As Currency</paragraph> + <paragraph role="bascode" id="N0483"> '''File size in bytes'''</paragraph> + <paragraph role="bascode" localize="false" id="N0484"> scr = GetPythonScript("Os/Path.py$get_size", Script.ISEMBEDDED)</paragraph> + <paragraph role="bascode" localize="false" id="N0485"> GetFilelen = scr.invoke(Array(systemFilePath), Array(), Array(),)</paragraph> + <paragraph role="bascode" localize="false" id="N0486">End Function ' GetFilelen</paragraph> + <paragraph role="bascode" localize="false" id="N0487"> </paragraph> + <paragraph role="bascode" localize="false" id="N0488">Private Type _SCRIPT_LOCATION</paragraph> + <paragraph role="bascode" id="N0489"> ISEMBEDDED As String ' document script</paragraph> + <paragraph role="bascode" id="N0490"> ISPERSONAL As String ' user script</paragraph> + <paragraph role="bascode" id="N0491"> ISSHARED As String ' %PRODUCTNAME macro</paragraph> + <paragraph role="bascode" localize="false" id="N0492">End Type ' _SCRIPT_LOCATION</paragraph> + <paragraph role="bascode" localize="false" id="N0493"> </paragraph> + <paragraph role="bascode" localize="false" id="N0494">Public Function Script() As Object ' Text enumeration</paragraph> + <paragraph role="bascode" localize="false" id="N0495"> Static enums As _SCRIPT_LOCATION : With enums</paragraph> + <paragraph role="bascode" localize="false" id="N0496"> If .ISEMBEDDED = "" Then</paragraph> + <paragraph role="bascode" id="N0497"> .ISEMBEDDED = "document" ' document script</paragraph> + <paragraph role="bascode" id="N0498"> .ISPERSONAL = "user" ' user scripts</paragraph> + <paragraph role="bascode" id="N0499"> .ISSHARED = "share" ' %PRODUCTNAME macro</paragraph> + <paragraph role="bascode" localize="false" id="N0500"> End If : End With ' enums</paragraph> + <paragraph role="bascode" localize="false" id="N0501"> Script = enums</paragraph> + <paragraph role="bascode" localize="false" id="N0502">End Function ' Script</paragraph> + </bascode> + <paragraph role="paragraph" id="N0503">Two different Python modules are called. They can either be embedded in the current document, either be stored on the file system. Argument type checking is skipped for clarity:</paragraph> + <list type="unordered"> + <listitem><paragraph localize="false" role="paragraph" id="N0504">Platform.py</paragraph></listitem> + </list> + <pycode> + <paragraph role="pycode" localize="false" id="N0505"># -*- coding: utf-8 -*-</paragraph> + <paragraph role="pycode" localize="false" id="N0506">from __future__ import unicode_literals</paragraph> + <paragraph role="pycode" localize="false" id="N0507"> </paragraph> + <paragraph role="pycode" localize="false" id="N0508">import platform</paragraph> + <paragraph role="pycode" localize="false" id="N0509"> </paragraph> + <paragraph role="pycode" localize="false" id="N0510">def computer_name() -> str:</paragraph> + <paragraph role="pycode" localize="false" id="N0511"> return platform.node()</paragraph> + <paragraph role="pycode" localize="false" id="N0512"> </paragraph> + <paragraph role="pycode" localize="false" id="N0513">def OSname() -> str:</paragraph> + <paragraph role="pycode" localize="false" id="N0514"> return platform.system()</paragraph> + </pycode> + <list type="unordered"> + <listitem><paragraph localize="false" role="paragraph" id="N0515">Os/Path.py</paragraph></listitem> + </list> + <pycode> + <paragraph role="pycode" localize="false" id="N0516"># -*- coding: utf-8 -*-</paragraph> + <paragraph role="pycode" localize="false" id="N0517">from __future__ import unicode_literals</paragraph> + <paragraph role="pycode" localize="false" id="N0518"> </paragraph> + <paragraph role="pycode" localize="false" id="N0519">import os.path</paragraph> + <paragraph role="pycode" localize="false" id="N0520"> </paragraph> + <paragraph role="pycode" localize="false" id="N0521">def get_size(systemFilePath: str) -> str:</paragraph> + <paragraph role="pycode" localize="false" id="N0522"> return str(os.path.getsize(systemFilePath))</paragraph> + <paragraph role="pycode" localize="false" id="N0523"> </paragraph> + <paragraph role="pycode" localize="false" id="N0524">def normalyze(systemPath: str) -> str:</paragraph> + <paragraph role="pycode" localize="false" id="N0525"> return os.path.normpath(systemPath)</paragraph> + </pycode> + <h3 id="N0526">Personal or Shared Scripts Examples</h3> + <paragraph role="paragraph" id="N0527">The calling mechanism for personal or shared Python scripts is identical to that of embedded scripts. Library names are mapped to folders. Computing %PRODUCTNAME user profile and shared modules system file paths can be performed as detailed in <link href="text/sbasic/python/python_session.xhp">Getting session information</link>. Below <literal>OSName</literal>, <literal>HelloWorld</literal> and <literal>NormalizePath</literal> routines are calling their Python counterparts, using aforementioned <literal>GetPythonScript</literal> function. Exception handling is not detailed.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="N0528">Option Explicit</paragraph> + <paragraph role="bascode" id="N0529">Option Compatible ' Properties are supported</paragraph> + <paragraph role="bascode" localize="false" id="N0530"> </paragraph> + <paragraph role="bascode" localize="false" id="N0531">Private scr As Object ' com.sun.star.script.provider.XScript</paragraph> + <paragraph role="bascode" localize="false" id="N0532"> </paragraph> + <paragraph role="bascode" localize="false" id="N0533">Private Property Get OSName As String</paragraph> + <paragraph role="bascode" id="N0534"> '''Platform name as "Linux", "Darwin" or "Windows"'''</paragraph> + <paragraph role="bascode" localize="false" id="N0535"> scr = GetPythonScript("Platform.py$OSname", Script.ISPERSONAL)</paragraph> + <paragraph role="bascode" localize="false" id="N0536"> OSName = scr.invoke(Array(), Array(), Array()) </paragraph> + <paragraph role="bascode" localize="false" id="N0537">End Property ' OSName</paragraph> + <paragraph role="bascode" localize="false" id="N0538"> </paragraph> + <paragraph role="bascode" localize="false" id="N0539">Private Sub HelloWorld()</paragraph> + <paragraph role="bascode" id="N0540"> '''%PRODUCTNAME Python shared sample'''</paragraph> + <paragraph role="bascode" localize="false" id="N0541"> scr = GetPythonScript("HelloWorld.py$HelloWorldPython", Script.ISSHARED)</paragraph> + <paragraph role="bascode" localize="false" id="N0542"> scr.invoke(Array(), Array(), Array(),)</paragraph> + <paragraph role="bascode" localize="false" id="N0543">End Sub ' HelloWorld</paragraph> + <paragraph role="bascode" localize="false" id="N0544"> </paragraph> + <paragraph role="bascode" localize="false" id="N0545">Public Function NormalizePath(systemFilePath As String) As String</paragraph> + <paragraph role="bascode" id="N0546"> '''Strip superfluous '\..' in path'''</paragraph> + <paragraph role="bascode" localize="false" id="N0547"> scr = GetPythonScript("Os/Path.py$normalyze", "user")</paragraph> + <paragraph role="bascode" localize="false" id="N0548"> NormalizePath = scr.invoke(Array(systemFilePath), Array(), Array())</paragraph> + <paragraph role="bascode" localize="false" id="N0549">End Function ' NormalizePath</paragraph> + </bascode> + <h2 id="N0550">Python standard modules</h2> + <paragraph role="paragraph" id="N0551">%PRODUCTNAME embedded Python contains many standard libraries to benefit from. They bear a rich feature set, such as but not limited to:</paragraph> + <list type="unordered"> + <listitem><paragraph role="listitem" id="N0552"><emph>argparse</emph> Parser for command-line options, arguments and sub-commands</paragraph></listitem> + <listitem><paragraph role="listitem" id="N0553"><emph>cmath</emph> Mathematical functions for complex numbers</paragraph></listitem> + <listitem><paragraph role="listitem" id="N0554"><emph>csv</emph> CSV files reading and writing</paragraph></listitem> + <listitem><paragraph role="listitem" id="N0555"><emph>datetime</emph> Genuine date and time types</paragraph></listitem> + <listitem><paragraph role="listitem" id="N0556"><emph>json</emph> JSON encoder and decoder</paragraph></listitem> + <listitem><paragraph role="listitem" id="N0557"><emph>math</emph> Mathematical functions</paragraph></listitem> + <listitem><paragraph role="listitem" id="N0558"><emph>re</emph> Regular expression operations</paragraph></listitem> + <listitem><paragraph role="listitem" id="N0559"><emph>socket</emph> Low-level networking interface</paragraph></listitem> + <listitem><paragraph role="listitem" id="N0560"><emph>sys</emph> System-specific parameters and functions</paragraph></listitem> + <listitem><paragraph role="listitem" id="N0561"><emph>unittest</emph> and <emph>trace</emph> Unit testing framework and Track Python execution</paragraph></listitem> + <listitem><paragraph role="listitem" id="N0562"><emph>xml.etree.ElementTree</emph> ElementTree XML API</paragraph></listitem> + </list> + <section id="relatedtopics" > + <embed href="text/sbasic/python/python_2_basic.xhp#py2ba_h1"/> + <embed href="text/sbasic/shared/main0601.xhp#mainsbasic"/> + <embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/> + </section> + </body> +</helpdocument> |