コンバーターおよびオプション¶

コンバーターはv0.7.0で導入された機能で、Excelのセル範囲やその値の 読み込み 、書き込み 時の変換方法を定義するものです。この機能は、xlwings.Range オブジェクトと User Defined Functions (UDF)の両方で同じように利用できます。

コンバーターを使うには、 Range オブジェクトの場合は options メソッドで、UDFの場合は @xw.arg と @xw.ret デコレーターで、明示的に指定します。コンバーターの指定が無ければ、読み込み時にはデフォルトコンバーターが適用されます。書き込み時には、Excelに書きこまれるオブジェクトの型に応じて、xlwingsは（可能であれば）適切なコンバーターを自動的に適用します。型に合うコンバーターが無ければ、デフォルトコンバーターにフォールバックします。

以下、全てのサンプルコードは次のインポートを前提としています:

>>> import xlwings as xw

シンタックス:

Action	Range objects	UDFs
読み込み	`myrange.options(convert=None, **kwargs).value`	`@arg('x', convert=None, **kwargs)`
書き込み	`myrange.options(convert=None, **kwargs).value = myvalue`	`@ret(convert=None, **kwargs)`

注釈

キーワード引数(kwargs)は、特定のコンバーターやデフォルトコンバーターで使用されます。例えば、デフォルトコンバーターの numbers オプションやDataFrame コンバーターの index オプションの設定方法は以下のとおりです:

myrange.options(pd.DataFrame, index=False, numbers=int).value

デフォルトコンバーター¶

If no options are set, the following default conversions are applied when accessing Range.value:

Numbers -> floats
Text -> str
Date and/or time -> datetime
TRUE or FALSE -> bool
Empty cell -> None
Windows only: Currency -> Decimal, truncated to 4 decimals

Columns/rows are read in as lists, e.g. [None, 1.0, 'a string'] and 2d cell ranges are read in as list of lists, e.g. [[None, 1.0, 'a string'], [None, 2.0, 'another string']].

以下のオプションを設定できます:

ndim¶

セル範囲の形に関わらず、強制的に値の次元を1か2にします:

>>> import xlwings as xw
>>> sheet = xw.Book().sheets[0]
>>> sheet['A1'].value = [[1, 2], [3, 4]]
>>> sheet['A1'].value
1.0
>>> sheet['A1'].options(ndim=1).value
[1.0]
>>> sheet['A1'].options(ndim=2).value
[[1.0]]
>>> sheet['A1:A2'].value
[1.0 3.0]
>>> sheet['A1:A2'].options(ndim=2).value
[[1.0], [3.0]]

To preserve the vertical orientation of columns, use ndim="natural". This returns scalars for single cells, 1D lists for horizontal ranges, and 2D lists for vertical or multi-row ranges:

>>> sheet['A1'].value = 1
>>> sheet['A1'].options(ndim="natural").value
1.0
>>> sheet['A1'].value = ["Industry", "Country", "Employees", "Revenue"]
>>> sheet['A1:D1'].options(ndim="natural").value
['Industry', 'Country', 'Employees', 'Revenue']
>>> sheet['A1'].value = [["3M"], ["AbbVie"], ["Apple"]]
>>> sheet['A1:A3'].options(ndim="natural").value  # Key difference to default
[['3M'], ['AbbVie'], ['Apple']]
>>> sheet['A1'].value = [[1, 2, 3], [4, 5, 6]]
>>> sheet['A1:C2'].options(ndim="natural").value
[[1, 2, 3], [4, 5, 6]]

numbers¶

デフォルトでは数字のセルは float として読み込まれますが、 int に変更できます:

>>> sheet['A1'].value = 1
>>> sheet['A1'].value
1.0
>>> sheet['A1'].options(numbers=int).value
1

それ以外にも、1つのfloat引数を受け取る関数や型を設定することもできます。

UDFでの使用例を以下に示します:

@xw.func
@xw.arg('x', numbers=int)
def myfunction(x):
    # all numbers in x arrive as int
    return x

注釈

Excel delivers all numbers as floats in the interactive mode, which is the reason why the int converter rounds numbers first before turning them into integers. Otherwise it could happen that e.g., 5 might be returned as 4 in case it is represented as a floating point number that is slightly smaller than 5. Should you require Python's original int in your converter, use raw int` instead.

dates¶

デフォルトでは、日付のセルは datetime.datetime として読み込まれますが、datetime.date に変更することもできます。

Range:

>>> import datetime as dt
>>> sheet['A1'].options(dates=dt.date).value

UDFs (decorator):
```
@xw.arg('x', dates=dt.date)
```

それ以外にも、 datetime.datetime と同じキーワード引数を受け取る任意の関数や型を指定できます。例:

>>> my_date_handler = lambda year, month, day, **kwargs: "%04i-%02i-%02i" % (year, month, day)
>>> sheet['A1'].options(dates=my_date_handler).value
'2017-02-20'

empty¶

空白のセルはデフォルトでは None に変換されますが、次のように変更できます:

Range:

>>> sheet['A1'].options(empty='NA').value

UDFs (decorator):
```
@xw.arg('x', empty='NA')
```

transpose¶

transposeは読み込み/書き込み時に機能し、例えばリストを列方向に書き込めます:

Range: sheet['A1'].options(transpose=True).value = [1, 2, 3]

UDFs:

@xw.arg('x', transpose=True)
@xw.ret(transpose=True)
def myfunction(x):
    # x will be returned unchanged as transposed both when reading and writing
    return x

expand¶

これはRangeの table, vertical, horizontal プロパティと同じように機能しますが、Rangeの値を取得するときのみ評価されます:

>>> import xlwings as xw
>>> sheet = xw.Book().sheets[0]
>>> sheet['A1'].value = [[1,2], [3,4]]
>>> range1 = sheet['A1'].expand()
>>> range2 = sheet['A1'].options(expand='table')
>>> range1.value
[[1.0, 2.0], [3.0, 4.0]]
>>> range2.value
[[1.0, 2.0], [3.0, 4.0]]
>>> sheet['A3'].value = [5, 6]
>>> range1.value
[[1.0, 2.0], [3.0, 4.0]]
>>> range2.value
[[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]]

注釈

expand メソッドが使えるのは、 Range オブジェクトのみです。UDFは呼び出し元のセルの操作のみしかできないため、UDFでは expand メソッドを使えません。

chunksize¶

When you read and write from or to big ranges, you may have to chunk them or you will hit a timeout or a memory error. The ideal chunksize will depend on your system and size of the array, so you will have to try out a few different chunksizes to find one that works well:

import pandas as pd
import numpy as np
sheet = xw.Book().sheets[0]
data = np.arange(75_000 * 20).reshape(75_000, 20)
df = pd.DataFrame(data=data)
sheet['A1'].options(chunksize=10_000).value = df

And the same for reading:

# As DataFrame
df = sheet['A1'].expand().options(pd.DataFrame, chunksize=10_000).value
# As list of list
df = sheet['A1'].expand().options(chunksize=10_000).value

err_to_str¶

Added in version 0.28.0.

If True, will include cell errors such as #N/A as strings. By default, they will be converted to None.

formatter¶

Added in version 0.28.1.

注釈

You can't use formatters with Excel tables.

The formatter option accepts the name of a function. The function will be called after writing the values to Excel and allows you to easily style the range in a very flexible way. How it works is best shown with a little example:

import pandas as pd
import xlwings as xw

sheet = xw.Book().sheets[0]

def table(rng: xw.Range, df: pd.DataFrame):
    """This is the formatter function"""
    # Header
    rng[0, :].color = "#A9D08E"

    # Rows
    for ix, row in enumerate(rng.rows[1:]):
        if ix % 2 == 0:
            row.color = "#D0CECE"  # Even rows

    # Columns
    for ix, col in enumerate(df.columns):
        if "two" in col:
            rng[1:, ix].number_format = "0.0%"


df = pd.DataFrame(data={"one": [1, 2, 3, 4], "two": [5, 6, 7, 8]})
sheet["A1"].options(formatter=table, index=False).value = df

Running this code will format the DataFrame like this:

The formatter's signature is: def myformatter(myrange, myvalues) where myrange corresponds to the range where myvalues are written to. myvalues is simply what you assign to the value property in the last line of the example. Since we're using this with a DataFrame, it makes sense to name the argument accordingly and using type hints will help your editor with auto-completion. If you would use a nested list instead of a DataFrame, you would write something like this instead:

def table(rng: xw.Range, values: list[list]):

ビルトインコンバーター¶

xlwingsはビルトインコンバーターを提供しており、これらは、辞書、Numpy arrays, Pandas Series, DataFrame への型変換に対応しています。これらはデフォルトコンバーターを基にしているため、多くのケースで上記のオプションも利用できます（例えば辞書の場合の ndim のように意味がないこともありますが）。

これら以外の型に対応するカスタムコンバーターの作成や登録もできます（後述）。

以下のサンプルは xlwings.Range オブジェクトとUDFの両方で使えますが、いずれかで説明します。

辞書コンバーター¶

辞書コンバーターはExcelの2つの列を辞書に変換します。もしデータが行方向なら、 transpose を使ってください:

>>> sheet = xw.sheets.active
>>> sheet['A1:B2'].options(dict).value
{'a': 1.0, 'b': 2.0}
>>> sheet['A4:B5'].options(dict, transpose=True).value
{'a': 1.0, 'b': 2.0}

Note: dict の代わりに、 collections の OrderedDict も使えます。

Tuple converter¶

Get the values as (nested) tuples instead of (nested) lists. This can be helpful in connection with caching, as tuples are immutable and hashable.

>>> sheet = xw.sheets.active
>>> sheet['A1:B2'].options(tuple).value
(('a', 1.0), ('b', 2.0))

JSON converter¶

Read and write values as JSON-formatted strings. This is especially useful to interact with LLMs.

>>> sheet = xw.sheets.active
>>> sheet['A1:C2'].options("json").value
'[["2024-01-01T00:00:00", "text", true], [null, 42.0, false]]'

Numpy array コンバーター¶

options: dtype=None, copy=True, order=None, ndim=None

最初の3つのオプションは、直接 np.array() を使うときと同じように機能します。また、 ndim は先述のリスト（デフォルトコンバーター）と同様に機能し、numpyのスカラーや1次元配列、2次元配列を返します。

Example

>>> import numpy as np
>>> sheet = xw.Book().sheets[0]
>>> sheet['A1'].options(transpose=True).value = np.array([1, 2, 3])
>>> sheet['A1:A3'].options(np.array, ndim=2).value
array([[ 1.],
       [ 2.],
       [ 3.]])

Pandas Series コンバーター¶

options: dtype=None, copy=False, index=1, header=True

最初の2つのオプションは、直接 pd.Series を使うときと同じように機能します。Pandas Seriesは常に列方向への入出力を前提としているため、 ndim は機能しません。

index: int or Boolean: 読み込み時、Excel上のデータからインデックスとする列の数を設定します。

書き込み時、インデックスの有無を True か False かで設定します。
header: Boolean: 読み込み時、ExcelにインデックスまたはSeriesの名前がなければ、False を設定します。

書き込み時、インデックスやシリーズの名前の有無を、 True か False かで設定します。

index と header には、1 と True の両方を使えます。

例

>>> sheet = xw.Book().sheets[0]
>>> s = sheet['A1'].options(pd.Series, expand='table').value
>>> s
date
2001-01-01    1
2001-01-02    2
2001-01-03    3
2001-01-04    4
2001-01-05    5
2001-01-06    6
Name: series name, dtype: float64

Pandas DataFrame コンバーター¶

options: dtype=None, copy=False, index=1, header=1

最初の2つのオプションは、直接 pd.DataFrame() を使ったときと同じように機能します。Pandas DataFrameは自動的に ndim=2 として読み込むため、ndim は機能しません。

index: int or Boolean: 読み込み時、Excel上のデータからインデックスとする列の数を設定します。

書き込み時、インデックスの有無を True か False かで設定します。
header: int or Boolean: 読み込み時、Excel上のデータから列ヘッダーの数を設定します。

書き込み時、インデックスやシリーズの名前の有無を、 True か False かで設定します。

index と header には、1 と True の両方を使えます。

例

>>> sheet = xw.Book().sheets[0]
>>> df = sheet['A1:D5'].options(pd.DataFrame, header=2).value
>>> df
    a     b
    c  d  e
ix
10  1  2  3
20  4  5  6
30  7  8  9

# Writing back using the defaults:
>>> sheet['A1'].value = df

# Writing back and changing some of the options, e.g. getting rid of the index:
>>> sheet['B7'].options(index=False).value = df

The same sample for UDF (starting in cell A13 on screenshot) looks like this:

@xw.func
@xw.arg('x', pd.DataFrame, header=2)
@xw.ret(index=False)
def myfunction(x):
   # x is a DataFrame, do something with it
   return x

Polars DataFrame and Series converters¶

Polars DataFrames work almost the same as pandas DataFrames. But since polars DataFrames don't have an index and don't support MultiIndex headers, the index option isn't available and the header option only accepts True (default) or False.

Examples:

# This is a script example

import datetime as dt
import polars as pl
import xlwings as xw

df = pl.DataFrame(
    {
        "name": ["Alice Archer", "Ben Brown", "Chloe Cooper", "Daniel Donovan"],
        "birthdate": [
            dt.date(1997, 1, 10),
            dt.date(1985, 2, 15),
            dt.date(1983, 3, 22),
            dt.date(1981, 4, 30),
        ],
        "weight": [57.9, 72.5, 53.6, 83.1],
        "height": [1.56, 1.77, 1.65, 1.75],
    }
)

book = xw.Book()
sheet = book.sheets[0]
sheet["A1"].value = df  # writing
df_read = sheet["A1"].expand().options(pl.DataFrame).value  # reading

# This is a UDF example

import polars as pl

@xw.func
def myfunction(df: pl.DataFrame):
   # df is a polars DataFrame, do something with it
   return df

xw.Range コンバーターおよび 'raw' コンバーター¶

技術的には、これらは "コンバーターではありません"。

xlwings.Range オブジェクトに直接アクセスする必要がある場合、次のようにします:
```
@xw.func
@xw.arg('x', 'range')
def myfunction(x):
   return x.formula
```
これはxを xlwings.Range オブジェクト、つまり、コンバーターやオプションを何も適用せずに返します。
raw コンバーターは、基礎となるライブラリー（Windowsでは pywin32 、Macでは appscript ）に変換ぜずに値を渡します。つまり、不要なものの除去やクロスプラットフォーム用の調整がされていない値が作られます。効率化が必要な場合には、この方法が役に立つことがあるかもしれません。例:
```
>>> sheet['A1:B2'].value
[[1.0, 'text'], [datetime.datetime(2016, 2, 1, 0, 0), None]]

>>> sheet['A1:B2'].options('raw').value  # or sheet['A1:B2'].raw_value
((1.0, 'text'), (pywintypes.datetime(2016, 2, 1, 0, 0, tzinfo=TimeZoneInfo('GMT Standard Time', True)), None))
```

カスタムコンバーター¶

自身で作成したコンバーターを実装する手順は以下のとおりです:

xlwings.conversion.Converter を継承します。
read_value メソッドと write_value メソッドをスタティックメソッドまたはクラスメソッドで実装します:
- read_value では、 value はbase コンバーターの戻り値です: したがって、base が特定されなければ、デフォルトコンバーターのものになります。
- write_value では、 value はExcelに書き込まれるオリジナルのオブジェクトです。戻り値は、base コンバーターが受け取れる形式でなければなりません。base が特定されていなければ、デフォルトコンバーターの形式になります。
The options dictionary will contain all keyword arguments specified in the options method, e.g. when calling myrange.options(myoption='some value') or as specified in the @arg and @ret decorator when using UDFs. Here is the basic structure:
```
from xlwings.conversion import Converter

class MyConverter(Converter):

    @staticmethod
    def read_value(value, options):
        myoption = options.get('myoption', default_value)
        return_value = value  # Implement your conversion here
        return return_value

    @staticmethod
    def write_value(value, options):
        myoption = options.get('myoption', default_value)
        return_value = value  # Implement your conversion here
        return return_value
```
Optional: set a base converter (base expects a class name) to build on top of an existing converter, e.g. for the built-in ones: DictConverter, NumpyArrayConverter, PandasDataFrameConverter, PandasSeriesConverter
Optional: コンバーターを登録します: (a) 型を登録すれば、その型を書き込む際ののデフォルトコンバーターになります。そして/または (b) エイリアスを登録すれば、正確なクラス名ではなく、名前でコンバーターを指定できるようになります。

以下の例は理解の助けになるでしょう。ビルトイン DataFrame コンバーターを基に、nanを除去する機能を追加したDataFrame コンバーターを定義しています:

from xlwings.conversion import Converter, PandasDataFrameConverter

class DataFrameDropna(Converter):

    base = PandasDataFrameConverter

    @staticmethod
    def read_value(builtin_df, options):
        dropna = options.get('dropna', False)  # set default to False
        if dropna:
            converted_df = builtin_df.dropna()
        else:
            converted_df = builtin_df
        # This will arrive in Python when using the DataFrameDropna converter for reading
        return converted_df

    @staticmethod
    def write_value(df, options):
        dropna = options.get('dropna', False)
        if dropna:
            converted_df = df.dropna()
        else:
            converted_df = df
        # This will be passed to the built-in PandasDataFrameConverter when writing
        return converted_df

これらコンバーターの動作の違いを見てみましょう:

# Fire up a Workbook and create a sample DataFrame
sheet = xw.Book().sheets[0]
df = pd.DataFrame([[1.,10.],[2.,np.nan], [3., 30.]])

デフォルトのDataFrame コンバーター:

# Write
sheet['A1'].value = df

# Read
sheet['A1:C4'].options(pd.DataFrame).value

DataFrameDropna コンバーター:

# Write
sheet['A7'].options(DataFrameDropna, dropna=True).value = df

# Read
sheet['A1:C4'].options(DataFrameDropna, dropna=True).value

エイリアスの登録(optional):

DataFrameDropna.register('df_dropna')

# Write
sheet['A12'].options('df_dropna', dropna=True).value = df

# Read
sheet['A1:C4'].options('df_dropna', dropna=True).value

DataFrameDropnaを、DataFrameに対するデフォルトのコンバーターとして登録(optional):

DataFrameDropna.register(pd.DataFrame)

# Write
sheet['A13'].options(dropna=True).value = df

# Read
sheet['A1:C4'].options(pd.DataFrame, dropna=True).value

これらのサンプルはUDFでも同様に機能します。例:

@xw.func
@arg('x', DataFrameDropna, dropna=True)
@ret(DataFrameDropna, dropna=True)
def myfunction(x):
    # ...
    return x

注釈

Pythonオブジェクトは、複数の変換パイプラインのステージを経て、Excelに書き出されます。反対方向、つまり、Excel/COM オブジェクトがPythonに読み込まれる際も同様です。

内部的には、パイプラインは複数の Accessor クラスで定義されています。コンバーターは特別なAccessorで、デフォルトAccessorのパイプラインに特別なステージを追加することで、特定の型への/からの変換を行います。例えば、 PandasDataFrameConverter は、（デフォルトのAccessorが渡す）リストのリストからPandas DataFrameに変換する方法を定めています。

Converter クラスは、新しいコンバーターを簡単に作るための基本的な枠組みを提供します。もっと細かい操作が必要なら、直接 Accessor クラスを継承することもできますが、作業が大変になることに加え、現在のところドキュメント化もされていません。