diff --git a/AllLangHelp_sbasic.mk b/AllLangHelp_sbasic.mk index 81718f70e2..bc44ddbce0 100644 --- a/AllLangHelp_sbasic.mk +++ b/AllLangHelp_sbasic.mk @@ -371,6 +371,7 @@ $(eval $(call gb_AllLangHelp_add_helpfiles,sbasic,\ helpcontent2/source/text/sbasic/python/main0000 \ helpcontent2/source/text/sbasic/python/python_examples \ helpcontent2/source/text/sbasic/python/python_ide \ + helpcontent2/source/text/sbasic/python/python_import \ helpcontent2/source/text/sbasic/python/python_locations \ helpcontent2/source/text/sbasic/python/python_platform \ helpcontent2/source/text/sbasic/python/python_programming \ diff --git a/source/text/sbasic/python/python_examples.xhp b/source/text/sbasic/python/python_examples.xhp index 067f239dfc..bdfb2488a3 100644 --- a/source/text/sbasic/python/python_examples.xhp +++ b/source/text/sbasic/python/python_examples.xhp @@ -33,7 +33,7 @@ --> - + diff --git a/source/text/sbasic/python/python_import.xhp b/source/text/sbasic/python/python_import.xhp new file mode 100644 index 0000000000..3ac240d87c --- /dev/null +++ b/source/text/sbasic/python/python_import.xhp @@ -0,0 +1,118 @@ + + + + + + Python : Importing Modules + /text/sbasic/python/python_import.xhp + + + + + Python;import + Python;Modules + Python;pythonpath + PythonLibraries + +

Importing Python Modules

+ LibreOffice Python scripts come in three distinct flavors, they can be personal, shared or embedded in documents. They are stored in varying places described in Python Scripts Organization and Location. In order to import Python modules, their locations must be known from Python at run time. + This mechanism is illustrated for file system based modules and document based modules. Exception handling is omitted for clarity. The terms library or directory, scripts or modules are used interchangeably. A Python macro refers to a function inside a module. + Note that <User Profile>/Scripts/python/pythonpath local directory is always explored when running a Python macro from <User Profile>/Scripts/python. +

File System module import

+ +

User or Shared Modules

+ Personal & shared Python scripts can be imported once their directories are included in Python run time path. Refer to Getting session information page for more details regarding omitted Session Class. + + # -*- coding: utf-8 -*- + from __future__ import unicode_literals + import sys + + user_lib = Session().UserPythonScripts # User scripts location + if not user_lib in sys.path: + sys.path.insert(0, user_lib) # Add to search path + import screen_io as ui # 'screen_io.py' module resides in user_lib directory + # Your code follows here + + This Python example exposes a local XSCRIPTCONTEXT variable to an imported module: + + # -*- coding: utf-8 -*- + from __future__ import unicode_literals + import uno, sys + + share_lib = Session.SharedPythonScripts() # Shared scripts location + if not share_lib in sys.path: + sys.path.insert(0, share_lib) # Add to search path + from IDE_utils import ScriptContext # 'IDE_utils.py' sits with shared Python scripts. + XSCRIPTCONTEXT = ScriptContext(uno.getComponentContext) + # Your code follows here + +

Installation Modules for Applications

+ Unlike personal and shared scripts, %PRODUCTNAME installation scripts can be imported any time. Next to uno & unohelper %PRODUCTNAME Python modules, other scripts present in <installation_path>/program directory can be imported directly, such as the msgbox module. + With Python shell: + >>> import msgbox, uno + >>> myBox = msgbox.MsgBox(uno.getComponentContext()) + >>> myBox.addButton("okay") + >>> myBox.renderFromButtonSize() + >>> myBox.numberOflines = 2 + >>> print(myBox.show("A small message",0,"Dialog title")) +

Document Module Import

+ Importing a Python document embedded module is illustrated below. Error handling is not detailed. Python run time path is updated when document has been opened and before closure. Refer to Event-Driven Macros to learn how to associate Python macros to document events. + + # -*- coding: utf-8 -*- + from __future__ import unicode_literals + + import sys, uno + + def OnDocPostOpenLoadPython(): + """ Prepare Python modules import when doc. loaded """ + PythonLibraries.loadLibrary('lib/subdir') # Add directory to search path + PythonLibraries.loadLibrary('my_gui', 'screen_io') # Add dir. & import screen_io + + def OnDocQueryCloseUnloadPython(): + """ Cleanup PYTHON_PATH when doc. Gets closed """ + PythonLibraries.unloadLibrary('my_gui') # Python runtime path cleanup + # Note: imported modules remain loaded in this example.. + + class PythonLibraries(): + """ Python library loader and module importer + + adapted from 'Bibliothèque de fonctions' by Hubert Lambert + at https://forum.openoffice.org/fr/forum/viewtopic.php?p=286213 """ + def isImportedModule(module_name: str) -> bool: + """ Check run time module list """ + return (module_name in sys.modules.keys()) + def isLoadedLibrary(lib_name: str) -> bool: + """ Check PYTHON_PATH content """ + return (lib_name in sys.path) + def loadLibrary(lib_name: str, module_name=None): + """ add directory to PYTHON_PATH, import named module """ + doc = XSCRIPTCONTEXT.getDocument() + url = uno.fileUrlToSystemPath( + '{}/{}'.format(doc.URL,'Scripts/python/'+lib_name) + if not url in sys.path: + sys.path.insert(0, url) + if module_name and not module_name in sys.modules.keys(): + return zipimport.zipimporter(url).load_module(module_name) + def unloadLibrary(lib_name: str): + """ remove directory from PYTHON_PATH """ + sys.path.remove(lib_name) + + g_exportedScripts = (OnDocPostOpenLoadPython, OnDocQueryCloseUnloadPython) + +
+ + + + + Refer to Creating a Python Listener for examples of event-driven macros. + +
+ +