アドインおよび設定¶
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¶
Added in version 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
で作成したワークブックであれば、参照設定への追加は必要ありません。
ユーザー設定¶
アドインの設定は、最初のインストール時に自動的に調整されるため、、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.
その他の方法: 独立したVBA モジュール¶
アドインをインストールせずにxlwingsのコードを実行するのが有用なときもあります。プロジェクト作成時に standalone
オプションを使用すれば、そのようにできます: xlwings quickstart myproject --standalone
。
これはアドインの内容を1つのVBAモジュールとしてブックに追加するもので、アドインへの参照設定が不要になります。 macOSでは、さらに Dictionary.cls
を含める必要があります。なお、この方法でも xlwings.conf
の設定は読み込まれますし、 xlwings.conf
シートで上書きすることもできます。