アドインおよび設定#

_images/ribbon.png

xlwingsのアドインをインストールすることで、 Run main ボタン、 RunPython および UDF が使えるようになります。なお、PythonのスクリプトでExcelを操作するだけであれば、アドインは不要です。

注釈

アドインのリボンは、WindowsならExcel 2007以降、macOSならExcel 2016以降で使えます。なお、UDF関連機能はmacOSでは使えません。

注釈

The add-in is password protected with the password xlwings. For debugging or to add new extensions, you need to unprotect it.

Run main#

バージョン 0.16.0 で追加.

Pythonのコードを実行する一番簡単な方法は、Run main ボタンです。このボタンは、ワークブックと同じ名前のPythonモジュールにある main 関数を実行します。この方法なら、マクロが無効化された xlsx 形式でワークブックを保存できます。また、 xlwings quickstart コマンドから、 Run ボタンが自動的に機能するワークブックを作成することもできます。

インストール#

アドインをインストールするには、コマンド ライン クライアントで次のコマンドを実行します:

xlwings addin install

技術的には、このコマンドは、Pythonのインストール ディレクトリからExcelの XLSTART ディレクトリに、アドインをコピーします。 次に、ワークブックで RunPython や UDFs を使用するために、VBAエディタの参照設定に xlwings を追加します。次のスクリーンショットを見てください(Windows: ツール > 参照設定... , Mac: VBAエディタの左下の角)。なお、 xlwings quickstart で作成したワークブックであれば、参照設定への追加は必要ありません。

_images/vba_reference.png

ユーザー設定#

アドインの設定は、最初のインストール時に自動的に調整されるため、、quickstart で作成したプロジェクトは十分に機能します。ファインチューニングを行うには、以下を設定します。

  • Interpreter: Python インタープリターのパスを設定します。この設定はMac上の仮想環境かconda環境でも機能します。Windowsでconda環境を使用する場合は空白のままとし、代わりに以下で説明する Conda Path と Conda Env を設定してください。例: "C:\Python35\pythonw.exe" または "/usr/local/bin/python3.5"。なお、configファイルにはそれぞれ Interpreter_Win または Interpreter_Mac として保存されています（以下を参照）。

  • PYTHONPATH: コードのソースファイルが見つからない場合、ここにディレクトリーのパスを追加してください。

  • Conda Path: WindowsでAnacondaかMinicondaを使用している場合、ここにインストール先のパスを、入力してください。 例: C:\Users\Username\Miniconda3 や %USERPROFILE%\Anaconda 。なお、conda 4.6以上が必要となります。 Conda Env の設定も必要となりますので、次もご覧ください。

  • Conda Env: WindowsでAnacondaかMinicondaを使っている場合、ここにconda環境の名前を入力してください。例えば、ベース インストールであれば base 、 myenv という名前のconda環境であれば myenv とします。

  • UDF Modules: UDFをインポートするPythonモジュールの名前（.py拡張子を除く）。モジュールが複数の場合は";"で区切ります。例: UDF_MODULES = "common_udfs;myproject" 何も入力しなければ、Excel スプレッドシートと同じディレクトリにある同じ名前のファイル（拡張子は .py）をインポートします。

  • Debug UDFs: Check this box if you want to run the xlwings COM server manually for debugging, see デバッグ.

  • RunPython: Use UDF Server: RunPythonでUDFと同じCOMサーバーを使用します。コールの都度インタープリターをシャットダウンしないため、動作が速くなります。

  • Restart UDF Server: UDF Server/Pythonインタープリターを再起動します。

  • Show Console: コマンド プロンプトを表示するには、リボンのボックスにチェックするかconfigファイルで TRUE を設定してください。これは現在Windowsのみで有効です。

  • ADD_WORKBOOK_TO_PYTHONPATH: このチェック ボックスをオフにすると、ワークブックのディレクトリが自動的に PYTHONPATH に追加されません。これは、OneDrive/SharePointで問題が発生した場合に役立ちます。このボックスのチェックを外し、PYTHONPATH設定でソース ファイルのパスを手動で指定します。

Anaconda/Miniconda#

WindowsでAnacondaかMinicondaを使用している場合、 Numpy 等の使用時にエラーとならないよう、 Conda Path と Conda Env を設定し、 Interpreter を空白にする必要があります。

環境変数を利用する#

環境変数を使えば、インタープリターや PYTHONPATH へのパス等を動的に設定することができます:

  • Windowsでは、 %USERPROFILE%\Anaconda のようなすべての環境変数を利用できます。

  • macOSでは、次の変数をサポートしています: $HOME 、 $APPLICATIONS 、 $DOCUMENTS 、 $DESKTOP 。

Config Hierarchy#

xlwings looks for settings in the following locations and order:

  • Workbook configuration

    First, xlwings looks for a sheet called xlwings.conf. This is the recommended way to configure your workbook for deployment as you don't have to handle an additional config file. When you run the quickstart command, it will create a sample configuration on a sheet called _xlwings.conf: remove the leading underscore in the name to activate it. If you don't want to use it, feel free to delete the sheet.

  • Directory configuration

    Next, xlwings looks for a file called xlwings.conf in the same directory as your Excel workbook.

  • User configuration

    Finally, xlwings looks for a file called xlwings.conf in the .xlwings folder in the user's home directory. Normally, you don't edit this file directly—instead, it is created and edited by the add-in whenever you change a setting.

You will find more details about the each configuration type below.

Source: The section "Config Hierarchy" is taken from "Python for Excel by Felix Zumstein (O'Reilly). Copyright 2021 Zoomer Analytics LLC, 978-1-492-08100-5."

ユーザー設定: リボン/Config ファイル#

xlwingsのリボンで行った設定はコンフィグファイルに保存されていますが、手動で設定することもできます。その場所は以下のとおりです。

  • Windows: ホーム フォルダー（通常は C:\Users\<username> ）にある .xlwings\xlwings.conf

  • macOS: ~/Library/Containers/com.microsoft.Excel/Data/xlwings.conf

フォーマットは次のとおり（現在のところキー項目は全て大文字でなければなりません） - OS依存のインタープリター設定があることに注意!

"INTERPRETER_WIN","C:\path\to\python.exe"
"INTERPRETER_MAC","/path/to/python"
"PYTHONPATH",""
"ADD_WORKBOOK_TO_PYTHONPATH",""
"CONDA PATH",""
"CONDA ENV",""
"UDF MODULES",""
"DEBUG UDFS",""
"USE UDF SERVER",""
"SHOW CONSOLE",""
"ONEDRIVE_CONSUMER_WIN",""
"ONEDRIVE_CONSUMER_WIN",""
"ONEDRIVE_COMMERCIAL_WIN",""
"ONEDRIVE_COMMERCIAL_MAC",""
"SHAREPOINT_WIN",""
"SHAREPOINT_MAC",""

注釈

ONEDRIVE_WIN/_MAC の設定はファイルでの直接編集しかできません。また、現在のところリボンで設定可能にする予定もありません。通常、macOSを使用しているか、Windows上の環境変数が正しく設定されていないか、プライベートかつ会社用のロケーションを持ちデフォルトのものを使用したくない場合にのみこの設定が必要になります。ONEDRIVE_WIN/_MAC にはローカルのOneDriveフォルダーのルートを設定してください。

Directory Config: Config file#

ワークブックのディレクトリに xlwings.conf ファイルを作れば、リボン/Config ファイルのグローバル設定を上書きできます。

注釈

ワークブック ディレクトリのConfigファイルは、ワークブックがSharePointやOneDriveに保存されている場合には対応していません。

ワークブック設定: xlwings.conf シート#

Workbook specific settings will override global (Ribbon) and workbook directory config files: Workbook specific settings are set by listing the config key/value pairs in a sheet with the name xlwings.conf. When you create a new project with xlwings quickstart, it'll already have such a sheet but you need to rename it from _xlwings.conf to xlwings.conf to make it active.

_images/workbook_config.png

その他の方法: 独立したVBA モジュール#

アドインをインストールせずにxlwingsのコードを実行するのが有用なときもあります。プロジェクト作成時に standalone オプションを使用すれば、そのようにできます: xlwings quickstart myproject --standalone。

これはアドインの内容を1つのVBAモジュールとしてブックに追加するもので、アドインへの参照設定が不要になります。 macOSでは、さらに Dictionary.cls を含める必要があります。なお、この方法でも xlwings.conf の設定は読み込まれますし、 xlwings.conf シートで上書きすることもできます。