appex - Pythonista用「アプリ・エクステンション」ユーティリティー

appex — Pythonista用「アプリ・エクステンション」ユーティリティー

 appexモジュールは、iOS上の他のアプリ中でPythonスクリプトを使用できるよう、Pythonistaから「アプリ・エクステンション」で共有する機能を提供します。

Pythonista 3は、このモジュールで、シェア・エクステンションと、ウィジットの2種類の「アプリ・エクステンション」の方法を提供します。

シェア・エクステンション

（ Pythonista Shortcuts / Share Extension もご覧下さい）

 

　Pythonistaのシェア・エクステンションは、一般的なiOSシェアシートを介して、他のアプリからのデータの処理をすることが可能です。

　最初に使う際には、シェア拡張をサポートしているアプリ(例えばSafari)からシェアシートを呼び出す必要があります。シェアシートの「More...」(iOS12以前)又は「Edit Actions...」(iOS13以降)をタップし、「Run Pythonista Script」を起動して下さい。この手続きは一回だけ行えば、その後は、「Run Pythonista Script」が自動的に表示されるようになります。

　アクティベートした後は、シェアシートを使えるどのアプリからも「Mini Pythonista」を呼び出すことが可能になります。シェア・エクステンションは、対話形式のコンソールと基本的なスクリプトエディタを含んでいるほか、お好みのスクリプトを素早く実行するためのショートカット・アイコンを追加することができます。

　アプリがシェアシートを使っている時は、通常、何らかのデータを「Mini Pythonista」に渡しています。例えば、Safariの開いていたページのURLとか、Notesのテキストデータとか、Photosの映像データなどです。このモジュールの関数を使って、それらのデータにアクセスしたり処理したりすることができます。関数の例としてはappex.get_url(), appex.get_text()などがあります。

　シェア・エクステンションでスクリプトを実行する際には、以下にご注意下さい。:

  • ui.Viewを表示している場合(ui.View.present()を使って表示している場合)には、表示形式は無視されます。iPhoneでは、表示は常に「full-screen」モードですが、iPadの場合は、アプリ・エクステンションの主画面を覆い隠してしまうため、「full-screen」モードは使えません。
  • いくつかの関数、最も重要なものではwebbrowser.open()はシェア・エクステンションのスクリプトでは実行できません。notificationモジュールも実行不可です。
  • カメラはアプリ・エクステンションを使えないので、photos.capture_image() は動作しません。

トゥディ・ウィジット

　トゥディ・ウィジットは、プルダウンした通知センター(の中のTodayタブ)や、ホーム画面の最初のページから、又はロック画面を右側にスワイプすることで、iOSのどこからも素早くアクセスして単独のスクリプトを実行することができます。

　トゥディ・ウィジットをアクティベートするには、「Today画面」の編集ボタンをタップして、Pythonistaウィジットを選ぶ必要があります。また、Pythonistaの設定でウィジットで実行するスクリプトを選ぶ必要があります。手始めに、Examples/Widgetフォルダにあるスクリプトから一つを試して見ると良いでしょう。

（注　トゥディ・ウィジットはiOS10以降のみの機能で、Python 3でのみサポートしています）

 

　選んだスクリプトは、ウィジットが表示されている時にはいつでも実行可能です。一般的に、ウィジットでは、（uiモジュールで生成された）シンプルなユーザーインターフェイスを表示するためにset_widget_view()関数が使われます。

　シェア・エクステンションと比べて、トゥディ・ウィジットでできる事は限定的です。Pythonistaの APIのサブセットだけが実行可能で、メインアプリやシェア・エクステンションに比べてはるかに少ないメモリー領域しか使えません。

 

トゥデイ・ウィジットでスクリプトを実行する際には、特に以下に留意する必要があります：

（警告　ウィジットの記憶領域はとても限られています。もし、メインアプリで動作するスクリプトであっても、ウィジットでは「読み込めません」というメッセージを眼にすること（又はウィジットが空になっていること）があります。その場合、スクリプトが大量の記憶領域を消費して、システムから強制終了されているのです。この現象が発生した場合には、デバイスの再起動を試してみて下さい。）

  • dialogs, console.alert()などにある全てのダイアローグは使用できません。
  • ui.View.present()メソッドは使用できません。ウィジットでユーザーインターフェイスを表示するには、set_widget_view()関数を使う必要があります。
  • ウィジットの動作が止まってしまった場合、2本の指で3秒間タップしてそのままホールドすると実行を終了させることができます。

関数

appex.is_running_extension()

　アプリ・エクステンション（シェア・エクステンション又はウィジット）中でスクリプトが動作している場合、Trueを返します。その他の場合はFalseを返します。

　メインアプリ上でスクリプトを試してみたい場合、例えば、この関数を使いシェア・シートの入力の代わりにダミーデータを読み込ませることができます。

appex.is_widget()

　スクリプトがトゥデイ・ウィジットで動作している場合、Trueを返します。その他の場合はFalseを返します。

appex.finish(js=None)

　シェア・シート・エクステンションを終了させます。省略可能なパラメーターであるjsは、Safariでのエクステンションの時だけ意味を持ちます。Pythonistaシートが閉じられた後、見ていたウェブページのコンテンツの中で実行されるジャバスクリプトコードを指定します。この関数はメインアプリで呼び出される場合には意味を持ちません。

appex.get_attachments(uti='public.data')

　与えられたタイプの識別子に該当する添付のリストを返します。多くの場合、get_image(), get_url()のようなタイプが固定された関数を使用するよりもずっと簡単に使えます。

appex.get_images(image_type='pil')

　シェア・シートに入力された画像のリストを返します。image_typeには、‘ui’又は‘pil’が選べます。‘ui’の場合、ui.Imageインスタンスが、それ以外の場合、PIL（Pythonイメージライブラリー）の画像が返されます。入力に画像がない場合、空のリストが返されます。

appex.get_image(image_type='pil)

　シェア・シートに入力された最初の画像を返します。image_typeには、‘ui’又は‘pil’が選べます。‘ui’の場合、ui.Imageインスタンスが、それ以外の場合、PIL（Pythonイメージライブラリー）の画像が返されます。入力に画像がない場合、空のリストが返されます。

appex.get_image_data()

　シェア・シートに入力された最初の画像の生画像データを返します。このデータはバイト列として返されます。入力に画像がない場合、None値を返します。

appex.get_images_data()

　シェア・シートに入力された全ての画像の生画像データを返します。このデータはバイト列として返されます。入力に画像がない場合、空のリストを返します。

appex.get_text()

　シェア・シートの文字列入力をユニコード列として返します。入力に文字列がない場合、None値を返します。

appex.get_urls()

　シェア・シートに入力されたURLのリストを返します。URLの入力がない場合には、空のリストを返します。

appex.get_url()

　シェア・シートに入力されたURLを返します。URLの入力がない場合には、None値を返します。

appex.get_file_paths()

　シェア・シートに入力されたファイルパスのリストを返します。ファイルパスがない場合には、空のリストを返します。

appex.get_file_path()

　シェア・シートに入力されたファイルパスを返します。ファイルパスがない場合には、None値を返します。

appex.get_vcards()

　シェア・シートに入力されたVCardレコードのリストを返します。各レコードは文字列として記述されます。入力にVcardがない場合には、空のリストを返します。

appex.get_vcard()

　シェア・シートに入力された最初のVCardレコードを返します。レコードは文字列として記述されます。入力にVcardがない場合には、None値を返します。

appex.get_web_page_info()

　Safariでシェア・シートを呼び出した場合、現在読み込んでいるページの情報を返します。返す値は辞書型で、普通は以下の内容を含んでいます。（全て、ユニコード文字列です）：

  • 'url': ページのフルURL(document.URL) – もし、この値だけが必要な場合、代わりに get_url() （他のアプリでも動作可能）を使うことができます。
  • 'title': ページのタイトル(document.title)
  • 'html': ページのHTMLソースコード – このソースコードはdocument.documentElement.outerHTMLから生成されており、必ずしもサーバーから読み込まれたものと正確に同一とは限らないことに注意して下さい。(例えば、ジャバスクリプト経由のDOM（ドキュメントオブジェクトモデル）マニピュレーションなど)
  • 'selection_html': 選択したテキスト (HTMLフォーマットや、保存用書式、リンクなど)
  • 'selection_text': 選択したテキスト(プレーンテキストとして)
  • 'cookie': document.cookieの値
  • 'referrer': document.referrerの値

　欠けている値は空の文字列で表現されます。

　シェア・シートがSafari以外のアプリから表示された場合、又は現在のページの情報が呼び出せない場合には、空の辞書型を返します。

appex.get_widget_view()

　トゥディ・ウィジットに現在表示されているビュー形式を返します。（set_widget_view()によりセットされたビュー形式がない場合にはNoneを返します。）

appex.set_widget_view(view)

　ウィジットのビュー形式をui.Viewオブジェクトとして設定します。ビュー形式は自動的にウィジット全体を覆うようにサイズ調整され、ビューの現在の高さは、“Show More”ボタンをタップした時の、ウィジットの拡張された高さとして使用されます。ビューの高さが120以下の場合、ウィジットには“Shore More”ボタンは表示されず、コンパクトなウィジットディスプレイモードが使用されます。

　ビューオブジェクトの代わりにNoneを渡せば、ウィジットから現在のビューを消すことができます。このスクリプトをメインアプリ中で実行した場合には、ウィジットビューがシミュレーションして表示されます。