Макросы/Руководство по проектированию Python

This page is a translated version of the page Macros/Python Design Guide and the translation is 22% complete.

Outdated translations are marked like this.

TDF LibreOffice Document Liberation Project Блоги сообщества Weblate Nextcloud Redmine Ask LibreOffice Пожертвования

Other languages:

Введение

Эта страница предназначена для разработчиков макросов на Python, желающих разрабатывать их для LibreOffice. Начинающие разработчики макросов на Python могут воспользоваться рекомендациями на этой странице. Обзор Python в LibreOffice доступен на странице Python Programmer's Guide.

Желающие помочь проекту LibreOffice могут обратиться к этой странице Wiki.

Эта страница предполагает, что вы знакомы с программированием на Python, а также, что вы знакомы с LibreOffice. Она содержит некоторые примеры кода на Python, а также описывает некоторые полезные расширения LibreOffice.

Документация

Документация на сайте Python.org конечно же
Learn Python the hard way не так сложно, как выглядит
Документация по Python на русском языке
Python - Apache OpenOffice
Real Python Tutorials, Python programming на Wikibooks

online courses or guides

Learning Python,
Learn Python - Free interactive Python tutorial
Real Python Tutorials,
Python programming at Wikibooks

Электронная библиография

OpenOffice.org 3.1 Developer's Guide, online version, and examples, 2009
StarOffice (Basic) Programmer's Tutorial, May 2000
Java LibreOffice Programming, Andrew Davison, March 2017

Унифицированный язык моделирования (UML)

Доступны некоторые утилиты для управления UML. Это произвольный список, в котором основное внимание уделяется бесплатному взаимодействию с приложениями с открытым исходным кодом:

ArgoUML : ArgoUML работает на любых Java платформах и доступна на десяти языках (Американский английский, Британский английский, Французский, Немецкий, Итальянский, Португальский, Испанский, Русский, Норвежский Bokmål и Китайский).
StarUML : StarUML доступна для macOS 10.6+, Windows XP+ и Ubuntu (64 или 32-bit). StarUML обладает богатым списком возможностей и доступна только на английском языке.
Umbrello : Umbrello распространяется с дистрибутивами GNU/Linux, доступна для Windows (64 или 32-bit) и macOS.

Более обширный список утилит (Unified Modeling Language (UML) доступен в Wikipedia.

StarOffice Programmer's Tutorial подробный документ LibreOffice со справкой по диаграммам UML.

Software Design Patterns описан в Wikipedia, иногда сопровождается примерами Python.

Преамбула

Управление скриптами Python с библиотеками

Разработка макросов в LibreOffice осуществляется в интегрированной среде разработки (IDE), которая позволяет редактировать, отлаживать и отлаживать макросы на Basic. Для написания макросов на Python требуются дополнительные шаги для настройки вашей IDE. При этом вам предоставляется гибкий дизайн, основанный на ваших предпочтениях или привычках при разработке на Python. Ниже приведены рекомендации по установке IDE, сложности которых варьируются от начинающего до продвинутого пользователя.

Управление библиотеками и макросами, эквивалентных управлению библиотеками Basic, недоступно для Python. Тем не менее, управление традиционными модулями и функциями Python вполне возможно, а создание пакетов Python, по крайней мере частично, соответствует созданию расширений LibreOffice или пакетов UNO. Эта страница использует взаимозаменяемые модули для библиотек и функций для макросов. Предпочитается терминология Python, чтобы соблюдать культуру использования Python.

Макросы LibreOffice могут быть персональные, общие или встроенные в документы. В зависимости от их типа и в зависимости от платформы, они могут располагаться в различных местах, как это описано здесь.

Для управления макросами Python можно использовать либо библиотеки Windows, либо использовать файловый менеджер в GNU/Linux. Таким образом .py файлы могут быть организованы, используя перетаскивание. Описание расположения папок в соответствии с вашим окружением, которое поможет вам настроить библиотеки или файловый менеджер, можно найти в статье AOO wiki Python как язык макросов.

Проекты на Python могут быть организованы для каждой среды IDE в библиотеке Windows, как показано на рисунке.

Меню Alternative Python Script Organizer

Обязательное расширение Alternative Python Script Organizer позволяет управлять макросами на Python. Установив его, вы получаете большую интеграцию макросов на Python в LibreOffice. После перезапуска LibreOffice проверьте меню Сервис ▸ Макросы ▸ Организация макросов Python.

Это расширение предоставляет различные действия по управлению макросами на Python. Кнопка Выполнить запускает выделенный макрос. Действия, доступные в кнопке Меню зависят от выделенного элемента:

Диалог Alternative Python Script Organizer

Создавайте макросы или библиотеки в виде персональных, общих или в варианте только для текущего документа
Редактируйте, переименовывайте, удаляйте макросы или библиотеки
Встраивайте макросы в документ из персонального или общего вариантов
Заменяйте встроенную в документ библиотеку модулем Python для платформы.
Экспортируйте встроенную в документ библиотеку в виде модуля Python
Отлаживайте выбранный макрос
Запускайте интерактивную консоль Python, также известную как интерпретатор Python

Дополнительная информация, связанная с организацией макросов и пакетами Python может быть найдена в разделе Debugging

Макрос LibreOffice уточняет, как использовать макросы в приложении LibreOffice.

Разработка

Многочисленные приложения используют Python. В LibreOffice встроен свой собственный интерпретатор Python, который позволяет использовать API через Universal Network Objects (UNO). Язык Python содержит собственный интерпретатор, который можно использовать параллельно с используемым в LibreOffice. Оба имеют общую базу и являются расширяемыми, поэтому они предоставляют одинаковые функции. Оригинальный Python не включает интерфейс UNO для API LibreOffice. И наоборот, Python из поставки LibreOffice не полностью ведет себя как оригинальный Python и не расширяет его функциональные возможности. Однако ни LibreOffice, ни сам по себе Python не облегчают разработку приложений на языке Python для Writer, Calc, Impress, Draw, Base или Math.

LibreOffice существует в 32- или 64-битных версиях. Интегрированная среда разработки (IDE), которая встроена в него, требует выполнения в одном и том же контексте, как в 32-, так и в 64-битном режиме. Многочисленные IDE существуют в вариантах от самых простых, таких как IDLE, до более сложных, например PyCharm или PyDev для Eclipse. Следующий список произвольно фокусируется на инструментах, которые являются бесплатными, с открытым исходным кодом, мультиплатформенными и, возможно, многоязычными. Ниже в Debugging chapter используется Pyzo и PyCharm исключительно для иллюстрации. Список IDE для Python доступен на сайте Python.org. Сравнение интегрированных сред разработки (IDE) для многих языков доступно в Википедии.

Integrated Development and Learning Environment (IDLE) поддерживает 32- и 64-бита. Доступна для многих платформ. IDLE - рекомендуемый инструмент для изучения Python.
Geany работает в 32- или 64-битах и доступна на 43 разных языках. Запускается на GNU/Linux, *BSD, macOS, AIX v5.3, Solaris Express и Windows. Geany легкая, подходит для небольших проектов и поддерживает интерпретатор Python из состава LibreOffice.
Liclipse
Отладка в Aptana выглядит возможной судя по этому треду
PyCharm (free edition) поддерживает Gnu/Linux, macOS и Windows. Доступна как 32^бит, и видимо вмещает 64^бит тоже. Наряду с многочисленными функциями, сопровождающими разработку Python, PyCharm содержит отладчик Python, совместимый с LibreOffice.
Pyzo доступен для Linux, OS X и Windows на 10 разных языках. Несколько интерпретаторов Python могут быть настроены, есть в 32^бита или 64^бита. Pyzo предлагает возможности отладки.

Ниже расположен список возможностей доступных из указанных выше IDE, при этом LibreOffice Basic IDE не обладает некоторыми из них.

Просмотр исходного кода и подсветка синтаксиса

Source exploration and syntax highlighting within IDLE, Geany and PyCharm are facilitating script edition. Geany and PyCharm support code folding. IDLE class browser does not support inner or embedded classes.

IDLE - Syntax highlighting and class browser.
Geany - Class explorer, syntax highlighting and code folding.
PyCharm - Color coding, code explorer and class analysis.

Code completion

Code completion assists the edition of Python scripts in IDLE, Geany and PyCharm.

IDLE - Module completion
IDLE - Function completion
Geany - Class method Completion
PyCharm - Code completion

Debugging

Debugging chapter below goes into this subject in more details.

$Geany executes info() function that calls ..awt.createMessageBox() API method defined in SDK - Script name is <user>\SysInfo.py$

Geany executes info() function that calls ..awt.createMessageBox() API method defined in SDK - Script name is <user>\SysInfo.py
$Pyzo runs and stops into <user>\..\IDE_utils.py$

Pyzo runs and stops into <user>\..\IDE_utils.py
Watching UNO objects UNO, Python classes or variables
Breakpoints, stack trace and objects inspection with APSO

Coding guidelines (PEP)

PyCharm IDE displays Python Enhancement Proposal (PEP) compliance checks.

Python coding conventions and recommendations are available on the rightmost portion of the editor. This is particularly convenient for unexperienced programmers.

Test-Driven Development (TDD) - draft

</Unit testing>

Version Control

A source code local history comes with PyCharm as illustrated below:

Two copies of apso.py Python module are jointly displayed and respectively labelled v0.8.3 and v0.8.7. Version differences are precisely highlighted.

PyCharm supports other version control solutions (VCS) such as Git, GitHub, Mercurial, Perforce or Subversion.

Debugging

Within LibreOffice

Xray - Methods of a Writer text object

MRI - Properties, methods, services and interfaces for a Writer document

Object Inspector - 'StarDesktop' properties, methods, supported services and exported interfaces

One can edit and debug Python macros directly within LibreOffice with the help of Alternative Python Script Organizer extension. Managing libraries and modules is possible, as well as selecting your preferred editor without leaving LibreOffice.

Developing out of LibreOffice is equally feasible, thus debugging becomes possible. Remote coding and testing using an Integrated Development Environment (IDE) brings more features detailed hereafter.

Here are three extensions for programmers to benefit from in those two contexts. They can be used regardless of the programming language, be it LibreOffice Basic, Python, JavaScript or BeanShell. All three extend the API's introspection from LibreOffice suite.

Useful Extensions

It is not always clear at design time which services a UNO object actually supports. However extensions that help the developer to inspect arbitrary UNO-Objects exist, but are not made available from the extensions' catalog, with the exception of MRI. They're built upon LibreOffice API reflection ability.

X-Ray inspects LibreOffice API objects. It displays the properties, methods, services, interfaces which are provided by an object variable. X-Ray is available in french, english, german, spanish, czech, polish and russian. X-Ray is written in Basic.
MRI (My Reflection and Introspection) is an introspection tool of UNO objects, written in Python. Its features are similar to that of X-Ray. MRI is available in english only. Note: Extensions' catalog MRI copy is outdated.

Object Inspector The Object Inspector extension displays the total capabilities of an UNO-object such as all supported services, exported interfaces, and their respective methods and properties in a TreeView window. The Object Inspector is written in Java and is available only in english.

APSO The Alternate Python Script Organizer extension nicely integrates objects inspection in its debugger. It uses either X-Ray either MRI.

Usage of Python macros

Python macros in LibreOffice are stored in numerous locations and come in varied species as explained in Python as a macro language. Scripts can be personal, shared, stored in extensions, integrated in packages or embedded in documents. This diversity imply different uses or constraints.

In a document each module is autonomous, no module import.

Refer to Python import online/local help in order to circumvent this

Calling a Basic or Python extension from an embedded Python module is possible.
Python scripts in <user>\python\pythonpath can be imported by embedded modules or by <user>\python scripts.

No Basic support from an IDE: No X-Ray

Basic presence is depending on the bridge type established with the IDE.

Python and Java are supported when invoked from an IDE: MRI, Object Inspector can be used.

Here's how to use Mri in a Python macro:

import uno
def mri(target):
    ctx = uno.getComponentContext()
    mri = ctx.ServiceManager.createInstanceWithContext(
        "mytools.Mri",ctx)
    mri.inspect(target)
    
if __name__ == '__main__':
    def Mri_test():
        document = XSCRIPTCONTEXT.getDocument()
        mri(document)
 
    Mri_test()

Stopping a running macro with X-Ray :

import uno
from com.sun.star.uno import RuntimeException as _rtex

def xray(myObject):
  try:
    sm = uno.getComponentContext().ServiceManager
    mspf = sm.createInstanceWithContext("com.sun.star.script.provider.MasterScriptProviderFactory", uno.getComponentContext())
    scriptPro = mspf.createScriptProvider("")
    xScript = scriptPro.getScript("vnd.sun.star.script:XrayTool._Main.Xray?language=Basic&location=application")
    xScript.invoke((myObject,), (), ())
    return
  except:
     raise _rtex("\n<span lang="en" dir="ltr" class="mw-content-ltr">Basic library Xray is not installed</span>", uno.getComponentContext())

# ___________  <span lang="en" dir="ltr" class="mw-content-ltr">example of use</span>  _______________ 

def demoXray(): 
  """ <span lang="en" dir="ltr" class="mw-content-ltr">example : using xray in a Writer document</span> """ 
  
  xTextDoc = XSCRIPTCONTEXT.getDocument() 
  xText = xTextDoc.Text 
  xray(xText)
  xray("<span lang="en" dir="ltr" class="mw-content-ltr">Demo is finished</span>") 

g_exportedScripts = demoXray,

Displaying UNO objets in a tree view using Object Inspector :

import uno
def inspectObject( obj, title="<span lang="en" dir="ltr" class="mw-content-ltr">Object Inspector</span>" ):
	ctx = uno.getComponentContext()
	oi = ctx.ServiceManager.createInstanceWithContext("org.openoffice.InstanceInspector", ctx)
	if oi is None:  # <span lang="en" dir="ltr" class="mw-content-ltr">i.e. InstanceInspector is not installed or deactivated</span>
		return  # <span lang="en" dir="ltr" class="mw-content-ltr">exit silently</span>
	oi.inspect( obj, title )
def exObjInspector():
	doc = XSCRIPTCONTEXT.getDocument()
	dsk = XSCRIPTCONTEXT.getDesktop()
	inspectObject(doc)
	inspectObject(dsk, title="StarDesktop")

From an IDE via LibreOffice Python interpreter

Developing Python macros within an IDE requires the use of LibreOffice interpreter. Native Python comes with IDLE's interpreter that's not compatible with UNO objects. While selecting a Python IDE programmers benefit from numerous features such as class browser, syntax highlighting, code completion, coding standards enforcement, test driven development, debugging, version control and many more.

The setting of LibreOffice Python interpreter for Geany, PyCharm or Pyzo is illustrated in Python IDE Basics.

Geany - Project Properties - Base Path
Geany - Project Properties - Build - Execute Commands
Pyzo - Shell - Shell configurations...
PyCharm - Default Settings - Project Interpreter

In order to execute a script from <user>\python or from <user>\python\pythonpath, a communication must be established between the IDE and LibreOffice. UNO objects are not reachable without such a bridge. Once a communication is in place, the IDE and LibreOffice operate together. The following links document that process:

A bridge for IDE with XSCRIPTCONTEXT revisité, Feb. 2017 (in french)
Interface-oriented programming in OpenOffice / LibreOffice : automate your office tasks with Python Macros, Dec. 2015

Macro creation of LibreOffice with PyCharm (environment setting) Sep. 2013 (from japanese)
Starting, Stopping, and Connecting to OpenOffice with Python, Dec. 2008
Python UNO-bridge, Oct. 2008

IDE_utils module borrows from these resources and provides LibreOffice Python macro simple enablement for IDEs.

Usage of Python scripts

...calling Python packages...

External Execution with Geany

Geany initiates the opening of a window within LibreOffice. Geany EDI invokes info() function, which utilizes ..awt.createMessageBox API method defined in the SDK. The user script is named SysInfo.py.

$Geany executes info() function that calls ..awt.createMessageBox() API method defined in SDK - Script name is <user>\SysInfo.py$

Debugging with PyZo

PyUNO Workspace is an object introspection Pyzo IDE plugin for PyUNO and LibreOffice UNO API:

$Pyzo runs and stops into <user>\..\IDE_utils.py$
Pyzo runs and stops into <user>\..\IDE_utils.py

Debugging with PyCharm

PyCharm's debugger displays UNO objects, Python classes or objects:

Debugging with APSO

The Alternative Python Script Organizer extension allows step by step execution, as well as stack trace display and UNO objects introspection, with xRay or MRI.

Output to Consoles

Python scripts can be prototyped by use of the Python shell and its Read Execute Print Loop (REPL) process. The Alternative Python Script Organizer integrates this facility, which is part of LibreOffice Python.

APSO console

Python Interactive Console

The Python interactive console, also known as Python interpreter or Python shell, provides programmers with a quick way to execute commands and try out and test code without creating a file. UNO objects introspection as well as LibreOfficeDev Python modules documentation can be obtained from the terminal. LibreOffice online/local details how to run Python interactive console.

Python shell

Console on Windows

By default, there is no default stdout on Windows. What is sent by function “print” will not be visible anywhere. To get a console to be used as stdout:

Start LibreOffice using soffice.com instead of soffice.exe:

Python scripts print() statements appear in the console until LibreOffice closes. In the absence of the console, print() statements are silent.

source: Proper console mode for LibreOffice on Windows

This is available from LibreOffice release 6.3. Prior to this release, follow these instructions:

Close LibreOffice.
Download Visual Studio Express 2010 C++ (I assume it may work with other versions) and install it.
Open the Console for Visual Studio.
Type:

editbin.exe /subsystem:console "C:\Program Files\LibreOffice 5\program\soffice.exe"
editbin.exe /subsystem:console "C:\Program Files\LibreOffice 5\program\soffice.bin"

cf. EditBin reference at TechNet

Now, a console will be shown when you open LibreOffice. It will be the stdout for the “print” command. And you can get Python errors while LO is running if you use traceback.

import traceback
[…]
try:
    […]
    except:
        traceback.print_exc()

But syntax errors still won’t be reported there.

source: [Python] Errors report - Debugging configuration

Handling Exceptions - draft

Exception handling

Building Dialogs - draft

cf. UNODiT UNO Dialog Tools Find below a few listed references t get started:

Designing Dialogs

more : .. Viewing intermediate results

Event-Driven Macros

- Basic event-driven macros, events CreateUnoListener
- Writer object events
- global Control or Form events

Events API pages
- com.sun.star.document Events Service, DocumentEvent, XDocumentEventBroadcaster

more: Updating ToC with automated script, [Calc] Event-Listeners & Handlers, Auto execute .. macro by code, .. python script to monitor OnSave event, Looking for an example in Python for a 2-button dialog, Python...MouseClick in ListBox, Dialog box in Python, [Python][UI] Refresh window/widget, Run a python macro when cell contents change, HowTo .. Python macro for Calc

- Basic Access2Base Application.Events() function, Persisting a registered event change in a document, ..Python macro for Calc
- .Net How to raise a OnLoad event for writer document of LibreOffice from VB.Net/C#

Localisation

Dispatcher commands - draft

[Dispatch commands] are used in conjunction with the com.sun.star.frame.DispatchHelper service.

Interface-oriented programming in *Office, Christopher Bourez (2015)

Creating extensions - draft

Developing Python extensions with LOEclipse

To create an extension with Python, you can use Eclipse together with the LOEclipse plugin.

This will allow developing Python Extensions from Eclipse and includes automatic Extension packaging, as well as a debugger to debug Extensions directly from Eclipse.