Pythonアプリケーションの設計と開発 [LibreOffice Wikiの和訳]

online courses or guides

• Pythonを学ぶ
• Pythonを学ぶ－無料の対話的なPythonチュートリアル
• 実際のPythonチュートリアル
• WikibooksのPythonプログラミング

e-Bibliography

• The Hitchhiker's Guide to Python!, Kenneth Reitz, April 2018
• Object-Oriented Programming in Python, Nov. 2017 (PDF版)
• Learning Programming with Python 3 － The Coder's Apprentice, Oct. 2017 (PDF版)
• OpenOffice.org 3.1 Developer's Guide, オンライン版, 例, 2009
• StarOffice (Basic) Programmer's Tutorial, May 2000
• Java LibreOffice Programming, Andrew Davison, March 2017

IDLE、Geany、PyCharm内でのソース探索と構文の強調表示により、スクリプトの編集が容易になります。GeanyとPyCharmは、コードの折り畳みをサポートしています。IDLEクラス・ブラウザは、内部、あるいは、埋め込みクラスをサポートしていません。

IDLE - 構文の強調表示とクラス・ブラウザ。

Geany - クラス・エクスプローラ、構文の強調表示とコードの折り畳み。

PyCharm - コードの色分け、コード・エクスプローラとクラス分析。

Code completion

コード補完は、IDLE、Geany、PyCharmでのPythonスクリプトの編集を支援します。

IDLE - モジュール補完

IDLE - 関数補完

Geany - クラス・メソッド補完

PyCharm - コード補完

Debugging

以下のデバッグの章では、このテーマについて詳しく説明します。

Geanyは、SDKで定義された..awt.createMessageBox()APIメソッドを呼び出すinfo()関数を実行します-スクリプト名は、<user>\SysInfo.pyです。

Pyzoは、実行され、\..\IDE_utils.pyで、停止します。

UNOオブジェクトのUNO、Pythonクラス、変数の監視

APSOを使用したブレークポイント、スタックトレース、オブジェクトの検査

Coding guidelines (PEP)

PyCharm IDEは、Python拡張の提案（PEP）コンプライアンス・チェックを表示します。

Pythonのコーディング規則と推奨事項は、エディターの右端にあります。これは、経験の浅いプログラマーにとって特に便利です。

Test-Driven Development (TDD) - draft

</Unit testing>

Version Control

下で図示するように、ソースコードのローカル履歴には、PyCharmが付属しています。：

apso.py Pythonモジュールの2つのコピーが一緒に表示され、それぞれv0.8.3とv0.8.7のラベルが付いています。バージョンの違いは、正確に強調表示されます。

PyCharmは、Git、GitHub、Mercurial、Perforce、Subversionなどの他のバージョン管理ソリューション（VCS）をサポートしています。

Within LibreOffice

Alternative Python Script Organizer拡張機能を使用して、LibreOffice内で、Pythonマクロを直接編集およびデバッグできます。LibreOfficeを離れることなく、ライブラリとモジュールを管理したり、好みのエディタを選択したりすることができます。

LibreOfficeからの開発も同様に実行可能であるため、デバッグが可能になります。統合開発環境（IDE）を使用したリモートコーディングとテストにより、この後詳述されるより多くの特徴を持っています。

ここに、これらの2つのコンテキストで、恩恵を受けるために、プログラマーのための3つの拡張機能があります。LibreOffice Basic、Python、JavaScript、BeanShellなど、プログラミング言語に関係なく使用できます。3つすべてが、LibreOfficeスイートからAPIのイントロスペクションを拡張します。

Useful Extensions

設計時に、UNOオブジェクトが、実際にサポートするサービスが、常に明確であるとは限りません。しかしながら、開発者が、どんなUNOオブジェクトでも、検査するのに役立つ拡張機能が存在しますが、MRIを除いて、拡張機能のカタログからは利用できません。それらは、LibreOfficeのAPIリフレクション機能に基づいて構築されています。

• X-Rayは、LibreOfficeのAPIオブジェクトを検査します。オブジェクト変数によって提供されるプロパティ、メソッド、サービス、インターフェイスが表示されます。X-Rayは、フランス語、英語、ドイツ語、スペイン語、チェコ語、ポーランド語、ロシア語で利用できます。X-Rayは、Basicで記述されています。
• MRI（My Reflection and Introspection）は、Pythonで記述されたUNOオブジェクトのイントロスペクションツールです。その機能は、X-Rayの機能と似ています。MRIは、英語だけで利用できます。注：拡張機能のカタログMRIコピーは古くなっています。
• Object Inspectorオブジェクト・インスペクタ拡張機能は、すべてのサポートされたサービス、エクスポートされたインターフェイス、およびTreeViewウィンドウ内のそれぞれのメソッドとプロパティのような、UNOオブジェクトの全機能を表示します。オブジェクト・インスペクタは、Javaで記述され、英語だけで利用できます。
• APSOAlternate Python Script Organizer 拡張機能は、オブジェクト・インスペクタをデバッガーにうまく統合します。X-RayまたはMRIのいずれかを使用します。

Xray - Writerテキスト・オブジェクトのメソッド

MRI - Writer文書のためのプロパティ、メソッド、サービス、インターフェイス

Object Inspector - 「StarDesktop」のプロパティ、メソッド、サポートされているサービス、およびエクスポートされたインターフェイス

Usage of Python macros

LibreOfficeのPythonマクロは、さまざまな場所に保存されており、「マクロ言語としてのPython」で説明されているように、さまざまな種類があります。スクリプトは、personal、shared、拡張機能への保存、パッケージへの統合、文書への埋め込みが可能です。この多様性は、さまざまな用途や制約を暗示します。

文書では、それぞれのモジュールは自律的であり、モジュールのインポートはありません。これを回避するために、オンライン/ローカル・ヘルプの「Pythonのインポート」を参照してください。

埋め込まれたPythonモジュールから、BasicやPython拡張機能を呼び出すことができます。

<user>\python\pythonpath内のPythonスクリプトは、埋め込みモジュール、または<user>\pythonスクリプトによってインポートできます。IDEからのBasicのサポートなし：X-Rayが存在しない

Basicの存在は、IDEで設置されたブリッジの種類に依存しています。

PythonとJavaは、IDEから呼び出されたときにサポートされます。：MRI、オブジェクト・インスペクタを使用することができます。

ここに、Pythonマクロで、Mriを、どのように使用するかがあります。：

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()

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("\nBasic library Xray is not installed", uno.getComponentContext())

# ___________  example of use  _______________ 

def demoXray(): 
  """ example : using xray in a Writer document """ 
  
  xTextDoc = XSCRIPTCONTEXT.getDocument() 
  xText = xTextDoc.Text 
  xray(xText)
  xray("Demo is finished") 

g_exportedScripts = demoXray,

オブジェクト・インスペクタを使用して、UNOオブジェクトをツリービューに表示する：

import uno
def inspectObject( obj, title="Object Inspector" ):
	ctx = uno.getComponentContext()
	oi = ctx.ServiceManager.createInstanceWithContext("org.openoffice.InstanceInspector", ctx)
	if oi is None:  # i.e. InstanceInspector is not installed or deactivated
			# すなわち、インスタンス・インスペクタが、インストール、あるいは、非アクティブ化されていません
		return  # exit silently
			# 静かに終了します
	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

IDE内でPythonマクロを開発するには、LibreOfficeインタプリタを使用する必要があります。ネイティブPythonには、UNOオブジェクトと互換性のないIDLEのインタプリタが付属しています。Python IDEを選択していると、プログラマーは、クラス・ブラウザ、構文の強調表示、コードの補間、コーディング標準の適用、テスト駆動開発、デバッグ、バージョン管理などの多くの機能を利用できます。

Geany、PyCharm、Pyzo用のLibreOffice Pythonインタプリタの設定は、「マクロ/Pythonの基礎」で説明されています。

Geany - Project Properties - Base Path

Geany - Project Properties - Build - Execute Commands

Pyzo - Shell - Shell configurations...

PyCharm - Default Settings - Project Interpreter

<user>\python、あるいは、<user>\python\pythonpathからスクリプトを実行するには、IDEとLibreOfficeの間で、通信を確立する必要があります。このようなブリッジがないと、UNOオブジェクトに到達できません。一旦、通信が行われると、IDEとLibreOfficeは、連携して動作します。次のリンクは、そのプロセスを文書化しています。：

• XSCRIPTCONTEXTによるIDEの架け橋、2017年2月（フランス語）
• OpenOffice / LibreOfficeでのインターフェース指向プログラミング：Pythonマクロによるオフィスタスクを自動化、2015年12月
• PyCharmによるLibreOfficeのマクロ作成（環境設定）2013年9月（日本語）
• Pythonを使用したOpenOfficeの開始、停止、および接続、2008年12月
• Python UNOブリッジ、2008年10月

IDE_utilsモジュールは、これらのリソースを借りて、LibreOfficeのIDE用のPythonマクロの単純な有効化を提供します。

Usage of Python scripts

• … Pythonパッケージと呼ばれています …

External Execution with Geany

Geanyは、LibreOffice内で、ウィンドウを開き始めます。GeanyのEDIは、SDKで定義された..awt.createMessageBoxAPIメソッドを利用するinfo()関数を呼び出します。ユーザー・スクリプトには、SysInfo.pyという名前が付いています。

Debugging with PyZo

PyUNOのWorkspaceは、PyUNOとLibreOffice UNO APIのためのオブジェクトのイントロスペクションPyzo IDEプラグインです：

Pyzoは、実行され、\..\IDE_utils.pyで、停止します。

Debugging with APSO

Alternative Python Script Organizer拡張機能は、xRayやMRIによるスタックトレース表示とUNOオブジェクトのイントロスペクションと同じように、段階的に実行できます。

Output to Consoles

Pythonスクリプトは、PythonシェルとそのRead Execute Print Loop（REPL）プロセスを使用して、プロトタイプ化できます。Alternative Python Script Organizerは、LibreOffice Pythonの一部であるこの機能を統合します。

Pythonインタラクティブ・コンソール

Windowsのコンソール

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

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

Handling Exceptions - draft

• 例外処理

Handling Exceptions - draft

• 例外処理

Designing Dialogs

• 詳細：..中間結果を表示する

Event-Driven Macros

• UNODiT UNOダイアログ・ツール
• コンポーネントでダイアログを使用する。
• イベント・ヘルプページ
  • Basic イベント駆動型マクロ、イベント、CreateUnoListener
  • Writer オブジェクト・イベント
  • グローバルControl、あるいは、Formイベント
• イベントAPIページ
  • com.sun.star.documentイベント・サービス、DocumentEvent、XDocumentEventBroadcaster
• 詳細：自動スクリプトで、ToCを更新する、[Calc]イベント-リスナーとハンドラ、マクロの自動実行 .. マクロコードで、.. OnSaveイベントを監視するPythonスクリプト、2-ボタン・ダイアログのためにPythonで例を探す、Python...ListBoxのMouseClick、Pythonのダイアログ・ボックス、[Python] [UI]ウィンドウ/ウィジェットの更新、セルの内容が変更されたときにPythonマクロを実行する、HowTo ..CalcのためのPythonマクロ
  • Basic Access2BaseのApplication.Events()関数、登録されたイベントの変更を文書に永続化する、..CalcのためのPythonマクロ
  • .Net VB.Net/C#から、LibreOfficeのWriter文書のためにOnLoadイベントを発生させる方法

Localisation

Building a Service

Building a Calc Add-In

• Calcのアドインの構築、Hubert Lambert、2016年11月（フランス語）
• 地理座標または地図作成座標の変換、pk1157＆alter、2011年1月

Building and Extension

Document module import

参考：オンラインヘルプでのPythonモジュールのインポート

Python package vs. LibreOffice Extension

（参考：これまでのフランス語の草案バージョン）

Static Properties or Methods

Q: Pythonのグローバル属性の動作は、どのようなものですか？