[Libreoffice-commits] help.git: AllLangHelp_sbasic.mk source/text
Libreoffice Gerrit user
logerrit at kemper.freedesktop.org
Thu Feb 14 12:21:04 UTC 2019
AllLangHelp_sbasic.mk | 1
source/text/sbasic/python/python_examples.xhp | 2
source/text/sbasic/python/python_import.xhp | 118 ++++++++++++++++++++++++++
3 files changed, 120 insertions(+), 1 deletion(-)
New commits:
commit 675b040e842403b91e2246ed78c6016ef10ddd0d
Author: --author=Alain Romedenne <OpenOfficiant at sfr.fr>
AuthorDate: Wed Feb 13 11:31:15 2019 -0200
Commit: Olivier Hallot <olivier.hallot at libreoffice.org>
CommitDate: Thu Feb 14 13:20:40 2019 +0100
Python: Help page for module import
Change-Id: I35ce948bbd0abcb2daeb272fe4d436cd05bb24ed
Reviewed-on: https://gerrit.libreoffice.org/67773
Tested-by: Jenkins
Reviewed-by: Olivier Hallot <olivier.hallot at libreoffice.org>
diff --git a/AllLangHelp_sbasic.mk b/AllLangHelp_sbasic.mk
index 81718f70e..bc44ddbce 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 067f239df..bdfb2488a 100644
--- a/source/text/sbasic/python/python_examples.xhp
+++ b/source/text/sbasic/python/python_examples.xhp
@@ -33,7 +33,7 @@
-->
<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#pythonimport"/>-->
+ <embed href="text/sbasic/python/python_import.xhp#pythonimporth1"/>
<embed href="text/sbasic/python/python_screen.xhp#ioscreen"/>
<embed href="text/sbasic/python/python_shell.xhp#pythonshell1"/>
</body>
diff --git a/source/text/sbasic/python/python_import.xhp b/source/text/sbasic/python/python_import.xhp
new file mode 100644
index 000000000..3ac240d87
--- /dev/null
+++ b/source/text/sbasic/python/python_import.xhp
@@ -0,0 +1,118 @@
+<?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/python/python_import">
+ <title id="tit" xml-lang="en-US">Python : Importing Modules</title>
+ <filename>/text/sbasic/python/python_import.xhp</filename>
+ </topic>
+ </meta>
+ <body>
+ <bookmark branch="index" id="N0461">
+ <bookmark_value>Python;import</bookmark_value>
+ <bookmark_value>Python;Modules</bookmark_value>
+ <bookmark_value>Python;pythonpath</bookmark_value>
+ <bookmark_value>PythonLibraries</bookmark_value>
+ </bookmark>
+ <h1 id="N0462"><variable id="pythonimporth1"><link href="text/sbasic/python/python_import.xhp" name="python imports">Importing Python Modules</link></variable></h1>
+ <paragraph role="paragraph" id="N0463">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 <link href="text/sbasic/python/python_locations.xhp">Python Scripts Organization and Location</link>. In order to import Python modules, their locations must be known from Python at run time.</paragraph>
+ <paragraph role="paragraph" id="N0464">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.</paragraph>
+ <warning id="N0465">Note that <literal><User Profile>/Scripts/python/pythonpath</literal> local directory is always explored when running a Python macro from <literal><User Profile>/Scripts/python</literal>.</warning>
+ <h2 id="N0466">File System module import</h2>
+ <embed href="text/sbasic/python/python_programming.xhp#PythonFileSystemImport"/>
+ <h3 id="N0467">User or Shared Modules</h3>
+ <paragraph role="paragraph" id="N0468">Personal & shared Python scripts can be imported once their directories are included in Python run time path. Refer to <link href="text/sbasic/python/python_session.xhp">Getting session information</link> page for more details regarding omitted Session Class.</paragraph>
+ <pycode>
+ <paragraph role="pycode" localize="false" id="N0469"># -*- coding: utf-8 -*-</paragraph>
+ <paragraph role="pycode" localize="false" id="N0470">from __future__ import unicode_literals</paragraph>
+ <paragraph role="pycode" localize="false" id="N0471">import sys</paragraph>
+ <paragraph role="pycode" localize="false" id="N0472"> </paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0473">user_lib = Session().UserPythonScripts # User scripts location</paragraph>
+ <paragraph role="pycode" localize="false" id="N0474">if not user_lib in sys.path:</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0475"> sys.path.insert(0, user_lib) # Add to search path</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0476">import screen_io as ui # 'screen_io.py' module resides in user_lib directory</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0477"># Your code follows here</paragraph>
+ </pycode>
+ <paragraph role="paragraph" id="N0478">This Python example exposes a local XSCRIPTCONTEXT variable to an imported module:</paragraph>
+ <pycode>
+ <paragraph role="pycode" localize="false" id="N0479"># -*- coding: utf-8 -*-</paragraph>
+ <paragraph role="pycode" localize="false" id="N0480">from __future__ import unicode_literals</paragraph>
+ <paragraph role="pycode" localize="false" id="N0481">import uno, sys</paragraph>
+ <paragraph role="pycode" localize="false" id="N0482"> </paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0483">share_lib = Session.SharedPythonScripts() # Shared scripts location</paragraph>
+ <paragraph role="pycode" localize="false" id="N0484">if not share_lib in sys.path:</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0485"> sys.path.insert(0, share_lib) # Add to search path</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0486">from IDE_utils import ScriptContext # 'IDE_utils.py' sits with shared Python scripts.</paragraph>
+ <paragraph role="pycode" localize="false" id="N0487">XSCRIPTCONTEXT = ScriptContext(uno.getComponentContext)</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0488"># Your code follows here</paragraph>
+ </pycode>
+ <h3 id="N0489">Installation Modules for Applications</h3>
+ <paragraph role="paragraph" id="N0490">Unlike personal and shared scripts, %PRODUCTNAME installation scripts can be imported any time. Next to <literal>uno</literal> & <literal>unohelper</literal> %PRODUCTNAME Python modules, other scripts present in <literal><installation_path>/program</literal> directory can be imported directly, such as the <literal>msgbox</literal> module.</paragraph>
+ <paragraph role="paragraph" id="N0491">With Python shell:</paragraph>
+ <paragraph role="paragraph" localize="false" id="N0492"><literal>>>> import msgbox, uno</literal></paragraph>
+ <paragraph role="paragraph" localize="false" id="N0494"><literal>>>> myBox = msgbox.MsgBox(uno.getComponentContext())</literal></paragraph>
+ <paragraph role="paragraph" localize="false" id="N0495"><literal>>>> myBox.addButton("okay")</literal></paragraph>
+ <paragraph role="paragraph" localize="false" id="N0496"><literal>>>> myBox.renderFromButtonSize()</literal></paragraph>
+ <paragraph role="paragraph" localize="false" id="N0497"><literal>>>> myBox.numberOflines = 2</literal></paragraph>
+ <paragraph role="paragraph" localize="false" id="N0499"><literal>>>> print(myBox.show("A small message",0,"Dialog title"))</literal></paragraph>
+ <h2 id="N0534">Document Module Import</h2>
+ <paragraph role="paragraph" id="N0535">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 <link href="text/sbasic/shared/01040000.xhp">Event-Driven Macros</link> to learn how to associate Python macros to document events.</paragraph>
+ <pycode>
+ <paragraph role="pycode" localize="false" id="N0536"># -*- coding: utf-8 -*-</paragraph>
+ <paragraph role="pycode" localize="false" id="N0536">from __future__ import unicode_literals</paragraph>
+ <paragraph role="pycode" localize="false" id="N0537"> </paragraph>
+ <paragraph role="pycode" localize="false" id="N0538">import sys, uno</paragraph>
+ <paragraph role="pycode" localize="false" id="N0539"> </paragraph>
+ <paragraph role="pycode" localize="false" id="N0540">def OnDocPostOpenLoadPython():</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0541"> """ Prepare Python modules import when doc. loaded """</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0542"> PythonLibraries.loadLibrary('lib/subdir') # Add directory to search path </paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0543"> PythonLibraries.loadLibrary('my_gui', 'screen_io') # Add dir. & import screen_io</paragraph>
+ <paragraph role="pycode" localize="false" id="N0544"> </paragraph>
+ <paragraph role="pycode" localize="false" id="N0545">def OnDocQueryCloseUnloadPython():</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0546"> """ Cleanup PYTHON_PATH when doc. Gets closed """ </paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0547"> PythonLibraries.unloadLibrary('my_gui') # Python runtime path cleanup</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0548"> # Note: imported modules remain loaded in this example..</paragraph>
+ <paragraph role="pycode" localize="false" id="N0549"> </paragraph>
+ <paragraph role="pycode" localize="false" id="N0552">class PythonLibraries():</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0553"> """ Python library loader and module importer</paragraph>
+ <paragraph role="pycode" localize="false" id="N0554"> </paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0555"> adapted from 'Bibliothèque de fonctions' by Hubert Lambert</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0556"> at https://forum.openoffice.org/fr/forum/viewtopic.php?p=286213 """</paragraph>
+ <paragraph role="pycode" localize="false" id="N0557">def isImportedModule(module_name: str) -> bool:</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0558"> """ Check run time module list """</paragraph>
+ <paragraph role="pycode" localize="false" id="N0559"> return (module_name in sys.modules.keys())</paragraph>
+ <paragraph role="pycode" localize="false" id="N0560">def isLoadedLibrary(lib_name: str) -> bool:</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0561"> """ Check PYTHON_PATH content """</paragraph>
+ <paragraph role="pycode" localize="false" id="N0562"> return (lib_name in sys.path)</paragraph>
+ <paragraph role="pycode" localize="false" id="N0563">def loadLibrary(lib_name: str, module_name=None):</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0564"> """ add directory to PYTHON_PATH, import named module """</paragraph>
+ <paragraph role="pycode" localize="false" id="N0565"> doc = XSCRIPTCONTEXT.getDocument()</paragraph>
+ <paragraph role="pycode" localize="false" id="N0566"> url = uno.fileUrlToSystemPath(</paragraph>
+ <paragraph role="pycode" localize="false" id="N0567"> '{}/{}'.format(doc.URL,'Scripts/python/'+lib_name)</paragraph>
+ <paragraph role="pycode" localize="false" id="N0568"> if not url in sys.path:</paragraph>
+ <paragraph role="pycode" localize="false" id="N0569"> sys.path.insert(0, url)</paragraph>
+ <paragraph role="pycode" localize="false" id="N0570"> if module_name and not module_name in sys.modules.keys():</paragraph>
+ <paragraph role="pycode" localize="false" id="N0571"> return zipimport.zipimporter(url).load_module(module_name)</paragraph>
+ <paragraph role="pycode" localize="false" id="N0572">def unloadLibrary(lib_name: str):</paragraph>
+ <paragraph role="pycode" xml-lang="en-US" id="N0573"> """ remove directory from PYTHON_PATH """</paragraph>
+ <paragraph role="pycode" localize="false" id="N0574"> sys.path.remove(lib_name)</paragraph>
+ <paragraph role="pycode" localize="false" id="N0575"> </paragraph>
+ <paragraph role="pycode" localize="false" id="N0576">g_exportedScripts = (OnDocPostOpenLoadPython, OnDocQueryCloseUnloadPython)</paragraph>
+ </pycode>
+ <section id="relatedtopics" >
+ <embed href="text/sbasic/python/python_session.xhp#pythonsession"/>
+ <embed href="text/sbasic/python/python_programming.xhp#pythonprogrammingheading"/>
+ <embed href="text/sbasic/python/python_locations.xhp#pythonlocations1"/>
+ <paragraph role="paragraph" id="N0580">
+ Refer to <link href="text/sbasic/python/python_listener.xhp">Creating a Python Listener</link> for examples of event-driven macros.
+ </paragraph>
+ </section>
+</body>
+</helpdocument>
More information about the Libreoffice-commits
mailing list