forked from amazingfate/help
7e42394ecb
Replacement done with
find . -name \*.xhp -print0 |xargs -0 -P 0 perl -CS -pi -e \
's#(<link[^>]*?) +name *="[^"]*" *( [^>]+|) *>#$1$2>#g'
(note some inconsistencies with space between name and = and also having
empty value, and some more complicated expression to also clear up
double space before/after the attribute)
translation files will be prepped with:
find */helpcontent2 -name \*.po -print0 |xargs -0 -P 0 perl -CS -pi -e \
$'s#(<link[^>]*?) +name=(?:\\\\"[^"]*\\\\"|\'[^\']*\') *( [^>]+|) *(/?>)#$1$2$3#g unless /^#/'
(note that not all languages use the " as quote character for the
attributes, but that also single quotes appera in the po file. Hence
the use of the shell $'string' syntax to be able to quote ' as \'
It also requires to quote the backslash, so that it needs to be escaped
once for the shell, then another time for perl. Also don't work on
obsolete strings (those are prefixed with #~ in the po files)
Also note that <link..></link> gets turned into <link ../> during
translation extraction (along with removal of the space between the
attribute name and the value), so the pattern needs to be slightly
different here)
Change-Id: I95e53a08e6b0095cd894109ea0de154cc4859d8f
Reviewed-on: https://gerrit.libreoffice.org/c/help/+/143713
Tested-by: Jenkins
Reviewed-by: Christian Lohmaier <lohmaier+LibreOffice@googlemail.com>
182 lines
18 KiB
XML
182 lines
18 KiB
XML
<?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">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">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">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/">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">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>
|