Range¶

class Range(cell1=None, cell2=None, **options)¶

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

Arguments¶

cell1str or tuple or Range: 左上セルをA1表記、インデックスのタプル、xw.Rangeオブジェクトのいずれかで指定します。'A1:B2'のようにrangeオペレーター（コロンのこと）での指定も可。
cell2str or tuple or Range, default None: 左下セルをA1表記、インデックスのタプル、xw.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"]

add_hyperlink(address, text_to_display=None, screen_tip=None)¶

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

Arguments¶

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

Added in version 0.3.0.

property address¶: Returns a string value that represents the range reference. Use get_address() to be able to provide parameters.

Added in version 0.9.0.

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

Added in version 0.9.0.

autofill(destination, type_='fill_default')¶

Autofills the destination Range. Note that the destination Range must include the origin Range.

Arguments¶

destinationRange: The origin.
type_str, default "fill_default": One of the following strings: "fill_copy", "fill_days", "fill_default", "fill_formats", "fill_months", "fill_series", "fill_values", "fill_weekdays", "fill_years", "growth_trend", "linear_trend", "flash_fill

Added in version 0.30.1.

autofit()¶

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

To autofit only the width of the columns use myrange.columns.autofit()
To autofit only the height of the rows use myrange.rows.autofit()

バージョン 0.9.0 で変更.

clear()¶: Rangeの値と書式をクリアーします。

clear_contents()¶: Rangeの値をクリアーしますが、書式は保持します。

clear_formats()¶: Clears the format of a Range but leaves the content.

Added in version 0.26.2.

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.

Returns¶

RGB : tuple

例¶

>>> import xlwings as xw
>>> wb = xw.Book()
>>> sheet1 = xw.sheets[0]
>>> sheet1.range('A1').color = (255, 255, 255)  # or '#ffffff'
>>> sheet1.range('A2').color
(255, 255, 255)
>>> sheet1.range('A2').color = None
>>> sheet1.range('A2').color is None
True

Added in version 0.3.0.

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

Returns¶

Integer

Added in version 0.3.5.

property column_width¶

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

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

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

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

Returns¶

float

Added in version 0.4.0.

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

Added in version 0.9.0.

copy(destination=None)¶

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

Parameters¶

destinationxlwings.Range: xlwings Range to which the specified range will be copied. If omitted, the range is copied to the clipboard.

Returns¶

None

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

Copies the range to the clipboard as picture.

Parameters¶

appearancestr, default 'screen': Either 'screen' or 'printer'.
formatstr, default 'picture': Either 'picture' or 'bitmap'.

Added in version 0.24.8.

property count¶: セルの数を返します。

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

Returns¶

Range object

delete(shift=None)¶

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

Parameters¶

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

Returns¶

None

end(direction)¶

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

Parameters¶

direction : One of 'up', 'down', 'right', 'left'

例¶

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

Added in version 0.9.0.

expand(mode='table')¶

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

Parameters¶

modestr, default 'table': 'table' (=downとright)、 'down' 、 'right' のいずれか。

Returns¶

Range

例¶

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

Added in version 0.9.0.

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

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

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

Added in version 0.7.1.

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

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

Arguments¶

row_absolutebool, default True: Trueを設定すれば、アドレスの行部分を絶対参照で取得します。
column_absolutebool, default True: Trueを設定すれば、アドレスの列部分を絶対参照で取得します。
include_sheetnamebool, default False: Trueを設定すれば、アドレスにシート名が含まれます。external=Trueの場合、無視されます。
externalbool, default False: Trueを設定すれば、アドレスにワークブック名とシート名が含まれます。

Returns¶

str

例¶

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

Added in version 0.2.3.

property has_array¶: True if the range is part of a legacy CSE Array formula and False otherwise.

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

Returns¶

float

Added in version 0.4.0.

property hyperlink¶

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

例¶

>>> import xlwings as xw
>>> wb = xw.Book()
>>> sheet1 = wb.sheets[0]
>>> sheet1.range('A1').value
'www.xlwings.org'
>>> sheet1.range('A1').hyperlink
'http://www.xlwings.org'

Added in version 0.3.0.

insert(shift, copy_origin='format_from_left_or_above')¶

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

Parameters¶

shiftstr: Use right or down.
copy_originstr, default format_from_left_or_above: Use format_from_left_or_above or format_from_right_or_below. Note that copy_origin is only supported on Windows.

Returns¶

None

バージョン 0.30.3 で変更: shift is now a required argument.

property last_cell¶

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

Returns¶

Range

例¶

>>> import xlwings as xw
>>> wb = xw.Book()
>>> sheet1 = wb.sheets[0]
>>> myrange = sheet1.range('A1:E4')
>>> myrange.last_cell.row, myrange.last_cell.column
(4, 5)

Added in version 0.3.5.

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

Returns¶

float

Added in version 0.6.0.

merge(across=False)¶

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

Parameters¶

acrossbool, default False: Trueを設定すれば、指定したRangeの各行ごとにセルを結合します。

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

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

property name¶: Rangeの名前を設定または取得します。

Added in version 0.4.0.

property note¶: Returns a Note object. Before the introduction of threaded comments, a Note was called a Comment.

Added in version 0.24.2.

property number_format¶

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

例¶

>>> import xlwings as xw
>>> wb = xw.Book()
>>> sheet1 = wb.sheets[0]
>>> sheet1.range('A1').number_format
'General'
>>> sheet1.range('A1:C3').number_format = '0.00%'
>>> sheet1.range('A1:C3').number_format
'0.00%'

Added in version 0.2.3.

offset(row_offset=0, column_offset=0)¶: 指定したRangeからオフセットしたRangeを表すRangeオブジェクトを返します。

Returns¶

Range object : Range

Added in version 0.3.0.

options(convert=None, **options)¶

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

Arguments¶

convertobject, default None: dict 、 np.array 、 pd.DataFrame 、 pd.Series 等のコンバーター。デフォルトはデフォルトコンバーター。

Keyword Arguments¶

ndimint, default None: 次元数
numberstype, default None: 数字の型。例 int
datestype, default None: 例 datetime.date 。デフォルトは datetime.datetime 。
emptyobject, default None: 空白セルの変換方法
transposeBoolean, default False: 値の転置
expandstr, default None: One of 'table', 'down', 'right'
chunksizeint: 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.
err_to_strBoolean, default False: If True, will include cell errors such as #N/A as strings. By default, they will be converted to None.

Added in version 0.28.0.

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

Returns¶

Range object

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

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

Parameters¶

pastestr, default None: all_merging_conditional_formats 、 all 、 all_except_borders 、 all_using_source_theme 、 column_widths 、 comments 、 formats 、 formulas 、 formulas_and_number_formats 、 validation 、 values 、 values_and_number_formats のいずれか。
operationstr, default None: "add" 、 "divide" 、 "multiply" 、 "subtract" のいずれか。
skip_blanksbool, default False: True を設定すれば、空白セルを飛ばします。
transposebool, default False: True を設定すれば、行と列を入れ替えます。」

Returns¶

None

property raw_value¶: Gets and sets the values directly as delivered from/accepted by the engine that s being used (pywin32 or appscript) without going through any of xlwings' data cleaning/converting. This can be helpful if speed is an issue but naturally will be engine specific, i.e. might remove the cross-platform compatibility.

resize(row_size=None, column_size=None)¶

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

Arguments¶

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

Returns¶

Range object: Range

Added in version 0.3.0.

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

Returns¶

Integer

Added in version 0.3.5.

property row_height¶

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

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

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

Returns¶

float

Added in version 0.4.0.

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

Added in version 0.9.0.

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

Added in version 0.9.0.

property shape¶: Rangeの次元を表すタプル

Added in version 0.3.0.

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

Added in version 0.9.0.

property size¶: Rangeに含まれる要素数を返します。

Added in version 0.3.0.

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

Added in version 0.21.0.

to_pdf(path=None, layout=None, show=None, quality='standard')¶

Exports the range as PDF.

Parameters¶

pathstr or path-like, default None

Path where you want to store the pdf. Defaults to the address of the range in the same directory as the Excel file if the Excel file is stored and to the current working directory otherwise.

layoutstr 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).

showbool, default False

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

qualitystr, default 'standard'

Quality of the PDF file. Can either be 'standard' or 'minimum'.

Added in version 0.26.2.

to_png(path=None)¶

Exports the range as PNG picture.

Parameters¶

pathstr 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.

Added in version 0.24.8.

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

Returns¶

float

Added in version 0.6.0.

unmerge()¶: 結合セルを単独のセルに分割します。

property value¶

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

Returns¶

objectreturned object depends on the converter being used,: see xlwings.Range.options()

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

Returns¶

float

Added in version 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.

Added in version 0.23.2.