XLPack for Python ユーザーマニュアル

1. 概要

XLPack for Python (以下 XLPack PY と略記します) は Excel VBA から Python を呼び出すことができるようにするためのアドインです.

マイクロソフトの Python in Excel に似たような機能ですが異なる仕組みで動作します. 以下に比較表を示します.

要約すると「XLPack PY は VBA プログラムから Python を使用するためのアドインで, Python を PC にローカルにインストールする必要があるが, ネット接続がない状況でも使用できる」ということになります.

2. 例題

使用イメージをつかむために簡単な例題を見てみます.

次のように, ワークシートに A, B, C それぞれ 2 つのセルを用意して, A と B に値を入れておきます.

次の VBA プログラムを用意します.

Sub Test_PY()
    Call PY( _
        "from XLPackPy import *" + vbLf + _
        "a = xl('B3:B4')" + vbLf + _
        "b = xl('C3:C4')" + vbLf + _
        "c = []" + vbLf + _
        "for i in range(2):" + vbLf + _
        "  c.append(a[i] + b[i])" + vbLf + _
        "xl('D3:D4', c)")
End Sub

これを実行すると次のように C のセルに A + B の結果が入ります.

この例のように Python プログラムの各行を vbLf (vbCrLf または vbNewLine でもよい) で区切って 1 つの文字列に入力し, PY() を呼び出すことにより Python プログラムを実行することができます. _ は VBA における継続行を表します. 基本的には短いプログラムを実行するために使うとよいでしょう.

長いプログラムを実行したいときには, プログラムをファイルに入れておき PYF() を呼び出すとよいでしょう.

Python プログラムの中で使われている xl 関数は Excel のセルを読み書きするためのものです.

VBA では Call PY(“…”) のような命令を単に PY “…” と書くことができます. これを使って次のように書くこともできます.

Sub Test_PY()
    PY "from XLPackPy import *"
    PY "a = xl('B3:B4')"
    PY "b = xl('C3:C4')"
    PY "c = []"
    PY "for i in range(2):" + vbNewLine + _
       "  c.append(a[i] + b[i])"
    PY "xl('D3:D4', c)"
End Sub

こちらの方が見やすいかもしれません. なお, 1 ステップごとに Python を呼び出すので効率が悪そうですが気になるほどではありません. また, for 文は繰り返しの中身を含めて１ステップとみなすことに注意してください.

3. Python を起動するための VBA サブルーチン

Python を起動するための VBA サブルーチンが提供されます. これらを使用するためには XLPack PY アドインを有効にしておく必要があります.

3.1 PY() VBA サブルーチン

Python プログラムが入った文字列を与えるとそれを実行します.

Call PY("Python プログラム")

現バージョンでは Python プログラムにエラーがあった場合, 通常の Python のような詳細なエラーメッセージは表示されません. 代わりにメッセージボックスに “Python error occurred.” とだけ表示されます.

つまり, エラーがあった場合には PY() の呼び出し単位で単にエラーがあったことしかわかりません. そのため, 少なくてもどのステップでエラーがあったかがわかるように PY “…” を使った上の２番目の例の記法のほうがよいかもしれません.

3.2 PYF() VBA サブルーチン

Python プログラムが入ったファイルを指定して実行します.

Call PYF("ファイル名")

比較的大きな Python プログラムを実行したい場合に適しています.

PY() と同様に, Python プログラムにエラーがあった場合, メッセージボックスに “Python error occurred.” とだけ表示されます.

4. Excel とのデータのやり取りのための Python 関数

Excel とデータのやり取りをするための Python 関数が提供されます. これらを使用するためには XLPackPy モジュールをインポートする必要があります. 例えば, 次のように書きます.

from XLPackPy import *

これらの関数は PY() または PYF() で呼び出された Python の中でしか動作しません.

現バージョンでは, データやり取りのために使われるワークシートは現在開かれている (カレント) ワークシートのみです. 他のブックやワークシートの指定はできません.

以下, 各関数の使い方を説明しますが, ワークシートに次のようなデータが入っているものとします. 左上を B5 セルとします.

4.1 xl() Python 関数

4.1.1 Excel のセルの読み出し

Excel のセルを読み出し, リスト(2 次元配列相当)として返します. 引数には A1 形式の文字列でセルを指定します.

a = xl(セル指定文字列)

単一のセルは ‘B5’ のように指定します. 複数のセルは左上と右下をコンマで区切って ‘B5:D8’ のように指定します.

エラーがあった場合には None を返します.

通常はリスト(2 次元配列相当)を返しますが, 例外として, 単一のセルを指定した時には単一の値, 単一の行あるいは列を指定したときにはリスト(1 次元配列相当)を返します.

エラーがあった場合には None を返します.

上のワークシートのデータの例では次のようになります.

xl('B5:D8')
= [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0], [7.0, 8.0, 9.0], [10.0, 11.0, 12.0]]
xl('B5:B8')
= [1.0, 4.0, 7.0, 10.0]
xl('B5:D5')
= [1.0, 2.0, 3.0]
xl('B5:B5')
= 1.0
xl('B5')
= 1.0

4.1.2 Excel のセルへの書き込み

与えられた Python データを Excel のセルに書き込みます. 引数には, A1 形式の文字列でのセル指定, および, 書き込むデータを渡します.

ret = xl(セル指定文字列, データ)

Python データの要素は, 整数, 浮動小数, または, 文字列でなければなりません. それ以外の場合には無視されます.

読み込みの場合と同様に, 通常はリスト(2 次元配列相当)をデータとして与えますが, 例外として, 単一のセルを指定した時には単一の値, 単一の行あるいは列を指定したときにはリスト(1 次元配列相当)をデータとして与えます.

書き込み成功の場合には True, 失敗の場合には False を返します.

使用例は次のとおりです.

xl('B5', 1)
xl('B5:D5', [1, 2, 3])
xl('B5:B8', [1, 4, 7, 10])
xl('B5:D8', [[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11, 12]])
xl('B5', [[1]])   -> 書き込まれない
xl('B5:D5', [[1, 2, 3]])   -> 書き込まれない

4.2 xlc() Python 関数

xl() 関数では 2 次元配列として考えると行方向を先にデータを格納しましたが, VBA や Fortran などの言語では列方向を先に格納します. これに対応した列方向バージョンが xlc() 関数です. その他の仕様は同じです.

4.2.1 Excel のセルの読み出し

上のワークシートのデータの例では次のようになります.

xlc('B5:D8')
= [[1.0, 4.0, 7.0, 10.0], [2.0, 5.0, 8.0, 11.0], [3.0, 6.0, 9.0, 12.0]]
xlc('B5:B8')
= [1.0, 4.0, 7.0, 10.0]
xlc('B5:D5')
= [1.0, 2.0, 3.0]
xlc('B5:B5')
= 1.0
xlc('B5')
= 1.0

4.2.2 Excel のセルへの書き込み

使用例は次のとおりです.

xlc('B5', 1)
xlc('B5:D5', [1, 2, 3])
xlc('B5:B8', [1, 4, 7, 10])
xlc('B5:D8', [[1, 4, 7, 10], [2, 5, 8, 11], [3, 6, 9, 12]])

4.3 xl_get() Python 関数

Excel のセルを読み出し, リスト(2 次元配列相当)として返します. 引数は 0 から始まる行および列番号でセルを指定します.

xl_get(行1, 列1, 行2, 列2): 指定された矩形領域のセルをリスト(2 次元配列相当)として読み出します.

xl_get(行1, 列1, 列2): 指定された行の領域のセルをリスト(1 次元配列相当)として読み出します.

xl_get(行1, 列1): 指定された単一セルを読み出します.

引数を 4 つ (行1, 列1, 行2, 列2) 指定した場合には必ずリスト(2 次元配列相当)を返します.

上のワークシートのデータの例では次のようになります.

xl_get(4, 1, 7, 3)
= [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0], [7.0, 8.0, 9.0], [10.0, 11.0, 12.0]]
xl_get(4, 1, 7, 1)
= [[1.0], [4.0], [7.0], [10.0]]
xl_get(4, 1, 4, 3)
= [[1.0, 2.0, 3.0]]
xl_get(4, 1, 4, 1)
= [[1.0]]
xl_get(4, 1, 3)
= [1.0, 2.0, 3.0]
xl_get(4, 1)
= 1.0

4.4 xlc_get() Python 関数

Excel のセルを読み出し, リスト(2 次元配列相当)として返します. 引数は 0 から始まる行および列番号でセルを指定します. xl_get() 関数の列方向バージョンです.

xl_get(行1, 列1, 行2, 列2): 指定された矩形領域のセルをリスト(2 次元配列相当)として読み出します.

xl_get(行1, 列1, 行2): 指定された列の領域のセルをリスト(1 次元配列相当)として読み出します.

xl_get(行1, 列1): 指定された単一セルを読み出します.

引数を 4 つ (行1, 列1, 行2, 列2) 指定した場合には必ずリスト(2 次元配列相当)を返します.

上のワークシートのデータの例では次のようになります.

xlc_get(4, 1, 7, 3)
= [[1.0, 4.0, 7.0, 10.0], [2.0, 5.0, 8.0, 11.0], [3.0, 6.0, 9.0, 12.0]]
xlc_get(4, 1, 7, 1)
= [[1.0, 4.0, 7.0, 10.0]]
xlc_get(4, 1, 4, 3)
= [[1.0], [2.0], [3.0]]
xlc_get(4, 1, 4, 1)
= [[1.0]]
xlc_get(4, 1, 7)
= [1.0, 4.0, 7.0, 10.0]
xlc_get(4, 1)
= 1.0

4.5 xl_set() Python 関数

0 から始まる行および列番号で指定されたセルに Python データを書き込みます.

Python データは, 整数, 浮動小数, または, 文字列でなければなりません. それ以外の場合には無視されます.

xl_set(行1, 列1, 行2, 列2, リスト(2 次元配列相当)): 指定された矩形領域のセルにリスト(2 次元配列相当)データを書き込みます.

xl_get(行1, 列1, 列2, リスト(1 次元配列相当)): 指定された行の領域のセルにリスト(1 次元配列相当)データを書き込みます.

xl_get(行1, 列1, データ): 指定された単一セルに単一データを書き込みます.

指定された行1, 列1, 行2, 列2をはみ出すデータは無視されます. また, データが不足する場合には対応する部分には書き込みを行いません

使用例は次のとおりです.

xl_set(4, 1, 7, 3, [[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11, 12]])
xl_set(4, 1, 4, 3, [[1, 2, 3]])
xl_set(4, 1, 7, 1, [[1], [4], [7], [10]])
xl_set(4, 1, 4, 1, [[1]])
xl_set(4, 1, 3, [1, 2, 3])
xl_set(4, 1, 1)

4.6 xlc_set() Python 関数

0 から始まる行および列番号で指定されたセルに Python データ (整数, 浮動小数, 文字列に限られます) を書き込みます. xl_set() 関数の列方向バージョンです.

xl_set(行1, 列1, 行2, 列2, リスト(2 次元配列相当)): 指定された矩形領域のセルにリスト(2 次元配列相当)データを書き込みます.

xl_get(行1, 列1, 行2, リスト(1 次元配列相当)): 指定された列の領域のセルにリスト(1 次元配列相当)データを書き込みます.

xl_get(行1, 列1, データ): 指定された単一セルに単一データを書き込みます.

指定された行1, 列1, 行2, 列2をはみ出すデータは無視されます. また, データが不足する場合には対応する部分には書き込みを行いません

使用例は次のとおりです.

xlc_set(4, 1, 7, 3, [[1, 4, 7, 10], [2, 5, 8, 11], [3, 6, 9, 12]])
xlc_set(4, 1, 7, 1, [[1, 4, 7, 10]])
xlc_set(4, 1, 4, 3, [[1], [2], [3]])
xlc_set(4, 1, 4, 1, [[1]])
xlc_set(4, 1, 7, [1, 4, 7, 10])
xlc_set(4, 1, 1)