シンタックス概要

xlwingsのオブジェクト モデルは、VBAにかなり似ています。

これ以降のすべてのコード サンプルは次のインポートを前提としています:

>>> import xlwings as xw

アクティブなオブジェクト

# Active app (i.e. Excel instance)
>>> app = xw.apps.active

# Active book
>>> wb = xw.books.active  # in active app
>>> wb = app.books.active  # in specific app

# Active sheet
>>> sheet = xw.sheets.active  # in active book
>>> sheet = wb.sheets.active  # in specific book

A1参照形式、Excelの1から始まるインデックスのタプル、名前の定義のいずれの方法でも、Rangeのインスタンスを取得できます:

import xlwings as xw
sheet1 = xw.Book("MyBook.xlsx").sheets[0]

sheet1.range("A1")
sheet1.range("A1:C3")
sheet1.range((1,1))
sheet1.range((1,1), (3,3))
sheet1.range("NamedRange")

# Or using index/slice notation
sheet1["A1"]
sheet1["A1:C3"]
sheet1[0, 0]
sheet1[0:4, 0:4]
sheet1["NamedRange"]

完全修飾

インデックスの開始番号は、丸括弧()ならExcelと同じく1から、角括弧[]ならPythonと同じく0から（こちらはスライスも可）となります。次の例はいずれも同じRangeを参照しています:

xw.apps[763].books[0].sheets[0].range('A1')
xw.apps(10559).books(1).sheets(1).range('A1')
xw.apps[763].books['Book1'].sheets['Sheet1'].range('A1')
xw.apps(10559).books('Book1').sheets('Sheet1').range('A1')

appsのキーはプロセスID(PID)であるため、人によって異なることに留意してください。PIDの一覧は、xw.apps.keys() を実行すれば取得できます。

Appコンテキスト マネージャー

App() で新しいExcelインスタンスを開く場合、通常、App をコンテキスト マネージャとして使用する必要があります。これにより、確実かつ適切にExcelインスタンスを閉じてクリーンアップできます:

with xw.App() as app:
    book = app.books['Book1']

Rangeのインデックス/スライス

Rangeオブジェクトはインデックスとスライスをサポートしています。例を見てみましょう:

>>> myrange = xw.Book().sheets[0].range('A1:D5')
>>> myrange[0, 0]
 <Range [Workbook1]Sheet1!$A$1>
>>> myrange[1]
 <Range [Workbook1]Sheet1!$B$1>
>>> myrange[:, 3:]
<Range [Workbook1]Sheet1!$D$1:$D$5>
>>> myrange[1:3, 1:3]
<Range [Workbook1]Sheet1!$B$2:$C$3>

Rangeのショートカット

インデックスやスライスを使って、SheetオブジェクトからRangeオブジェクトを参照することができます。評価結果は、指定する方法が文字列かインデックス/スライスかにより、 sheet.range か sheet.cells のいずれかになります:

>>> sheet = xw.Book().sheets['Sheet1']
>>> sheet['A1']
<Range [Book1]Sheet1!$A$1>
>>> sheet['A1:B5']
<Range [Book1]Sheet1!$A$1:$B$5>
>>> sheet[0, 1]
<Range [Book1]Sheet1!$B$1>
>>> sheet[:10, :10]
<Range [Book1]Sheet1!$A$1:$J$10>

オブジェクトの階層構造

次の例でオブジェクトの階層構造を見てみましょう。appオブジェクトからrangeオブジェクトを取得する方法およびその反対方向がわかります:

>>> myrange = xw.apps[10559].books[0].sheets[0].range('A1')
>>> myrange.sheet.book.app
<Excel App 10559>