From 32ed2dcd315db480d0d85ff0853d19fd4d5916a4 Mon Sep 17 00:00:00 2001 From: LibreOﬃciant Date: Wed, 23 Oct 2019 18:16:38 +0200 Subject: 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 Tested-by: Jean-Pierre Ledure Reviewed-by: Olivier Hallot --- 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(-) create mode 100644 source/text/sbasic/guide/basic_2_python.xhp diff --git a/AllLangHelp_sbasic.mk b/AllLangHelp_sbasic.mk index cc5f02cbc8..0b31b3e7ae 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 0000000000..f80cb1658c --- /dev/null +++ b/source/text/sbasic/guide/basic_2_python.xhp @@ -0,0 +1,180 @@ + + + + + + Basic to Python + /text/sbasic/guide/basic_2_python.xhp + + + + + Basic;Calling Python + API;SimpleFileAccess + API;PathSettings + +

Calling Python macros from Basic

+ Calling Python scripts from %PRODUCTNAME Basic macros is possible, and valuable features can be obtained such as: + + ComputerName identification or OSName detection are possible, + Basic FileLen() function and com.sun.star.ucb.SimpleFileAccess.getSize() API function exhibit a 2 Gigabytes file size upper limit that Python helps to overcome, + com.sun.star.util.PathSettings can be normalized, + and many more. + + A reasonable exposure to %PRODUCTNAME Basic and to Application Programming Interface (API) features is recommended prior to perform inter-language calls from Basic to Python, to JavaScript or any other script engine. +

Retrieving Python Scripts

+ 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 com.sun.star.script.provider.XScript interface compliant UNO objects allows the execution of Python scripts: + + Option Explicit + + Public Function GetPythonScript(macro As String, _ + Optional location As String) As com.sun.star.script.provider.Xscript + ''' Grab Python script object before execution + ' Arguments: + ' macro : as "library/module.py$macro" or "module.py$macro" + ' location: as "document", "share", "user" or ENUM(eration) + ' Result: + ' located com.sun.star.script.provider.XScript UNO service''' + If IsMissing(location) Then location = "user" + Dim mspf As Object ' com.sun.star.script.provider.MasterScriptProviderFactory + Dim sp As Object ' com.sun.star.script.provider.XScriptProvider compatible + Dim uri As String + If location="document" Then + sp = ThisComponent.getScriptProvider() + Else + mspf = CreateUNOService("com.sun.star.script.provider.MasterScriptProviderFactory") + sp = mspf.createScriptProvider("") + End If + uri = "vnd.sun.star.script:"& macro &"?language=Python&location="& location + GetPythonScript = sp.getScript(uri) + End Function ' GetPythonScript + +

Executing Python Scripts

Syntax

+ workstation_name = script.invoke(Array(), Array(), Array()) + opSysName = script.invoke(Array(), in_outs, Array()) ' in_out is an Array + file_len = script.invoke(Array(systemFilePath), Array(), Array()) + normalizedPath = script.invoke(Array(systemFilePath), Array(), Array()) +

Embedded Scripts Examples

+ Below ComputerName, and GetFilelen routines are calling their Python counterparts, using aforementioned GetPythonScript function. Exception handling is not detailed. + + Option Explicit + Option Compatible ' Properties are supported + + Private scr As Object ' com.sun.star.script.provider.XScript + + Private Property Get ComputerName As String + '''Workstation name''' + scr = GetPythonScript("Platform.py$computer_name", "document") + ComputerName = scr.invoke(Array(), Array(), Array()) + End Property ' ComputerName + + Private Function GetFilelen(systemFilePath As String) As Currency + '''File size in bytes''' + scr = GetPythonScript("Os/Path.py$get_size", Script.ISEMBEDDED) + GetFilelen = scr.invoke(Array(systemFilePath), Array(), Array(),) + End Function ' GetFilelen + + Private Type _SCRIPT_LOCATION + ISEMBEDDED As String ' document script + ISPERSONAL As String ' user script + ISSHARED As String ' %PRODUCTNAME macro + End Type ' _SCRIPT_LOCATION + + Public Function Script() As Object ' Text enumeration + Static enums As _SCRIPT_LOCATION : With enums + If .ISEMBEDDED = "" Then + .ISEMBEDDED = "document" ' document script + .ISPERSONAL = "user" ' user scripts + .ISSHARED = "share" ' %PRODUCTNAME macro + End If : End With ' enums + Script = enums + End Function ' Script + + 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: + + Platform.py + + + # -*- coding: utf-8 -*- + from __future__ import unicode_literals + + import platform + + def computer_name() -> str: + return platform.node() + + def OSname(): + return platform.system() + + + Os/Path.py + + + # -*- coding: utf-8 -*- + from __future__ import unicode_literals + + import os.path + + def get_size(systemFilePath: str) -> str: + return str(os.path.getsize(systemFilePath)) + + def normalyze(systemPath: str) -> str: + return os.path.normpath(systemPath) + +

Personal or Shared Scripts Examples

+ 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 Getting session information. Below OSName, HelloWorld and NormalizePath routines are calling their Python counterparts, using aforementioned GetPythonScript function. Exception handling is not detailed. + + Option Explicit + Option Compatible ' Properties are supported + + Private scr As Object ' com.sun.star.script.provider.XScript + + Private Property Get OSName As String + '''Platform name as "Linux", "Darwin" or "Windows"''' + scr = GetPythonScript("Platform.py$OSname", Script.ISPERSONAL) + OSName = scr.invoke(Array(), Array(), Array()) + End Property ' OSName + + Private Sub HelloWorld() + '''LibreOffice Python shared sample''' + scr = GetPythonScript("HelloWorld.py$HelloWorldPython", Script.ISSHARED) + scr.invoke(Array(), Array(), Array(),) + End Sub ' HelloWorld + + Public Function NormalizePath(systemFilePath As String) As String + '''Strip superfluous '\..' in path''' + scr = GetPythonScript("Os/Path.py$normalyze", "user") + NormalizePath = scr.invoke(Array(systemFilePath), Array(), Array()) + End Function ' NormalizePath + +

Python standard modules

+ %PRODUCTNAME embedded Python contains many standard libraries to benefit from. They bear a rich feature set, such as but not limited to: + + argparse Parser for command-line options, arguments and sub-commands + cmath Mathematical functions for complex numbers + csv CSV files reading and writing + datetime Genuine date and time types + json JSON encoder and decoder + math Mathematical functions + re Regular expression operations + socket Low-level networking interface + sys System-specific parameters and functions + unittest and trace Unit testing framework and Track Python execution + xml.etree.ElementTree ElementTree XML API + +

+ + diff --git a/source/text/sbasic/guide/basic_examples.xhp b/source/text/sbasic/guide/basic_examples.xhp index c89999ece9..97b11c0659 100644 --- a/source/text/sbasic/guide/basic_examples.xhp +++ b/source/text/sbasic/guide/basic_examples.xhp @@ -21,9 +21,6 @@

Basic Programming Examples

@@ -31,6 +28,7 @@

diff --git a/source/text/sbasic/python/python_2_basic.xhp b/source/text/sbasic/python/python_2_basic.xhp index d3d7e491ed..cf26d1290f 100644 --- a/source/text/sbasic/python/python_2_basic.xhp +++ b/source/text/sbasic/python/python_2_basic.xhp @@ -141,12 +141,11 @@ End If End Function ' Standard.Scripting.SUM() -

- +

diff --git a/source/text/sbasic/python/python_examples.xhp b/source/text/sbasic/python/python_examples.xhp index 8878962d00..c5b496ed07 100644 --- a/source/text/sbasic/python/python_examples.xhp +++ b/source/text/sbasic/python/python_examples.xhp @@ -25,9 +25,6 @@

Python programming examples

@@ -38,6 +35,7 @@

-- cgit