Python API

Top-level functions

xlwings.load(index=1, header=1, chunksize=5000)

Loads the selected cell(s) of the active workbook into a pandas DataFrame. If you select a single cell that has adjacent cells, the range is auto-expanded (via current region) and turned into a pandas DataFrame. If you don't have pandas installed, it returns the values as nested lists.

注釈

Only use this in an interactive context like e.g. a Jupyter notebook! Don't use this in a script as it depends on the active book.

パラメータ
  • index (bool or int, default 1) -- DataFrameのインデックスとして取り込む左側の列の数を定義します。

  • header (bool or int, default 1) -- DataFrameの列名として取り込む上部の列数を定義します。

  • chunksize (int, default 5000) -- Chunks the loading of big arrays.

>>> import xlwings as xw
>>> xw.load()

view を参考

バージョン 0.23.1 で変更.

xlwings.view(obj, sheet=None, table=True, chunksize=5000)

デフォルトでは、新しいワークブックを開き、その最初のシートにオブジェクトを表示します。シートを指定すれば、シートをクリアした上でオブジェクトを表示します。

注釈

Only use this in an interactive context like e.g. a Jupyter notebook! Don't use this in a script as it depends on the active book.

パラメータ
  • obj (any type with built-in converter) -- 表示するオブジェクト。例えば、数字、文字列、リスト、numpy arrays、pandas dataframes

  • sheet (Sheet, default None) -- Sheet オブジェクト。指定がなければ新しいワークブックの最初のシートになります。

  • table (bool, default True) -- 表示するオブジェクトがpandas DataFrameなら、Excelのテーブルとしてフォーマットされます。

  • chunksize (int, default 5000) -- Chunks the loading of big arrays.

>>> import xlwings as xw
>>> import pandas as pd
>>> import numpy as np
>>> df = pd.DataFrame(np.random.rand(10, 4), columns=['a', 'b', 'c', 'd'])
>>> xw.view(df)

load を参考

バージョン 0.22.0 で変更.

オブジェクト モデル

Apps

class xlwings.main.Apps(impl)

すべての:meth:app <App> オブジェクトのコレクション:

>>> import xlwings as xw
>>> xw.apps
Apps([<Excel App 1668>, <Excel App 1644>])
property active

戻り値はアクティブなappです。

バージョン 0.9.0 で追加.

add()

新規Appを作成し戻します。新しいAppはアクティブになります。

property count

戻り値はAppオブジェクトの数です。

バージョン 0.9.0 で追加.

keys()

Appsコレクションのキーとなる、各ExcelインスタンスのPIDを返します。

バージョン 0.13.0 で追加.

App

class xlwings.App(visible=None, spec=None, add_book=True, impl=None)

An app corresponds to an Excel instance and should normally be used as context manager to make sure that everything is properly cleaned up again and to prevent zombie processes. New Excel instances can be fired up like so:

import xlwings as xw

with xw.App() as app:
    print(app.books)

appオブジェクトは apps コレクションのメンバーです:

>>> xw.apps
Apps([<Excel App 1668>, <Excel App 1644>])
>>> xw.apps[1668]  # get the available PIDs via xw.apps.keys()
<Excel App 1668>
>>> xw.apps.active
<Excel App 1668>
パラメータ
  • visible (bool, default None) -- 表示するか否かのブール値を戻すもしくは設定します。デフォルトでは値は変更されないか、オブジェクトがまだ存在していない場合にはvisible=Trueが設定されます。

  • spec (str, default None) --

    Macのみ、Excelアプリケーションへのフルパスを指定します。例えば、/Applications/Microsoft Office 2011/Microsoft Excel/Applications/Microsoft Excel

    Windowsでは、xlwingsと連携するExcelのバージョンを変更したい場合、コントロールパネル > プログラムと機能 からデフォルトで使いたいオフィスのバージョンに 変更 します。

注釈

Macでは、xlwingsを使えば複数のExcelインスタンスを実行できますが、複数のExcelインスタンスの実行はMac版Excelでは公式にはサポートされていません: Windowsとは異なり、既に他のインスタンスで開かれているファイルをを開こうとする時に、Excelは読み取り専用で開くかどうかを聞きません。したがって、同じファイルが異なるインスタンスから上書きされていないかどうかを気を付ける必要があります。

activate(steal_focus=False)

Exel appをアクティブにします。

パラメータ

steal_focus (bool, default False) -- Trueの場合、最も前面のアプリケーションにして、フォーカスをPythonからExcelに変更します。

バージョン 0.9.0 で追加.

property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

バージョン 0.9.0 で追加.

property books

現在開かれているすべてのBookオブジェクトのコレクション。

バージョン 0.9.0 で追加.

calculate()

開いているすべてのブックで再計算します。

バージョン 0.3.6 で追加.

property calculation

計算モードを表す値を返すまたは設定します。 計算モード: 'manual''automatic''semiautomatic'

>>> import xlwings as xw
>>> wb = xw.Book()
>>> wb.app.calculation = 'manual'

バージョン 0.9.0 で変更.

property cut_copy_mode

Gets or sets the status of the cut or copy mode. Accepts False for setting and returns None, copy or cut when getting the status.

バージョン 0.24.0 で追加.

property display_alerts

デフォルト値はTrueです。コード実行中のプロンプトやアラート メッセージを非表示にするには、Falseを設定します。Falseに設定した場合、メッセージがレスポンスを必要とするときにはExcelはデフォルト値で返します。

バージョン 0.9.0 で追加.

property enable_events

True if events are enabled. Read/write boolean.

バージョン 0.24.4 で追加.

property hwnd

Windowハンドルを返します(Windowsのみ)。

バージョン 0.9.0 で追加.

property interactive

True if Excel is in interactive mode. If you set this property to False, Excel blocks all input from the keyboard and mouse (except input to dialog boxes that are displayed by your code). Read/write Boolean. Note: Not supported on macOS.

バージョン 0.24.4 で追加.

kill()

プロセスをキルしてExcelアプリを強制的に終了します。

バージョン 0.9.0 で追加.

macro(name)

特定のワークブックではない、アドイン等に含まれるExcel VBAのSubやFunctionを実行します。

パラメータ

name (Name of Sub or Function with or without module name, e.g. 'Module1.MyMacro' or 'MyMacro') --

次のVBA関数は

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

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

>>> import xlwings as xw
>>> app = xw.App()
>>> my_sum = app.macro('MySum')
>>> my_sum(1, 2)
3

Types are supported too:

>>> import xlwings as xw
>>> app = xw.App()
>>> my_sum = app.macro('MySum')
>>> my_sum(1, 2)
3

However typed arrays are not supported. So the following won't work


Function MySum(arr() as integer)

''' code here

End Function

Book.macro() をご覧ください。

バージョン 0.9.0 で追加.

property pid

appのPIDを返します。

バージョン 0.9.0 で追加.

properties(**kwargs)

Context manager that allows you to easily change the app's properties temporarily. Once the code leaves the with block, the properties are changed back to their previous state. Note: Must be used as context manager or else will have no effect. Also, you can only use app properties that you can both read and write.

import xlwings as xw
app = App()

# Sets app.display_alerts = False
with app.properties(display_alerts=False):
    # do stuff

# Sets app.calculation = 'manual' and app.enable_events = True
with app.properties(calculation='manual', enable_events=True):
    # do stuff

# Makes sure the status bar is reset even if an error happens in the with block
with app.properties(status_bar='Calculating...'):
    # do stuff

バージョン 0.24.4 で追加.

quit()

ワークブックを保存せずにアプリケーションを終了します。

バージョン 0.3.3 で追加.

range(cell1, cell2=None)

アクティブブックのアクティブシートのRangeオブジェクトを返します。Range() を参照。

バージョン 0.9.0 で追加.

render_template(template=None, output=None, book_settings=None, **data)

This function requires xlwings PRO.

This is a convenience wrapper around mysheet.render_template

Writes the values of all key word arguments to the output file according to the template and the variables contained in there (Jinja variable syntax). Following variable types are supported:

strings, numbers, lists, simple dicts, NumPy arrays, Pandas DataFrames, pictures and Matplotlib/Plotly figures.

パラメータ
  • template (str or path-like object) -- Path to your Excel template, e.g. r'C:\Path\to\my_template.xlsx'

  • output (str or path-like object) -- Path to your Report, e.g. r'C:\Path\to\my_report.xlsx'

  • book_settings (dict, default None) -- A dictionary of xlwings.Book parameters, for details see: xlwings.Book. For example: book_settings={'update_links': False}.

  • data (kwargs) -- All key/value pairs that are used in the template.

戻り値

  • wb (xlwings Book)

  • .. versionadded:: 0.24.4

property screen_updating

スクリプトの処理を速くするために、スクリーンの更新を止めます。スクリプトが何をしているのかが見えなくなる代わりに、速くなります。スクリプト終了時にTrueに戻すことを忘れないでください。

バージョン 0.3.3 で追加.

property selection

選択しているセルをRangeとして返します。

バージョン 0.9.0 で追加.

property startup_path

xlwings addin install コマンドでxlwingsアドインをコピーした先の``XLSTART`` フォルダーのパスを返します。

バージョン 0.19.4 で追加.

property status_bar

ステータスバーの値を取得または設定します。Excelがステータスバーをコントロールしている場合には False を返します。

バージョン 0.20.0 で追加.

property version

Excelのバージョン番号のオブジェクトを返します。

>>> import xlwings as xw
>>> xw.App().version
VersionNumber('15.24')
>>> xw.apps[10559].version.major
15

バージョン 0.9.0 で変更.

property visible

Excelを表示するか否かを True または False で取得または設定します。

バージョン 0.3.3 で追加.

Books

class xlwings.main.Books(impl)

すべての book オブジェクトのコレクション:

>>> import xlwings as xw
>>> xw.books  # active app
Books([<Book [Book1]>, <Book [Book2]>])
>>> xw.apps[10559].books  # specific app, get the PIDs via xw.apps.keys()
Books([<Book [Book1]>, <Book [Book2]>])

バージョン 0.9.0 で追加.

property active

アクティブなBookを返します。

add()

新しいBookを作成し、返します。新しいBookはアクティブになります。

open(fullname, 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)

開いていなければ、ブックを開き返します。既に開いていれば、エラーは出さずにBookオブジェクトを返します。

パラメータ
  • fullname (str or path-like object) -- ファイル名またはフルパス。例えば r'C:\path\to\file.xlsx''file.xlsm'。フルパス以外の場合、カレント ワーキング ディレクトリーからファイルを探します。

  • Parameters (Other) -- xlwings.Book() を参考

戻り値

Book

戻り値の型

Book that has been opened.

Book

class xlwings.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)

bookオブジェクトは books コレクションのメンバーです:

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

xw.Book を使えば、最も簡単にブックに接続できます: xw.Book は接続先のブックを開いているかどうかを全てのExcelインスタンスに対して確認し、もし複数のExcelインスタンスが接続先のブックを同時に開いていればエラーを返します。アクティブなExcelインスタンスのブックに接続するには、 xw.books を使います。また、特定のappを参照するには次のようにします:

>>> app = xw.App()  # or something like xw.apps[10559] for existing apps, 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 or path-like object, default None) -- 既存のワークブックのフルパスまたは名前(xlsx、xlsm等を含む)、もしくは未保存のワークブックの名前。フルパス以外の場合、カレント ワーキング ディレクトリーからファイルを探します。

  • update_links (bool, default None) -- 引数が省略された場合、リンクのアップデートについてのプロンプトが現れます。

  • read_only (bool, default False) -- Trueにすればワークブックを読み取り専用で開きます

  • format (str) -- テキストファイルを開くときの区切り文字を指定します

  • password (str) -- ワークブックを開くときのパスワード

  • write_res_password (str) -- ワークブックに書き込むときのパスワード

  • ignore_read_only_recommended (bool, default False) -- True を設定すれば読み取り専用を推奨するメッセージを非表示にできます

  • origin (int) -- テキストファイル専用。どこでテキストファイルが生成されたかを特定します。XlPlatform定数を使用します。

  • delimiter (str) -- formatの引数が6の場合、区切り文字を指定します。

  • editable (bool, default False) -- このオプションはレガシーなMicrosoft Excel 4.0アドイン専用です。

  • notify (bool, default False) -- 読み込み/書き込みモードで開けなかったファイルが、使えるようになった時にユーザーに通知します。

  • converter (int) -- ファイルオープン時に最初に使用するコンバーターのインデックス

  • add_to_mru (bool, default False) -- このワークブックを最近追加したワークブックのリストに追加します。

  • local (bool, default False) -- True の場合、Excelの言語に反してファイルを保存します。そうでなければ、VBAの言語に反して保存します。macOSではサポートされていません。

  • corrupt_load (int, default xlNormalLoad) -- xlNormalLoad、xlRepairFile、xlExtractDataから選択します。macOSではサポートされていません。

activate(steal_focus=False)

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

パラメータ

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

property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

バージョン 0.9.0 で追加.

property app

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

バージョン 0.9.0 で追加.

classmethod caller()

Pythonの関数がExcelから RunPython で呼び出されている場合に、呼び出し元のブックを参照します。Excelから呼び出されている関数の中に入れてください。例:

import xlwings as xw

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

Pythonやデバッグ時にそのようなコードを簡単に実行するには、xw.Book.set_mock_caller() を使用してください。

バージョン 0.3.0 で追加.

close()

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

バージョン 0.1.1 で追加.

property fullname

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

macro(name)

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

パラメータ

name (Name of Sub or Function with or without module name, e.g. 'Module1.MyMacro' or 'MyMacro') --

次のVBA関数は

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

App.macro() を参照

バージョン 0.7.1 で追加.

property name

ブックの名前を文字列で返します。

property names

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

バージョン 0.9.0 で変更.

render_template(**data)

このメソッドはxlwings PRO でのみ使用できます。

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

バージョン 0.25.0 で追加.

パラメータ

data (kwargs) -- 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)

ワークブックを保存します。pathが指定されれば、ExcelのSaveAs()と同様に動作します。pathの指定がなく保存されていないファイルの場合は、カレント ワーキング ディレクトリーに現在のファイル名で保存されます。存在するファイルはプロンプトなしで上書きされます。

パラメータ

path (str or path-like object, default None) -- ワークブックのフルパス

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

バージョン 0.3.1 で追加.

property selection

選択しているセルをRangeとして返します。

バージョン 0.9.0 で追加.

set_mock_caller()

コードがExcelから RunPython で呼び出されるのではなく、Pythonから呼び出されている場合に、Excelファイルを xw.Book.caller() として利用するために設定します。

# 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()

バージョン 0.3.1 で追加.

property sheets

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

バージョン 0.9.0 で追加.

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

Excelワークブック全体またはシートの一部をPDFファイルにエクスポートします。非表示のシートを印刷するには、明示的に include 引数に含める必要があります。

パラメータ
  • path (str or path-like object, default None) -- PDFファイルのパスで、デフォルトはワークブックと同じ名前、ディレクトリーになります。保存されていないワークブックの場合は、代わりにカレント ワーキング ディレトリーになります。

  • include (int or str or list, default None) -- どのシートを含めるか: シート番号(Excelのように1から始まるもの)またはシート名あるいはそれらのリストで指定します。

  • exclude (int or str or list, default None) -- どのシートを除くか: シート番号(Excelのように1から始まるもの)またはシート名あるいはそれらのリストで指定します。

  • layout (str or path-like object, default 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).

    バージョン 0.24.3 で追加.

  • exclude_start_string (str, default '#') --

    Sheet names that start with this character/string will not be printed.

    バージョン 0.24.4 で追加.

  • show (bool, default False) --

    Once created, open the PDF file with the default application.

    バージョン 0.24.6 で追加.

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

xlwings.Sheet.to_pdf() を参考

バージョン 0.21.1 で追加.

PageSetup

class xlwings.main.PageSetup(impl)
property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

バージョン 0.24.2 で追加.

property print_area

Gets or sets the range address that defines the print area.

>>> mysheet.page_setup.print_area = '$A$1:$B$3'
>>> mysheet.page_setup.print_area
'$A$1:$B$3'
>>> mysheet.page_setup.print_area = None  # clear the print_area

バージョン 0.24.2 で追加.

Sheets

class xlwings.main.Sheets(impl)

すべての sheet オブジェクトのコレクション:

>>> import xlwings as xw
>>> xw.sheets  # active book
Sheets([<Sheet [Book1]Sheet1>, <Sheet [Book1]Sheet2>])
>>> xw.Book('Book1').sheets  # specific book
Sheets([<Sheet [Book1]Sheet1>, <Sheet [Book1]Sheet2>])

バージョン 0.9.0 で追加.

property active

アクティブなSheetを返します。

add(name=None, before=None, after=None)

新しいSheetを作成し、アクティブにします。

パラメータ
  • name (str, default None) -- 新しいシートの名前。NoneならExcelのデフォルトのシート名になります。

  • before (Sheet, default None) -- ここで指定したシートの前に新しいシートが追加されます。

  • after (Sheet, default None) -- ここで指定したシートの後に新しいシートが追加されます。

Sheet

class xlwings.Sheet(sheet=None, impl=None)

sheetオブジェクトは sheets コレクションのメンバーです:

>>> import xlwings as xw
>>> wb = xw.Book()
>>> wb.sheets[0]
<Sheet [Book1]Sheet1>
>>> wb.sheets['Sheet1']
<Sheet [Book1]Sheet1>
>>> wb.sheets.add()
<Sheet [Book1]Sheet2>

バージョン 0.9.0 で変更.

activate()

シートをアクティブにして返します。

property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

バージョン 0.9.0 で追加.

autofit(axis=None)

シート全体の列、行または両方の幅を自動調整します。

パラメータ

axis (string, default None) --

  • 行を自動調整するには以下を指定します: rows or r

  • 列を自動調整するには以下を指定します: columns or c

  • 何も指定しなければ行と列を自動調整します

>>> import xlwings as xw
>>> wb = xw.Book()
>>> wb.sheets['Sheet1'].autofit('c')
>>> wb.sheets['Sheet1'].autofit('r')
>>> wb.sheets['Sheet1'].autofit()

バージョン 0.2.3 で追加.

property book

このシートを含むBookを返します。読み取り専用。

property cells

Sheetオブジェクト上のすべてのセルを表すRangeオブジェクトを返します(現在使っているセルではありません)。

バージョン 0.9.0 で追加.

property charts

Charts を参照

バージョン 0.9.0 で追加.

clear()

シート内のすべての値と書式をクリアーします。

clear_contents()

シート内のすべての値をクリアーしますが、書式は残します。

copy(before=None, after=None, name=None)

同一ブック内または新規ブックにシートをコピーします。デフォルトでは、同一ブックの一番右側にコピーします。コピー後のシートを返します。

バージョン 0.22.0 で追加.

パラメータ
  • before (sheet object, default None) -- ここで指定したシートの左にコピーします

  • after (sheet object, default None) -- ここで指定したシートの右にコピーします。

  • name (str, default None) -- コピー後のシート名

戻り値

Sheet object -- コピー後のシート

戻り値の型

Sheet

# Create two books and add a value to the first sheet of the first book
first_book = xw.Book()
second_book = xw.Book()
first_book.sheets[0]['A1'].value = 'some value'

# Copy to same Book with the default location and name
first_book.sheets[0].copy()

# Copy to same Book with custom sheet name
first_book.sheets[0].copy(name='copied')

# Copy to second Book requires to use before or after
first_book.sheets[0].copy(after=second_book.sheets[0])
delete()

シートを削除します。

property index

シートのインデックスを返します(Excel同様1から始まるもの)。

property name

シート名を取得または設定します。

property names

このシート内のすべての名前("SheetName!" から始まるよう定義された名前)を表すnamesコレクションを返します。

バージョン 0.9.0 で追加.

property page_setup

Returns a PageSetup object.

バージョン 0.24.2 で追加.

property pictures

Pictures を参照

バージョン 0.9.0 で追加.

range(cell1, cell2=None)

アクティブなブックのアクティブなシートからRangeオブジェクトを返します。Range() を参照。

バージョン 0.9.0 で追加.

render_template(**data)

このメソッドはxlwings PRO でのみ使用できます。

Replaces all Jinja variables (e.g {{ myvar }}) in the sheet with the keyword argument that has the same name. Following variable types are supported:

strings, numbers, lists, simple dicts, NumPy arrays, Pandas DataFrames, PIL Image objects that have a filename and Matplotlib figures.

バージョン 0.22.0 で追加.

パラメータ

data (kwargs) -- 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.sheets[0].render_template(myvar='test')
select()

シートを選択します。このメソッドはブックがアクティブのときのみ機能します。

バージョン 0.9.0 で追加.

property shapes

Shapes を参照

バージョン 0.9.0 で追加.

property tables

Tables を参照

バージョン 0.21.0 で追加.

to_pdf(path=None, layout=None, show=False)

シートをPDFファイルで出力します。

パラメータ
  • path (str or path-like object, default None) -- PDFファイルのパス。デフォルトはワークブックと同じディレクトリーにシート名で保存します。未保存のワークブックの場合は、カレント ワーキング ディレトリーに保存します。

  • layout (str or path-like object, default 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).

    バージョン 0.24.3 で追加.

  • show (bool, default False) --

    Once created, open the PDF file with the default application.

    バージョン 0.24.6 で追加.

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

xlwings.Book.to_pdf() を参照

バージョン 0.22.3 で追加.

property used_range

シートで使用しているRange。

戻り値

戻り値の型

xw.Range

バージョン 0.13.0 で追加.

property visible

シートの表示/非表示(bool値)を取得または設定します。

バージョン 0.21.1 で追加.

Range

class xlwings.Range(cell1=None, cell2=None, **options)

セルまたはセル範囲を表すRangeオブジェクトを返します。

パラメータ
  • cell1 (str or tuple or Range) -- 左上セルをA1表記、インデックスのタプル、xw.Rangeオブジェクトのいずれかで指定します。'A1:B2'のようにrangeオペレーター(コロンのこと)での指定も可。

  • cell2 (str or tuple or Range, default None) -- 左下セルをA1表記、インデックスのタプル、xw.Rangeオブジェクトのいずれかで指定します。

アクティブなシートの場合:

import xlwings as xw
xw.Range('A1')
xw.Range('A1:C3')
xw.Range((1,1))
xw.Range((1,1), (3,3))
xw.Range('NamedRange')
xw.Range(xw.Range('A1'), xw.Range('B2'))

シートを指定する場合:

xw.books['MyBook.xlsx'].sheets[0].range('A1')

対象のRange(単独のセル)にハイパーリンクを追加します

パラメータ
  • address (str) -- ハイパーリンクのアドレス。

  • text_to_display (str, default None) -- ハイパーリンクに表示されるテキスト。デフォルトはハイパーリンクのアドレス。

  • screen_tip (str, default None) -- マウスポインターをハイパーリンクに合わせたときに表示される文字。デフォルト値は'<address> - Click once to follow. Click and hold to select this cell.'。

バージョン 0.3.0 で追加.

property address

参照先を表す文字列を返す。get_address() を使えば細かいパラメーターを設定できます。

バージョン 0.9.0 で追加.

property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

バージョン 0.9.0 で追加.

autofit()

Rangeに含まれるすべてのセルの幅と高さを自動調整します。

  • 列の幅のみを自動調整するには、 xw.Range('A1:B2').columns.autofit() とします。

  • 行の高さのみを自動調整するには、 xw.Range('A1:B2').rows.autofit() とします。

バージョン 0.9.0 で変更.

clear()

Rangeの値と書式をクリアーします。

clear_contents()

Rangeの値をクリアーしますが、書式は保持します。

property color

Rangeの背景色を取得または設定します。

To set the color, either use an RGB tuple (0, 0, 0) or a hex string like #efefef or an Excel color constant. To remove the background, set the color to None, see Examples.

戻り値

RGB

戻り値の型

tuple

>>> import xlwings as xw
>>> wb = xw.Book()
>>> xw.Range('A1').color = (255, 255, 255)  # or '#ffffff'
>>> xw.Range('A2').color
(255, 255, 255)
>>> xw.Range('A2').color = None
>>> xw.Range('A2').color is None
True

バージョン 0.3.0 で追加.

property column

Rangeに含まれる最初の列の番号を返します。読み取り専用。

戻り値

戻り値の型

Integer

バージョン 0.3.5 で追加.

property column_width

Rangeの幅を文字数で取得または設定します。列幅の1単位は、標準スタイルの1文字の幅と同じです。プロポーショナルフォントの場合、文字の幅0(ゼロ)が使用されます。

Range内のすべての列幅が同じ場合は、幅を返します。 Rangeの列幅が異なる場合、Noneを返します。

column_widthは次の範囲内でなければなりません:0 <= column_width <= 255

注:Rangeがワークシートの使用範囲外であり、Range内の列幅が異なる場合、最初の列幅を返します。

戻り値

戻り値の型

float

バージョン 0.4.0 で追加.

property columns

指定したRange内の列の集合を表す RangeColumns オブジェクトを返します。

バージョン 0.9.0 で追加.

copy(destination=None)

貼り付け先のRangeまたはクリップボードにRangeをコピーします。

パラメータ

destination (xlwings.Range) -- 指定したRangeのコピー先となるxlwingsのRangeオブジェクト。省略した場合、Rangeはクリップボードにコピーされます。

戻り値

戻り値の型

None

copy_picture(appearance='screen', format='picture')

Copies the range to the clipboard as picture.

パラメータ
  • appearance (str, default 'screen') -- Either 'screen' or 'printer'.

  • format (str, default 'picture') -- Either 'picture' or 'bitmap'.

  • versionadded: (.) -- 0.24.8:

property count

セルの数を返します。

property current_region

このプロパティは、空白行、空白列またはワークシートの端のいずれかの組み合わせで囲まれた(空白行等を含まない)Rangeオブジェクトを返します。Windowsでは Ctrl-* (訳注: Ctrl-a の間違いか?)、Macでは Shift-Ctrl-Space に対応します。

戻り値

戻り値の型

Range object

delete(shift=None)

セルまたはセル範囲を削除します。

パラメータ

shift (str, default None) -- left` または up を使用します。省略された場合、ExcelがRangeの形に基づき決定します。

戻り値

戻り値の型

None

end(direction)

データが入っている範囲の最後のセルを表すRangeオブジェクトを返します。Ctrl+Up、 Ctrl+down、 Ctrl+left または Ctrl+rightと同じものです。

パラメータ

direction (One of 'up', 'down', 'right', 'left') --

>>> import xlwings as xw
>>> wb = xw.Book()
>>> xw.Range('A1:B2').value = 1
>>> xw.Range('A1').end('down')
<Range [Book1]Sheet1!$A$2>
>>> xw.Range('B2').end('right')
<Range [Book1]Sheet1!$B$2>

バージョン 0.9.0 で追加.

expand(mode='table')

指定したmodeに応じてRangeを拡張します。左上セルが空白の場合は無視されます ( Range.end() とは異なる)。

パラメータ

mode (str, default 'table') -- 'table' (=downとright)、 'down''right' のいずれか。

戻り値

戻り値の型

Range

>>> import xlwings as xw
>>> wb = xw.Book()
>>> xw.Range('A1').value = [[None, 1], [2, 3]]
>>> xw.Range('A1').expand().address
$A$1:$B$2
>>> xw.Range('A1').expand('right').address
$A$1:$B$1

バージョン 0.9.0 で追加.

property formula

指定したRangeのformulaプロパティを取得または設定します。

property formula2

指定したRangeのformula2プロパティを取得または設定します。

property formula_array

指定したRangeのarray formulaプロパティを取得または設定します。

バージョン 0.7.1 で追加.

get_address(row_absolute=True, column_absolute=True, include_sheetname=False, external=False)

指定したフォーマットでRangeのアドレスを返します。すべてデフォルトのままなら代わりに address を使えます。

パラメータ
  • row_absolute (bool, default True) -- Trueを設定すれば、アドレスの行部分を絶対参照で取得します。

  • column_absolute (bool, default True) -- Trueを設定すれば、アドレスの列部分を絶対参照で取得します。

  • include_sheetname (bool, default False) -- Trueを設定すれば、アドレスにシート名が含まれます。external=Trueの場合、無視されます。

  • external (bool, default False) -- Trueを設定すれば、アドレスにワークブック名とシート名が含まれます。

戻り値

戻り値の型

str

>>> import xlwings as xw
>>> wb = xw.Book()
>>> xw.Range((1,1)).get_address()
'$A$1'
>>> xw.Range((1,1)).get_address(False, False)
'A1'
>>> xw.Range((1,1), (3,3)).get_address(True, False, True)
'Sheet1!A$1:C$3'
>>> xw.Range((1,1), (3,3)).get_address(True, False, external=True)
'[Book1]Sheet1!A$1:C$3'

バージョン 0.2.3 で追加.

property has_array

配列数式の一部かどうかを返します。

property height

Rangeの高さをポイント単位で返します。読み取り専用。

戻り値

戻り値の型

float

バージョン 0.4.0 で追加.

指定したRange(単独セルに限る)のハイパーリンク先のアドレスを返します。

>>> import xlwings as xw
>>> wb = xw.Book()
>>> xw.Range('A1').value
'www.xlwings.org'
>>> xw.Range('A1').hyperlink
'http://www.xlwings.org'

バージョン 0.3.0 で追加.

insert(shift=None, copy_origin='format_from_left_or_above')

シートにセルまたはセル範囲を挿入します。

パラメータ
  • shift (str, default None) -- right または down を使用します。省略された場合、rangeの形に基づきExcelが決定します。

  • copy_origin (str, default format_from_left_or_above) -- format_from_left_or_above または format_from_right_or_below を使用します。なお、macOSではサポートされていません。

戻り値

戻り値の型

None

property last_cell

指定したRangeの右下セルを返します。読み取り専用。

戻り値

戻り値の型

Range

>>> import xlwings as xw
>>> wb = xw.Book()
>>> rng = xw.Range('A1:E4')
>>> rng.last_cell.row, rng.last_cell.column
(4, 5)

バージョン 0.3.5 で追加.

property left

A列の左端からRangeの左端までの距離をポイント単位で返します。読み取り専用。

戻り値

戻り値の型

float

バージョン 0.6.0 で追加.

merge(across=False)

指定したRangeオブジェクトから結合セルを作ります。

パラメータ

across (bool, default False) -- Trueを設定すれば、指定したRangeの各行ごとにセルを結合します。

property merge_area

指定したRangeを含む結合セルを表すRangeオブジェクトを返します。指定したRangeが結合セルに含まれない場合、指定したRangeを返します。

property merge_cells

Rangeに結合セルが含まれていれば True 、そうでなければ False を返します。

property name

Rangeの名前を設定または取得します。

バージョン 0.4.0 で追加.

property note

Returns a Note object. Before the introduction of threaded comments, a Note was called a Comment.

バージョン 0.24.2 で追加.

property number_format

Rangeの number_format を取得または設定します。

>>> import xlwings as xw
>>> wb = xw.Book()
>>> xw.Range('A1').number_format
'General'
>>> xw.Range('A1:C3').number_format = '0.00%'
>>> xw.Range('A1:C3').number_format
'0.00%'

バージョン 0.2.3 で追加.

offset(row_offset=0, column_offset=0)

指定したRangeからオフセットしたRangeを表すRangeオブジェクトを返します。

戻り値

Range object

戻り値の型

Range

バージョン 0.3.0 で追加.

options(convert=None, **options)

コンバーターおよびそのオプションの設定をします。コンバーターは、読み込み時と書き込み時の両方で、どのようにExcelのRangeまたはその値が変換されるかを定義します。コンバーターが明示的に指定されなければ、ベース コンバーターが適用されます。 コンバーターおよびオプション を参照。

パラメータ

convert (object, default None) -- dictnp.arraypd.DataFramepd.Series 等のコンバーター。デフォルトはデフォルト コンバーター。

キーワード引数
  • ndim (int, default None) -- 次元数

  • numbers (type, default None) -- 数字の型。例 int

  • dates (type, default None) -- 例 datetime.date 。デフォルトは datetime.datetime

  • empty (object, default None) -- 空白セルの変換方法

  • transpose (Boolean, default False) -- 値の転置

  • expand (str, default None) -- One of 'table', 'down', 'right'

  • chunksize (int) --

    Use a chunksize, e.g. 10000 to prevent timeout or memory issues when reading or writing large amounts

    of data. Works with all formats, including DataFrames, NumPy arrays, and list of lists.

    => For converter-specific options, see コンバーターおよびオプション.

戻り値

戻り値の型

Range object

バージョン 0.7.0 で追加.

paste(paste=None, operation=None, skip_blanks=False, transpose=False)

クリップボードから指定したRangeに、Rangeを貼り付けます。

パラメータ
  • paste (str, default None) -- all_merging_conditional_formatsallall_except_bordersall_using_source_themecolumn_widthscommentsformatsformulasformulas_and_number_formatsvalidationvaluesvalues_and_number_formats のいずれか。

  • operation (str, default None) -- "add" 、 "divide" 、 "multiply" 、 "subtract" のいずれか。

  • skip_blanks (bool, default False) -- True を設定すれば、空白セルを飛ばします。

  • transpose (bool, default False) -- True を設定すれば、行と列を入れ替えます。」

戻り値

戻り値の型

None

property raw_value

xlwingsのデータ クリーニング/変換をせずに、エンジン(pywin32 または appscript)から直接値を取得または設定します。速度が問題になるときには役立つかもしれませんがエンジンに依存するため、クロスプラットフォームの互換性は失われる可能性があります。

resize(row_size=None, column_size=None)

指定したRangeをリサイズします

パラメータ
  • row_size (int > 0) -- 新しいRangeの行数(Noneの場合、行数は変化しません)。

  • column_size (int > 0) -- 新しいRangeの列数(Noneの場合、列数は変化しません)。

戻り値

Range object

戻り値の型

Range

バージョン 0.3.0 で追加.

property row

指定したrangeの最初の行番号を返します。読み取り専用。

戻り値

戻り値の型

Integer

バージョン 0.3.5 で追加.

property row_height

Rangeの高さをポイント単位で取得または設定します。Range内のすべての高さが同じ場合は、その高さを返します。 Rangeの高さが異なる場合、Noneを返します。

row_heightは次の範囲内でなければなりません: 0 <= row_height <= 409.5

注:Rangeがワークシートの使用範囲外であり、Range内の高さが異なる場合、最初の高さを返します。

戻り値

戻り値の型

float

バージョン 0.4.0 で追加.

property rows

指定したRangeに含まれるrowの集合を表す RangeRows オブジェクトを返します。

バージョン 0.9.0 で追加.

select()

Rangeを選択します。selectはアクティブ ワークブックでのみ機能します。

バージョン 0.9.0 で追加.

property shape

Rangeの次元を表すタプル

バージョン 0.3.0 で追加.

property sheet

Rangeが属するSheetオブジェクトを返します。

バージョン 0.9.0 で追加.

property size

Rangeに含まれる要素数を返します。

バージョン 0.3.0 で追加.

property table

Rangeを含んでいるテーブル オブジェクトを返します。Rangeがテーブルに含まれない場合は None を返します。

バージョン 0.21.0 で追加.

to_png(path=None)

Exports the range as PNG picture.

パラメータ
  • path (str or path-like, default None) -- Path where you want to store the picture. Defaults to the name of the range in the same directory as the Excel file if the Excel file is stored and to the current working directory otherwise.

  • versionadded: (.) -- 0.24.8:

property top

1行目の上端からrangeの上端までの距離をポイント単位で返します。読み取り専用。

戻り値

戻り値の型

float

バージョン 0.6.0 で追加.

unmerge()

結合セルを単独のセルに分割します。

property value

Gets and sets the values for the given Range. See see xlwings.Range.options() about how to set options, e.g. to transform it into a DataFrame or how to set a chunksize.

戻り値

object

戻り値の型

戻り値のオブジェクトは、使用したコンバーターに依存します。xlwings.Range.options() を参照。

property width

幅をポイント単位で返します。読み取り専用。

戻り値

戻り値の型

float

バージョン 0.4.0 で追加.

property wrap_text

Returns True if the wrap_text property is enabled and False if it's disabled. If not all cells have the same value in a range, on Windows it returns None and on macOS False.

バージョン 0.23.2 で追加.

RangeRows

class xlwings.RangeRows(rng)

Rangeの行の集合を表します。このクラスを直接生成しないでください。代わりに Range.rows を使用してください。

import xlwings as xw

rng = xw.Range('A1:C4')

assert len(rng.rows) == 4  # or rng.rows.count

rng.rows[0].value = 'a'

assert rng.rows[2] == xw.Range('A3:C3')
assert rng.rows(2) == xw.Range('A2:C2')

for r in rng.rows:
    print(r.address)
autofit()

行の高さを自動調整します。

property count

行の数を返します。

バージョン 0.9.0 で追加.

RangeColumns

class xlwings.RangeColumns(rng)

Rangeの列の集合を表します。このクラスを直接生成しないでください。代わりに Range.columns を使用してください。

import xlwings as xw

rng = xw.Range('A1:C4')

assert len(rng.columns) == 3  # or rng.columns.count

rng.columns[0].value = 'a'

assert rng.columns[2] == xw.Range('C1:C4')
assert rng.columns(2) == xw.Range('B1:B4')

for c in rng.columns:
    print(c.address)
autofit()

列の幅を自動調整します。

property count

列の数を返します。

バージョン 0.9.0 で追加.

Shapes

class xlwings.main.Shapes(impl)

指定したシート内のすべての shape オブジェクトのコレクション:

>>> import xlwings as xw
>>> xw.books['Book1'].sheets[0].shapes
Shapes([<Shape 'Oval 1' in <Sheet [Book1]Sheet1>>, <Shape 'Rectangle 1' in <Sheet [Book1]Sheet1>>])

バージョン 0.9.0 で追加.

property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

property count

コレクションに含まれるオブジェクトの数を返します。

Shape

class xlwings.Shape(*args, **options)

Shapeオブジェクトは shapes コレクションのメンバーです:

>>> import xlwings as xw
>>> sht = xw.books['Book1'].sheets[0]
>>> sht.shapes[0]  # or sht.shapes['ShapeName']
<Shape 'Rectangle 1' in <Sheet [Book1]Sheet1>>

バージョン 0.9.0 で変更.

activate()

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

バージョン 0.5.0 で追加.

property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

バージョン 0.19.2 で追加.

delete()

Shapeを削除します。

バージョン 0.5.0 で追加.

property height

Shapeの高さを表すポイント単位の数値を取得または設定します。

バージョン 0.5.0 で追加.

property left

Shapeの水平位置を表すポイント単位の数値を取得または設定します。

バージョン 0.5.0 で追加.

property name

Shapeの名前を取得または設定します。

バージョン 0.5.0 で追加.

property parent

Shapeの親オブジェクトを返します。

バージョン 0.9.0 で追加.

scale_height(factor, relative_to_original_size=False, scale='scale_from_top_left')
factorfloat

例えば、1.5なら150%に拡大します。

relative_to_original_sizebool, optional

False の場合、現在の高さからの相対的な大きさで拡大縮小します (デフォルト)。True は図またはOLE objectでなければなりません。

scalestr, optional

scale_from_top_left (デフォルト)、 scale_from_bottom_rightscale_from_middle のいずれか。

バージョン 0.19.2 で追加.

scale_width(factor, relative_to_original_size=False, scale='scale_from_top_left')
factorfloat

例えば、1.5なら150%に拡大します。

relative_to_original_sizebool, optional

False の場合、現在の幅からの相対的な大きさで拡大縮小します (デフォルト)。True は図またはOLE objectでなければなりません。

scalestr, optional

scale_from_top_left (デフォルト)、 scale_from_bottom_rightscale_from_middle のいずれか。

バージョン 0.19.2 で追加.

property text

Shapeのテキストを取得または設定します。

バージョン 0.21.4 で追加.

property top

Shapeの垂直位置を表すポイント単位の数値を取得または設定します。

バージョン 0.5.0 で追加.

property type

Shapeの種類を返します。

バージョン 0.9.0 で追加.

property width

Shapeの幅を表すポイント単位の数値を取得または設定します。

バージョン 0.5.0 で追加.

Charts

class xlwings.main.Charts(impl)

指定したシート内のすべての chart オブジェクトのコレクション:

>>> import xlwings as xw
>>> xw.books['Book1'].sheets[0].charts
Charts([<Chart 'Chart 1' in <Sheet [Book1]Sheet1>>, <Chart 'Chart 1' in <Sheet [Book1]Sheet1>>])

バージョン 0.9.0 で追加.

add(left=0, top=0, width=355, height=211)

指定したシートに新しいChartを作成します。

パラメータ
  • left (float, default 0) -- 左位置(ポイント単位)

  • top (float, default 0) -- 上端位置(ポイント単位)

  • width (float, default 355) -- 幅(ポイント単位)

  • height (float, default 211) -- 高さ(ポイント単位)

戻り値

戻り値の型

Chart

>>> import xlwings as xw
>>> sht = xw.Book().sheets[0]
>>> sht.range('A1').value = [['Foo1', 'Foo2'], [1, 2]]
>>> chart = sht.charts.add()
>>> chart.set_source_data(sht.range('A1').expand())
>>> chart.chart_type = 'line'
>>> chart.name
'Chart1'
property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

property count

コレクションに含まれるオブジェクトの数を返します。

Chart

class xlwings.Chart(name_or_index=None, impl=None)

Chartオブジェクトは charts コレクションのメンバーです:

>>> import xlwings as xw
>>> sht = xw.books['Book1'].sheets[0]
>>> sht.charts[0]  # or sht.charts['ChartName']
<Chart 'Chart 1' in <Sheet [Book1]Sheet1>>
property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

バージョン 0.9.0 で追加.

property chart_type

Chartの種類を取得または設定します。利用可能なチャート タイプは次の通り:

3d_area, 3d_area_stacked, 3d_area_stacked_100, 3d_bar_clustered, 3d_bar_stacked, 3d_bar_stacked_100, 3d_column, 3d_column_clustered, 3d_column_stacked, 3d_column_stacked_100, 3d_line, 3d_pie, 3d_pie_exploded, area, area_stacked, area_stacked_100, bar_clustered, bar_of_pie, bar_stacked, bar_stacked_100, bubble, bubble_3d_effect, column_clustered, column_stacked, column_stacked_100, combination, cone_bar_clustered, cone_bar_stacked, cone_bar_stacked_100, cone_col, cone_col_clustered, cone_col_stacked, cone_col_stacked_100, cylinder_bar_clustered, cylinder_bar_stacked, cylinder_bar_stacked_100, cylinder_col, cylinder_col_clustered, cylinder_col_stacked, cylinder_col_stacked_100, doughnut, doughnut_exploded, line, line_markers, line_markers_stacked, line_markers_stacked_100, line_stacked, line_stacked_100, pie, pie_exploded, pie_of_pie, pyramid_bar_clustered, pyramid_bar_stacked, pyramid_bar_stacked_100, pyramid_col, pyramid_col_clustered, pyramid_col_stacked, pyramid_col_stacked_100, radar, radar_filled, radar_markers, stock_hlc, stock_ohlc, stock_vhlc, stock_vohlc, surface, surface_top_view, surface_top_view_wireframe, surface_wireframe, xy_scatter, xy_scatter_lines, xy_scatter_lines_no_markers, xy_scatter_smooth, xy_scatter_smooth_no_markers

バージョン 0.1.1 で追加.

delete()

Chartを削除します。

property height

Chartの高さを表すポイント単位の数値を取得または設定します。

property left

Chartの水平位置を表すポイント単位の数値を取得または設定します。

property name

Chartの名前を取得または設定します。

property parent

Chartの親オブジェクトを返します。

バージョン 0.9.0 で追加.

set_source_data(source)

Chartのデータソース範囲を設定します。

パラメータ

source (Range) -- Range object, e.g. xw.books['Book1'].sheets[0].range('A1')

to_png(path=None)

Exports the chart as PNG picture.

パラメータ
  • path (str or path-like, default None) -- Path where you want to store the picture. Defaults to the name of the chart in the same directory as the Excel file if the Excel file is stored and to the current working directory otherwise.

  • versionadded: (.) -- 0.24.8:

property top

Chartの垂直位置を表すポイント単位の数値を取得または設定します。

property width

Chartの幅を表すポイント単位の数値を取得または設定します。

Pictures

class xlwings.main.Pictures(impl)

指定したシート内のすべての picture オブジェクトのコレクション:

>>> import xlwings as xw
>>> xw.books['Book1'].sheets[0].pictures
Pictures([<Picture 'Picture 1' in <Sheet [Book1]Sheet1>>, <Picture 'Picture 2' in <Sheet [Book1]Sheet1>>])

バージョン 0.9.0 で追加.

add(image, link_to_file=False, save_with_document=True, left=None, top=None, width=None, height=None, name=None, update=False, scale=None, format=None, anchor=None)

指定したシートにPictureを追加します。

パラメータ
  • image (str or path-like object or matplotlib.figure.Figure) -- ファイルパスまたはMatplotlibのFigureオブジェクト。

  • left (float, default None) -- Left position in points, defaults to 0. If you use top/left, you must not provide a value for anchor.

  • top (float, default None) -- Top position in points, defaults to 0. If you use top/left, you must not provide a value for anchor.

  • width (float, default None) -- Width in points. Defaults to original width.

  • height (float, default None) -- Height in points. Defaults to original height.

  • name (str, default None) -- ExcelのPictureの名前。指定しなければ、'Picture 1'のようなExcelの標準の名前になります。。

  • update (bool, default False) -- 同じ名前の既存のPictureを置き換えます。 name が設定されていなければなりません。

  • scale (float, default None) -- Scales your picture by the provided factor.

  • format (str, default None) -- Only used if image is a Matplotlib or Plotly plot. By default, the plot is inserted in the "png" format, but you may want to change this to a vector-based format like "svg" on Windows (may require Microsoft 365) or "eps" on macOS for better print quality. If you use 'vector', it will be using 'svg' on Windows and 'eps' on macOS. To find out which formats your version of Excel supports, see: https://support.microsoft.com/en-us/topic/support-for-eps-images-has-been-turned-off-in-office-a069d664-4bcf-415e-a1b5-cbb0c334a840

  • anchor (xw.Range, default None) --

    The xlwings Range object of where you want to insert the picture. If you use anchor, you must not provide values for top/left.

    バージョン 0.24.3 で追加.

戻り値

戻り値の型

Picture

  1. Picture

>>> import xlwings as xw
>>> sht = xw.Book().sheets[0]
>>> sht.pictures.add(r'C:\path\to\file.png')
<Picture 'Picture 1' in <Sheet [Book1]Sheet1>>
  1. Matplotlib

>>> import matplotlib.pyplot as plt
>>> fig = plt.figure()
>>> plt.plot([1, 2, 3, 4, 5])
>>> sht.pictures.add(fig, name='MyPlot', update=True)
<Picture 'MyPlot' in <Sheet [Book1]Sheet1>>
property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

property count

コレクションに含まれるオブジェクトの数を返します。

Picture

class xlwings.Picture(impl=None)

Pictureオブジェクトは pictures コレクションのメンバーです:

>>> import xlwings as xw
>>> sht = xw.books['Book1'].sheets[0]
>>> sht.pictures[0]  # or sht.charts['PictureName']
<Picture 'Picture 1' in <Sheet [Book1]Sheet1>>

バージョン 0.9.0 で変更.

property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

バージョン 0.9.0 で追加.

delete()

Picureを削除します。

バージョン 0.5.0 で追加.

property height

Pictureの高さを表すポイント単位の数値を取得または設定します。

バージョン 0.5.0 で追加.

property left

Pictureの水平位置を表すポイント単位の数値を取得または設定します。

バージョン 0.5.0 で追加.

property lock_aspect_ratio

True will keep the original proportion, False will allow you to change height and width independently of each other (read/write).

バージョン 0.24.0 で追加.

property name

Picrtureの名前を取得または設定します。

バージョン 0.5.0 で追加.

property parent

Pictureの親オブジェクトを返します。

バージョン 0.9.0 で追加.

property top

Pictureの垂直位置を表すポイント単位の数値を取得または設定します。

バージョン 0.5.0 で追加.

update(image, format=None)

既存のPictureを新しいPictureで置き換えます。既存のPictureのアトリビュートは新しいPictureに引き継がれます。

パラメータ

image (str or path-like object or matplotlib.figure.Figure) -- ファイルパスまたはMatplotlibのFigureオブジェクト。

バージョン 0.5.0 で追加.

property width

Pictureの幅を表すポイント単位の数値を取得または設定します。

バージョン 0.5.0 で追加.

Names

class xlwings.main.Names(impl)

指定したシート内のすべての name オブジェクトのコレクション:

>>> import xlwings as xw
>>> sht = xw.books['Book1'].sheets[0]
>>> sht.names
[<Name 'MyName': =Sheet1!$A$3>]

バージョン 0.9.0 で追加.

add(name, refers_to)

セル範囲に新しい名前を定義します。

パラメータ
  • name (str) -- 名前として使う文字列を指定します。名前にスペースを含めることはできません。またセルを参照することもできません。

  • refers_to (str) -- A1形式で名前の参照先を指定します。

戻り値

戻り値の型

Name

バージョン 0.9.0 で追加.

property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

バージョン 0.9.0 で追加.

property count

コレクションに含まれるオブジェクトの数を返します。

Name

class xlwings.Name(impl)

Pictureオブジェクトは names コレクションのメンバーです:

>>> import xlwings as xw
>>> sht = xw.books['Book1'].sheets[0]
>>> sht.names[0]  # or sht.names['MyName']
<Name 'MyName': =Sheet1!$A$3>

バージョン 0.9.0 で追加.

property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

バージョン 0.9.0 で追加.

delete()

名前を削除します。

バージョン 0.9.0 で追加.

property name

Nameオブジェクトの名前を取得または設定します。

バージョン 0.9.0 で追加.

property refers_to

名前の参照先を定義する数式を取得または設定します。数式はA1形式でイコールで始まります。

バージョン 0.9.0 で追加.

property refers_to_range

Nameオブジェクトが参照するRangeオブジェクトを返します。

バージョン 0.9.0 で追加.

Note

class xlwings.main.Note(impl)
property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

バージョン 0.24.2 で追加.

delete()

Delete the note.

バージョン 0.24.2 で追加.

property text

Gets or sets the text of a note. Keep in mind that the note must already exist!

>>> sheet = xw.Book(...).sheets[0]
>>> sheet['A1'].note.text = 'mynote'
>>> sheet['A1'].note.text
>>> 'mynote'

バージョン 0.24.2 で追加.

Tables

class xlwings.main.Tables(impl)

指定したシート内のすべての table オブジェクトのコレクション:

>>> import xlwings as xw
>>> xw.books['Book1'].sheets[0].tables
Tables([<Table 'Table1' in <Sheet [Book11]Sheet1>>, <Table 'Table2' in <Sheet [Book11]Sheet1>>])

バージョン 0.21.0 で追加.

add(source=None, name=None, source_type=None, link_source=None, has_headers=True, destination=None, table_style_name='TableStyleMedium2')

指定したシートに新しいTableを作成します。

パラメータ
  • source (xlwings range, default None) -- データ ソースを表すxlwingsのrangeオブジェクト。

  • name (str, default None) -- テーブルの名前。デフォルトはExcelが自動生成する名前。

  • source_type (str, default None) -- 現在のところ、デフォルトは xlSrcRange 。つまり、xlwingsのrangeオブジェクトの使用を前提とするものです。他のオプションは使用できません。

  • link_source (bool, default None) -- source_typexlSrcExternal の時に使用するものなので、現在時点では実装されていません。

  • has_headers (bool or str, default True) -- インポートしたデータに列ラベルが含まれるかどうかを表します。デフォルトは True 。可能な値: TrueFAlse'guess'

  • destination (xlwings range, default None) -- source_typexlSrcExternal の時に使用するものなので、現在時点では実装されていません。

  • table_style_name (str, default 'TableStyleMedium2') -- 可能な文字列: 'TableStyleLightN'' (Nは1から21のいずれか)、 'TableStyleMediumN' (Nは1から28のいずれか)、 'TableStyleDarkN' (Nは1から11のいずれか)

戻り値

戻り値の型

Table

>>> import xlwings as xw
>>> sheet = xw.Book().sheets[0]
>>> sheet['A1'].value = [['a', 'b'], [1, 2]]
>>> table = sheet.tables.add(source=sheet['A1'].expand(), name='MyTable')
>>> table
<Table 'MyTable' in <Sheet [Book1]Sheet1>>

Table

class xlwings.main.Table(*args, **options)

tableオブジェクトは tables コレクションのメンバーです:

>>> import xlwings as xw
>>> sht = xw.books['Book1'].sheets[0]
>>> sht.tables[0]  # or sht.tables['TableName']
<Table 'Table 1' in <Sheet [Book1]Sheet1>>

バージョン 0.21.0 で追加.

property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

property data_body_range

ヘッダー行を除く、値のrangeを表すxlwingsのrangeオブジェクトを返します。

property display_name

指定したTableオブジェクトの表示名を取得または設定します。

property header_row_range

ヘッダーのrangeを表すxlwingsのrangeオブジェクトを返します。

property insert_row_range

データが挿入される行を表すxlwingsのrangeオブジェクトを返します。このメソッドはテーブルが空の場合のみ利用できます。それ以外の場合は None を返します。

property name

Tableの名前を取得または設定します。

property parent

tableの親オブジェクトを返します。

property range

tableのxlwingsのrangeオブジェクトを返します。

resize(range)

Resize a Table by providing an xlwings range object

バージョン 0.24.4 で追加.

property show_autofilter

オートフィルターのオン/オフを True または False で切り替える(読み取り/書き込み boolean)。

property show_headers

ヘッダーの表示または非表示(読み取り/書き込み)

property show_table_style_column_stripes

列方向ストライプのテーブル スタイルが使用されているかを取得または設定します(読み取り/書き込み boolean)。

property show_table_style_first_column

最初の列が書式設定されているかを取得または設定します(読み取り/書き込み boolean)。

property show_table_style_last_column

最後の列が書式設定されているかを取得または設定します(読み取り/書き込み boolean)。

property show_table_style_row_stripes

行方向ストライプのテーブル スタイルが使用されているかを取得または設定します(読み取り/書き込み boolean)。

property show_totals

集計行の表示/非表示のブール値を取得または設定します。

property table_style

テーブル スタイルを取得または設定します。設定可能な値は Tables.add を参照。

property totals_row_range

集計行を表すxlwingsのrangeオブジェクトを返します。

update(data, index=True)

引数dataでExcelテーブルを更新します。現在のところ、DataFrameのみ利用できます。

バージョン 0.24.0 で変更.

パラメータ
  • data (pandas DataFrame) -- Currently restricted to pandas DataFrames.

  • index (bool, default True) -- Whether or not the index of a pandas DataFrame should be written to the Excel table.

戻り値

戻り値の型

Table

import pandas as pd
import xlwings as xw

sheet = xw.Book('Book1.xlsx').sheets[0]
table_name = 'mytable'

# Sample DataFrame
nrows, ncols = 3, 3
df = pd.DataFrame(data=nrows * [ncols * ['test']],
                  columns=['col ' + str(i) for i in range(ncols)])

# Hide the index, then insert a new table if it doesn't exist yet,
# otherwise update the existing one
df = df.set_index('col 0')
if table_name in [table.name for table in sheet.tables]:
    sheet.tables[table_name].update(df)
else:
    mytable = sheet.tables.add(source=sheet['A1'], name=table_name).update(df)

Font

class xlwings.main.Font(impl)

The font object can be accessed as an attribute of the range or shape object.

  • mysheet['A1'].font

  • mysheet.shapes[0].font

バージョン 0.23.0 で追加.

property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

バージョン 0.23.0 で追加.

property bold

Returns or sets the bold property (boolean).

>>> sheet['A1'].font.bold = True
>>> sheet['A1'].font.bold
True

バージョン 0.23.0 で追加.

property color

Returns or sets the color property (tuple).

>>> sheet['A1'].font.color = (255, 0, 0)  # or '#ff0000'
>>> sheet['A1'].font.color
(255, 0, 0)

バージョン 0.23.0 で追加.

property italic

Returns or sets the italic property (boolean).

>>> sheet['A1'].font.italic = True
>>> sheet['A1'].font.italic
True

バージョン 0.23.0 で追加.

property name

Returns or sets the name of the font (str).

>>> sheet['A1'].font.name = 'Calibri'
>>> sheet['A1'].font.name
Calibri

バージョン 0.23.0 で追加.

property size

Returns or sets the size (float).

>>> sheet['A1'].font.size = 13
>>> sheet['A1'].font.size
13

バージョン 0.23.0 で追加.

Characters

class xlwings.main.Characters(impl)

The characters object can be accessed as an attribute of the range or shape object.

  • mysheet['A1'].characters

  • mysheet.shapes[0].characters

注釈

On macOS, characters are currently not supported due to bugs/lack of support in AppleScript.

バージョン 0.23.0 で追加.

property api

使用しているエンジンのネイティブ オブジェクト(pywin32 オブジェクトまたは appscript オブジェクト)を返します。

バージョン 0.23.0 で追加.

property font

Returns or sets the text property of a characters object.

>>> sheet['A1'].characters[1:3].font.bold = True
>>> sheet['A1'].characters[1:3].font.bold
True

バージョン 0.23.0 で追加.

property text

Returns or sets the text property of a characters object.

>>> sheet['A1'].value = 'Python'
>>> sheet['A1'].characters[:3].text
Pyt

バージョン 0.23.0 で追加.

Markdown

MarkdownStyle

UDF デコレーター

xlwings.func(category='xlwings', volatile=False, call_in_wizard=True)

xlwings.func でデコレートした関数は、"Import Python UDFs"実行時にExcelの Function としてインポートされます。

categoryint or str, default "xlwings"

1から14はビルトイン カテゴリーです。ユーザー定義 カテゴリーは文字列を使ってください。

バージョン 0.10.3 で追加.

volatilebool, default False

ユーザー定義関数をvolatileとします。volatileな関数はワークシートのいずれかのセルで計算が行われるたびに再計算されます。volatileではない関数は引数が変化したときのみ再計算されます。

バージョン 0.10.3 で追加.

call_in_wizardbool, default True

Falseを設定すれば、関数ウィザードでの関数呼び出しを抑制します。

バージョン 0.10.3 で追加.

xlwings.sub()

xlwings.sub でデコレートした関数は、"Import Python UDFs"実行時にExcelの Sub (つまりマクロ) としてインポートされます。

xlwings.arg(arg, convert=None, **options)

コンバーターおよびオプションを引数に適用します。 Range.options() を参照。

例:

x を2次元のnumpy arrayに変換します:

import xlwings as xw
import numpy as np

@xw.func
@xw.arg('x', np.array, ndim=2)
def add_one(x):
    return x + 1
xlwings.ret(convert=None, **options)

コンバーターおよびオプションを戻り値に適用します。 Range.options() を参照。

  1. 戻り値のDataFrameからインデックスとヘッダーを除去:

import pandas as pd

@xw.func
@xw.ret(index=False, header=False)
def get_dataframe(n, m):
    return pd.DataFrame(np.arange(n * m).reshape((n, m)))
  1. 動的配列:

注釈

もしExcelが新しいネイティブな動的配列に対応済みなら、特別なことはなにもしないでください。そして expand デコレーターを使用すべきではありません。Excelが対応しているか調べるには、=UNIQUE() 関数が利用可能かをみてください。ネイティブな動的配列は2018年9月のOffice 365 インサイダー ファストで導入されました。

expand='table' を使えばUDFが動的配列になります。現在のところ、volatileな関数は動的配列の引数に使えません。 例えば、 =TODAY() は動的配列の一部として使えません。また、動的配列は空行や空列が下や右になければなりませんし、既に存在するデータを警告なしで上書きします。

通常のExcel配列数式とは異なり、動的配列は通常の関数同様、単独のセルから使用され、戻り値に応じて自動的に拡張されます:

import xlwings as xw
import numpy as np

@xw.func
@xw.ret(expand='table')
def dynamic_array(n, m):
    return np.arange(n * m).reshape((n, m))

バージョン 0.10.0 で追加.

Reports