Book¶

class Book(fullname=None, update_links=None, read_only=None, format=None, password=None, write_res_password=None, ignore_read_only_recommended=None, origin=None, delimiter=None, editable=None, notify=None, converter=None, add_to_mru=None, local=None, corrupt_load=None, impl=None, json=None, mode=None, engine=None, **kwargs)¶

A book object is a member of the books collection:

>>> import xlwings as xw
>>> xw.books[0]
<Book [Book1]>

The easiest way to connect to a book is offered by xw.Book: it looks for the book in all app instances and returns an error, should the same book be open in multiple instances. To connect to a book in the active app instance, use xw.books and to refer to a specific app, use:

>>> app = xw.App()  # or xw.apps[10559] (get the PIDs via xw.apps.keys())
>>> app.books['Book1']

	xw.Book	xw.books
New book	`xw.Book()`	`xw.books.add()`
Unsaved book	`xw.Book('Book1')`	`xw.books['Book1']`
Book by (full)name	`xw.Book(r'C:/path/to/file.xlsx')`	`xw.books.open(r'C:/path/to/file.xlsx')`

パラメータ:

fullname (str | PathLike[str] | None) -- 既存のワークブックのフルパスまたは名前(xlsx、xlsm等を含む)、もしくは未保存のワークブックの名前。フルパス以外の場合、カレントワーキングディレクトリーからファイルを探します。
update_links (bool | None) -- 引数が省略された場合、リンクのアップデートについてのプロンプトが現れます。
read_only (bool | None) -- Trueにすればワークブックを読み取り専用で開きます
format (str | None) -- テキストファイルを開くときの区切り文字を指定します
password (str | None) -- ワークブックを開くときのパスワード
write_res_password (str | None) -- ワークブックに書き込むときのパスワード
ignore_read_only_recommended (bool | None) -- True を設定すれば読み取り専用を推奨するメッセージを非表示にできます
origin (int | None) -- For text files only. Specifies where it originated. Use Platform constants.
delimiter (str | None) -- formatの引数が6の場合、区切り文字を指定します。
editable (bool | None) -- このオプションはレガシーなMicrosoft Excel 4.0アドイン専用です。
notify (bool | None) -- 読み込み/書き込みモードで開けなかったファイルが、使えるようになった時にユーザーに通知します。
converter (int | None) -- ファイルオープン時に最初に使用するコンバーターのインデックス
add_to_mru (bool | None) -- このワークブックを最近追加したワークブックのリストに追加します。
local (bool | None) -- True の場合、Excelの言語に反してファイルを保存します。そうでなければ、VBAの言語に反して保存します。macOSではサポートされていません。
corrupt_load (int | None) -- xlNormalLoad、xlRepairFile、xlExtractDataから選択します。macOSではサポートされていません。
json (dict[str, Any] | None) -- A JSON object as delivered by the MS Office Scripts or Google Apps Script xlwings module but in a deserialized form, i.e., as dictionary. New in version 0.26.0.
mode (str | None) -- Either "i" (interactive (default)) or "r" (read). In interactive mode, xlwings opens the workbook in Excel, i.e., Excel needs to be installed. In read mode, xlwings reads from the file directly, without requiring Excel to be installed. Read mode requires xlwings PRO. New in version 0.28.0.

activate(steal_focus=False)¶

ブックをアクティブにします。

パラメータ:: steal_focus (bool) -- Trueの場合、最も前面のウインドウにし、フォーカスをPythonからExcelに変更します。

property api: Any¶: Returns the native object (pywin32 or appscript obj) of the engine being used.

Added in version 0.9.0.

property app: App¶: ブックを開いているappオブジェクトを返します。

Added in version 0.9.0.

classmethod caller()¶

References the calling book when the Python function is called from Excel via RunPython. Pack it into the function being called from Excel, e.g.:

import xlwings as xw

 def my_macro():
    wb = xw.Book.caller()
    wb.sheets[0].range('A1').value = 1

To be able to easily invoke such code from Python for debugging, use xw.Book.set_mock_caller().

Added in version 0.3.0.

close()¶

保存せずにブックを閉じます。

Added in version 0.1.1.

async flush()¶

Flushes all pending actions to Excel and the Output pane.

Requires xlwings Lite.

Added in version 0.35.0.

property fullname: str¶: ディスク上のパスを含むオブジェクトの名前を文字列で返します。読み取り専用。

async get_selection()¶

Returns the selected cells as Range, fetched live from Excel.

Requires xlwings Lite.

Added in version 0.35.0.

json()¶

Returns a JSON serializable object as expected by the MS Office Scripts or Google Apps Script xlwings module. Only available with book objects that have been instantiated via xw.Book(json=...).

Added in version 0.26.0.

async load()¶

Loads the book's current data from Excel on demand.

Requires xlwings Lite.

macro(name)¶

Excel VBA内のSubまたはFunctionを実行します。

パラメータ:: name (str) -- 'Module1.MyMacro' or 'MyMacro'

サンプル

Function MySum(x, y)
    MySum = x + y
End Function

このように使うことができます:

>>> import xlwings as xw
>>> wb = xw.books.active
>>> my_sum = wb.macro('MySum')
>>> my_sum(1, 2)
3

See also: App.macro

Added in version 0.7.1.

property name: str¶: ブックの名前を文字列で返します。

property names: Names¶: ブックに含まれる（シート固有のものを含む）すべての名前の定義を表すnamesコレクションを返します。

バージョン 0.9.0 で変更.

render_template(**data)¶

This method requires xlwings PRO.

Replaces all Jinja variables (e.g {{ myvar }}) in the book with the keyword argument of the same name.

Added in version 0.25.0.

パラメータ:: data (Any) -- All key/value pairs that are used in the template.

サンプル

>>> import xlwings as xw
>>> book = xw.Book()
>>> book.sheets[0]['A1:A2'].value = '{{ myvar }}'
>>> book.render_template(myvar='test')

save(path=None, password=None)¶

Saves the Workbook. If a path is provided, this works like SaveAs() in Excel. If no path is specified and if the file hasn't been saved previously, it's saved in the current working directory with the current filename. Existing files are overwritten without prompting. To change the file type, provide the appropriate extension, e.g. to save myfile.xlsx in the xlsb format, provide myfile.xlsb as path.

パラメータ:

path (str | PathLike[str] | None) -- Path where you want to save the Book.
password (str | None) -- Protection password with max. 15 characters New in version 0.25.1.

サンプル

>>> import xlwings as xw
>>> wb = xw.Book()
>>> wb.save()
>>> wb.save(r'C:\path\to\new_file_name.xlsx')

Added in version 0.3.1.

property selection: Range | None¶: 選択しているセルをRangeとして返します。

Added in version 0.9.0.

set_mock_caller()¶

Sets the Excel file which is used to mock xw.Book.caller() when the code is called from Python and not from Excel via RunPython.

サンプル

# This code runs unchanged from Excel via RunPython and from Python directly
import os
import xlwings as xw

def my_macro():
sht = xw.Book.caller().sheets[0]
sht.range('A1').value = 'Hello xlwings!'

if __name__ == '__main__':
xw.Book('file.xlsm').set_mock_caller()
my_macro()

Added in version 0.3.1.

property sheet_names: list[str]¶

戻り値:: List of sheet names in order of appearance.

Added in version 0.28.1.

property sheets: Sheets¶: ブック内のすべてのsheetを表すsheetsコレクションを返します。

Added in version 0.9.0.

async sync()¶

バージョン 0.35.0 で非推奨: Use flush instead.

to_pdf(path=None, include=None, exclude=None, layout=None, exclude_start_string='#', show=False, quality='standard')¶

Exports the whole Excel workbook or a subset of the sheets to a PDF file. If you want to print hidden sheets, you will need to list them explicitely under include.

パラメータ:

path (str | PathLike[str] | None) -- PDFファイルのパスで、デフォルトはワークブックと同じ名前、ディレクトリーになります。保存されていないワークブックの場合は、代わりにカレントワーキングディレトリーになります。
include (int | str | list[int | str] | None) -- どのシートを含めるか: シート番号（Excelのように1から始まるもの）またはシート名あるいはそれらのリストで指定します。
exclude (int | str | list[int | str] | None) -- どのシートを除くか: シート番号（Excelのように1から始まるもの）またはシート名あるいはそれらのリストで指定します。
layout (str | PathLike[str] | None) -- This argument requires xlwings PRO. Path to a PDF file on which the report will be printed. This is ideal for headers and footers as well as borderless printing of graphics/artwork. The PDF file either needs to have only 1 page (every report page uses the same layout) or otherwise needs the same amount of pages as the report (each report page is printed on the respective page in the layout PDF). New in version 0.24.3.
exclude_start_string (str) -- Sheet names that start with this character/string will not be printed. New in version 0.24.4.
show (bool) -- Once created, open the PDF file with the default application. New in version 0.24.6.
quality (str) -- Quality of the PDF file. Can either be 'standard' or 'minimum'. New in version 0.26.2.

サンプル

>>> wb = xw.Book()
>>> wb.sheets[0]['A1'].value = 'PDF'
>>> wb.to_pdf()