[Libreoffice-commits] help.git: AllLangHelp_sbasic.mk source/text
LibreOļ¬ciant (via logerrit)
logerrit at kemper.freedesktop.org
Thu Oct 24 15:23:55 UTC 2019
AllLangHelp_sbasic.mk | 1
source/text/sbasic/guide/basic_2_python.xhp | 180 ++++++++++++++++++++++++++
source/text/sbasic/guide/basic_examples.xhp | 4
source/text/sbasic/python/python_2_basic.xhp | 7 -
source/text/sbasic/python/python_examples.xhp | 4
5 files changed, 186 insertions(+), 10 deletions(-)
New commits:
commit 32ed2dcd315db480d0d85ff0853d19fd4d5916a4
Author: LibreOļ¬ciant <LibreOfficiant at sfr.fr>
AuthorDate: Wed Oct 23 18:16:38 2019 +0200
Commit: Olivier Hallot <olivier.hallot at libreoffice.org>
CommitDate: Thu Oct 24 17:23:33 2019 +0200
Documenting how to call Python routines from Basic macros
Change-Id: I904cafe91ad7c5e72d09209c68db401003dda556
Reviewed-on: https://gerrit.libreoffice.org/81412
Tested-by: Jenkins
Reviewed-by: Jean-Pierre Ledure <jp at ledure.be>
Tested-by: Jean-Pierre Ledure <jp at ledure.be>
Reviewed-by: Olivier Hallot <olivier.hallot at libreoffice.org>
diff --git a/AllLangHelp_sbasic.mk b/AllLangHelp_sbasic.mk
index cc5f02cbc..0b31b3e7a 100644
--- a/AllLangHelp_sbasic.mk
+++ b/AllLangHelp_sbasic.mk
@@ -17,6 +17,7 @@ $(eval $(call gb_AllLangHelp_use_linked_modules,sbasic,\
$(eval $(call gb_AllLangHelp_add_helpfiles,sbasic,\
helpcontent2/source/text/sbasic/guide/access2base \
+ helpcontent2/source/text/sbasic/guide/basic_2_python \
helpcontent2/source/text/sbasic/guide/basic_examples \
helpcontent2/source/text/sbasic/guide/control_properties \
helpcontent2/source/text/sbasic/guide/create_dialog \
diff --git a/source/text/sbasic/guide/basic_2_python.xhp b/source/text/sbasic/guide/basic_2_python.xhp
new file mode 100644
index 000000000..f80cb1658
--- /dev/null
+++ b/source/text/sbasic/guide/basic_2_python.xhp
@@ -0,0 +1,180 @@
+<?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>
+ <h1 id="hd_id811571848401485"><variable id="basic2python"><link href="text/sbasic/guide/basic_2_python.xhp" name="Basic Programming Examples">Calling Python macros 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" 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" id="N0467"><literal>file_len = script.invoke(Array(systemFilePath), Array(), Array())</literal></paragraph>
+ <paragraph role="paragraph" 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 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():</paragraph>
+ <paragraph role="pycode" localize="false" id="N0514"> return platform.system()</paragraph>
+ </pycode>
+ <list type="unordered">
+ <listitem><paragraph 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"> '''LibreOffice 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#py2bah1"/>
+ <embed href="text/sbasic/shared/main0601.xhp#mainsbasic"/>
+ <embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/>
+ </section>
+ </body>
+</helpdocument>
diff --git a/source/text/sbasic/guide/basic_examples.xhp b/source/text/sbasic/guide/basic_examples.xhp
index c89999ece..97b11c065 100644
--- a/source/text/sbasic/guide/basic_examples.xhp
+++ b/source/text/sbasic/guide/basic_examples.xhp
@@ -21,9 +21,6 @@
<section id="basicexamplesh1">
<h1 id="hd_id471559139063621"><variable id="basicexamplestit"><link href="text/sbasic/guide/basic_examples.xhp" name="Basic Programming Examples">Basic Programming Examples</link></variable></h1>
</section>
- <!-- WIP
- <embed href="text/sbasic/python/python_from_basic.xhp#pythonfrombasic"/>
- -->
<embed href="text/sbasic/python/python_handler.xhp#pythonhandler_h1"/>
<embed href="text/sbasic/python/python_listener.xhp#pythonlistener"/>
<embed href="text/sbasic/python/python_session.xhp#pythonsession"/>
@@ -31,6 +28,7 @@
<embed href="text/sbasic/python/python_document_events.xhp#pythonmonitor"/>
<embed href="text/sbasic/guide/show_dialog.xhp#show_dialog"/>
<embed href="text/sbasic/guide/sample_code.xhp#sample_code"/>
+ <embed href="text/sbasic/guide/basic_2_python.xhp#basic2python"/>
<section id="relatedtopics">
<embed href="text/sbasic/shared/main0601.xhp#mainsbasic"/>
</section>
diff --git a/source/text/sbasic/python/python_2_basic.xhp b/source/text/sbasic/python/python_2_basic.xhp
index d3d7e491e..cf26d1290 100644
--- a/source/text/sbasic/python/python_2_basic.xhp
+++ b/source/text/sbasic/python/python_2_basic.xhp
@@ -141,12 +141,11 @@
<paragraph role="bascode" id="N0425" localize="false"> End If</paragraph>
<paragraph role="bascode" id="N0426" localize="false">End Function ' Standard.Scripting.SUM()</paragraph>
</bascode>
- <section id="relatedtopics" >
- <!-- WIP
- <paragraph role="paragraph" id="N0427">Calling Python macros from Basic</paragraph>
- -->
+ <section id="relatedtopics" >
+ <embed href="text/sbasic/guide/basic_2_python.xhp#basic2python"/>
<embed href="text/sbasic/python/python_examples.xhp#pythonexamples2"/>
<embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/>
+ <embed href="text/sbasic/shared/main0601.xhp#mainsbasic"/>
</section>
</body>
</helpdocument>
diff --git a/source/text/sbasic/python/python_examples.xhp b/source/text/sbasic/python/python_examples.xhp
index 8878962d0..c5b496ed0 100644
--- a/source/text/sbasic/python/python_examples.xhp
+++ b/source/text/sbasic/python/python_examples.xhp
@@ -25,9 +25,6 @@
</bookmark>
<h1 id="hd_id201901031407"><variable id="pythonexamples2"><link href="text/sbasic/python/python_examples.xhp" name="python examples">Python programming examples</link></variable></h1>
</section>
- <!-- WIP
- <embed href="text/sbasic/python/python_from_basic.xhp#pythonfrombasic"/>
- -->
<embed href="text/sbasic/python/python_session.xhp#pythonsession"/>
<embed href="text/sbasic/python/python_platform.xhp#pythonplatform"/>
<embed href="text/sbasic/python/python_import.xhp#pythonimporth1"/>
@@ -38,6 +35,7 @@
<embed href="text/sbasic/python/python_listener.xhp#pythonlistener"/>
<embed href="text/sbasic/python/python_2_basic.xhp#py2ba_h1"/>
<section id="relatedtopics">
+ <embed href="text/sbasic/guide/basic_2_python.xhp#basic2python"/>
<embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/>
</section>
</body>
More information about the Libreoffice-commits
mailing list