Как запускать скрипты Python в макросах LibreOffice Calc

Да. LibreOffice Calc может запускать код Python в виде макроса внутри процесса LibreOffice, а макрос LibreOffice Basic также может вызывать функцию Python через скриптовую среду LibreOffice. Если ваша цель — прочитать или изменить ячейки в открытой электронной таблице, макрос Python внутри процесса обычно является самым простым вариантом. Используйте вызов Basic-to-Python, когда существующий макрос Basic должен передать одну задачу многократно используемой функции Python.

Эти подходы отличаются от запуска обычного системного скрипта Python с помощью команды оболочки. Обычный внешний процесс Python не получает автоматически объект документа Calc. Для доступа к рабочей книге запустите макрос Python через LibreOffice или намеренно подключите внешний процесс к экземпляру LibreOffice через UNO.

Что означает «запустить Python внутри макроса Calc»?

LibreOffice поддерживает несколько языков сценариев через свою скриптовую среду. В макросе Python LibreOffice предоставляет объект контекста UNO, который позволяет сценарию обратиться к текущему документу и его листам. Макрос Python — это функция в .pyмодуле; кортеж модуля g_exportedScriptsопределяет функции, которые LibreOffice должен отображать как исполняемые макросы.

Макрос Python может запускаться самостоятельно из меню макросов Calc. Его не обязательно вызывать из Basic. Если у вас уже есть макрос Basic и вы хотите, чтобы он вызывал Python, поставщик скриптов LibreOffice или более новая Session.ExecutePythonScriptслужба ScriptForge могут обеспечить связь между двумя языками.

Какой подход следует выбрать?

• Используйте макрос Python напрямую, если задача в основном выполняется на Python и требует текущего документа Calc. Это позволяет избежать переключения между языками программирования и упрощает отладку в виде одного скрипта.
• Вызывайте Python из Basic, когда у вас уже есть код Basic, кнопки или события документа, которые должны оставаться на месте, и вы хотите, чтобы вспомогательный класс Python выполнил целенаправленное вычисление или операцию с данными.
• Используйте внешний процесс Python, если вам нужна отдельная среда разработки или пакеты Python, не входящие в состав LibreOffice. Настройте явное подключение UNO; не предполагайте, что скрипт, запущенный из терминала, сможет увидеть открытую электронную таблицу.

Например, небольшой инструмент для очистки электронных таблиц можно полностью написать в виде макроса на Python. Если уже существует кнопка Basic, запускающая отчет, сохраните макрос кнопки и позвольте ей вызывать функцию Python, которая вычисляет итоговую сумму отчета.

Как создать макрос на Python, который редактирует ячейки в Calc?

LibreOffice хранит персональные скрипты Python в профиле пользователя, скрипты, действующие на уровне всего приложения, в каталоге установки, а скрипты документов — вместе с самим документом. Для первого теста удобно использовать персональный скрипт, поскольку он доступен из любого открытого документа LibreOffice для того же пользователя. Однако он не передается вместе с файлом ODS, поэтому другой пользователь не получит его автоматически вместе с электронной таблицей.

Найдите папку с личными скриптами Python для вашей системы в справке LibreOffice в разделе «Организация и расположение скриптов Python». Обычно она находится %APPDATA%\LibreOffice\4\user\Scripts\pythonв Windows и ~/.config/libreoffice/4/user/Scripts/pythonLinux. Фактический путь к папке может отличаться; используйте путь, указанный для вашей установки, вместо того, чтобы создавать второй каталог профиля наугад.

Создайте файл с указанным именем calc_tools.pyв папке с личными скриптами Python, а затем добавьте в него этот простой пример:

def double_a1(args=None):
    doc = XSCRIPTCONTEXT.getDocument()
    sheet = doc.getCurrentController().getActiveSheet()

    source = sheet.getCellRangeByName("A1")
    target = sheet.getCellRangeByName("B1")
    target.setValue(source.getValue() * 2)

g_exportedScripts = (double_a1,)

Эта функция считывает числовое значение из ячейки A1 активного листа и записывает это значение дважды в ячейку B1. XSCRIPTCONTEXTЗначение передается макросу Python в LibreOffice во время выполнения; оно не является обычной глобальной переменной Python, когда тот же файл запускается вне LibreOffice. Публичная функция указана в списке, g_exportedScriptsпоэтому она отображается в селекторе макросов.

Сохраните файл, затем откройте или вернитесь в Calc и выберите Инструменты > Макросы > Запустить макросы . В зависимости от версии LibreOffice или перевода платформы, название меню может быть в единственном числе. Выберите Мои макросы > calc_tools > double_a1 и запустите его. Сначала введите число в ячейку A1, затем убедитесь, что ячейка B1 содержит удвоенное значение. Если модуль не отображается, убедитесь, что расширение файла — .py, файл находится в правильной папке Python профиля и установлена ​​поддержка сценариев Python. Перезапуск LibreOffice после добавления нового модуля может помочь обновить список сценариев.

Как макрос на языке Basic может вызвать функцию Python?

Для вызова функции из Basic в Python поместите модуль Python в папку личных скриптов и вызовите его функцию через сервис ScriptForge Session. В этом примере выполняется сложение двух значений в Python и результат записывается в ячейку B1 на текущем листе Calc.

В файле calc_tools.pyопределите функцию:

def add_values(first, second):
    return float(first) + float(second)

g_exportedScripts = (add_values,)

Затем создайте базовый макрос в Calc и используйте:

Sub RunPythonHelper()
    Dim session As Object
    Dim result As Variant
    Dim sheet As Object

    session = CreateScriptService("Session")
    result = session.ExecutePythonScript( _
        session.SCRIPTISPERSONAL, _
        "calc_tools.py$add_values", _
        12, 30)

    sheet = ThisComponent.CurrentController.getActiveSheet()
    sheet.getCellRangeByName("B1").setValue(result)
End Sub

Запуск осуществляется RunPythonHelperиз селектора базовых макросов. Если вызов пройден успешно, в ячейке B1 должно отобразиться значение 42. Ссылка на скрипт имеет следующий вид: module.py$function_name; для модуля в подпапке или другом месте хранения используйте синтаксис и константу местоположения, описанные для данной версии ScriptForge. Сохраняйте аргументы и возвращаемые значения в виде типов данных, которые оба языка могут корректно представлять, например, числа, строки и простые последовательности.

CreateScriptServiceДокументированные вспомогательные функции сессий ScriptForge доступны в современных версиях LibreOffice, но названия меню и входящие в комплект компоненты могут отличаться в более старых или дистрибутивных сборках. Если эта служба недоступна, используйте документированный метод поставщика скриптов UNO в LibreOffice, который получает значение XScriptиз URI скрипта и вызывает его. Избегайте копирования фрагмента кода для другого местоположения макроса без изменения его настроек местоположения.

Код на Python должен быть личным, общим или встроенным?

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

Почему макрос может отсутствовать или не работать?

• Отсутствует опция или модуль Python. В некоторых дистрибутивах GNU/Linux скриптовая платформа Python для LibreOffice является необязательным пакетом. Если макросы Python не отображаются в диалоговом окне макросов, проверьте инструкции по установке LibreOffice в вашем дистрибутиве.
• Скрипт сохранен в неправильном профиле. LibreOffice может использовать несколько пользовательских профилей. Проверьте путь к профилю для установленной программы и сохраните модуль в его Scripts/pythonдиректории.
• Функция не экспортируется. Добавьте её g_exportedScriptsдля функции, которую вы собираетесь запускать из селектора макросов. Убедитесь, что синтаксис кортежа включает завершающую запятую для кортежа из одного элемента.
• Этот скрипт запускается вне LibreOffice. XSCRIPTCONTEXT Он существует для макроса, запущенного LibreOffice, а не для того, который запускается с помощью системной pythonкоманды. Используйте средство запуска макросов или настройте документированное соединение UNO.
• Защита макросов блокирует встроенный код. Проверьте настройки защиты макросов LibreOffice и разрешайте только код из источников, которым вы доверяете. Снижение глобального уровня безопасности — не лучший способ быстрого устранения неполадок.
• Импортированный модуль не может видеть контекст документа. Документы LibreOffice, которые XSCRIPTCONTEXTне передаются импортированным модулям, следует передавать в вспомогательные функции, вместо того чтобы ожидать, что импортированные модули будут считывать эту глобальную информацию.
• В консоли нет видимого вывода. Стандартный вывод Python недоступен при запуске макроса из меню «Инструменты > Макросы». Для получения обратной связи запишите результат в ячейку, используйте службу диалогов LibreOffice или запишите результат в файл по указанному пути.

Как безопасно проверить результат?

Проведите тестирование с копией электронной таблицы и известными входными данными. Убедитесь, что макрос Python отображается в программе запуска, запустите его один раз и сравните выходную ячейку с результатом, вычисленным вручную. Для вызова Basic-to-Python протестируйте один простой входной параметр и убедитесь, что возвращаемое значение записано на нужный лист. Избегайте использования скриптов, которые удаляют листы, перезаписывают большие диапазоны или выполняют команды операционной системы.

Когда тест пройдет успешно, определите, как скрипт будет установлен на других компьютерах, и задокументируйте все необходимые библиотеки Python или предположения относительно версии LibreOffice. Для макросов, выполняемых внутри процесса, используется встроенная среда Python в LibreOffice; пакеты, установленные для отдельного системного интерпретатора Python, могут быть ему недоступны. Если вам нужны пакеты из другого интерпретатора, используйте подход с внешним процессом/UNO и настройте это соединение соответствующим образом.

Официальные ссылки

• Справка LibreOffice: Создание скриптов Python с помощью ScriptForge
• Справка LibreOffice: Вызов скриптов Python из Basic
• Справка LibreOffice: Программирование с использованием скриптов Python
• Справка LibreOffice: организация и расположение скриптов Python.
• Справка LibreOffice: Чтение и запись значений в диапазоны
• LibreOffice SDK: интерфейс XScript