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 <openoffici...@sfr.fr>
AuthorDate: Wed Feb 13 11:31:15 2019 -0200
Commit: Olivier Hallot <olivier.hal...@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.hal...@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>
_______________________________________________
Libreoffice-commits mailing list
libreoffice-comm...@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/libreoffice-commits
