Range¶

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

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

パラメータ:

cell1 (str | tuple[int, int] | Range | None) -- 左上セルをA1表記、インデックスのタプル、xw.Rangeオブジェクトのいずれかで指定します。'A1:B2'のようにrangeオペレーター（コロンのこと）での指定も可。
cell2 (str | tuple[int, int] | Range | 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（単独のセル）にハイパーリンクを追加します

パラメータ:

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

Added in version 0.3.0.

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

Added in version 0.9.0.

adjust_indent(amount)¶

Adjusts the indentation in a Range.

パラメータ:: amount (int) -- Number of spaces by which the indent is adjusted. Can be positive or negative.

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

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.

パラメータ:

destination (Range) -- The origin.
type -- 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: tuple[int, int, int] | None¶

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.

サンプル

>>> 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: int¶: Rangeに含まれる最初の列の番号を返します。読み取り専用。

Added in version 0.3.5.

property column_width: float | None¶

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

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

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

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

Added in version 0.4.0.

property columns: RangeColumns¶: Returns a RangeColumns object that represents the columns in the specified range.

Added in version 0.9.0.

copy(destination=None)¶

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

パラメータ:: destination (Range | None) -- xlwings Range to which the specified range will be copied. If omitted, the range is copied to the clipboard.

copy_from(source_range, copy_type='all', skip_blanks=False, transpose=False)¶

A newer variant of copy that replaces copy/paste.

パラメータ:

source_range (Range)
copy_type (str) -- One of "all", "formats", "formulas", "link", "values"
skip_blanks (bool)
transpose (bool)

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

Copies the range to the clipboard as picture.

パラメータ:

appearance (str) -- Either 'screen' or 'printer'.
format (str) -- Either 'picture' or 'bitmap'.

Added in version 0.24.8.

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

property current_region: Range¶: This property returns a Range object representing a range bounded by (but not including) any combination of blank rows and blank columns or the edges of the worksheet. It corresponds to Ctrl-* on Windows and Shift-Ctrl-Space on Mac.

delete(shift=None)¶

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

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

end(direction)¶

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

パラメータ:: direction (str)

サンプル

>>> 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')¶

Expands the range according to the mode provided. Ignores empty top-left cells (unlike Range.end()).

パラメータ:: mode (str) -- 'table' (=downとright)、 'down' 、 'right' のいずれか。

サンプル

>>> 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: str | list[str] | list[list[str]]¶: 指定したRangeのformulaプロパティを取得または設定します。

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

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

Added in version 0.7.1.

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

Returns the address of the range in the specified format. address can be used instead if none of the defaults need to be changed.

パラメータ:

row_absolute (bool) -- Trueを設定すれば、アドレスの行部分を絶対参照で取得します。
column_absolute (bool) -- Trueを設定すれば、アドレスの列部分を絶対参照で取得します。
include_sheetname (bool) -- Trueを設定すれば、アドレスにシート名が含まれます。external=Trueの場合、無視されます。
external (bool) -- Trueを設定すれば、アドレスにワークブック名とシート名が含まれます。

サンプル

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

async get_value()¶

Fetch values from Excel on demand.

Requires xlwings Lite.

group(by=None)¶

Group rows or columns.

パラメータ:: by (str | None) -- "columns" or "rows". Figured out automatically if the range is defined as '1:3' or 'A:C', respectively.

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

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

Added in version 0.4.0.

property hyperlink: str¶

指定した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')¶

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

パラメータ:

shift (str) -- Use right or down.
copy_origin (str) -- Use format_from_left_or_above or format_from_right_or_below. Note that copy_origin is only supported on Windows.

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

property last_cell: Range¶

指定した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: float¶: A列の左端からRangeの左端までの距離をポイント単位で返します。読み取り専用。

Added in version 0.6.0.

merge(across=False)¶

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

パラメータ:: across (bool) -- Trueを設定すれば、指定したRangeの各行ごとにセルを結合します。

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

property merge_cells: bool¶: Returns True if the Range contains merged cells, otherwise False

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

Added in version 0.4.0.

property note: Note | None¶: 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: str¶

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オブジェクトを返します。

Added in version 0.3.0.

options(convert=None, **options)¶

Allows you to set a converter and their options. Converters define how Excel Ranges and their values are being converted both during reading and writing operations. If no explicit converter is specified, the base converter is being applied, see converters.

パラメータ:: convert (Any) -- A converter, e.g. dict, np.array, pd.DataFrame, pd.Series, defaults to default converter.

:keyword ndim: Number of dimensions. :keyword numbers: Type of numbers, e.g. int. :keyword dates: E.g. datetime.date, defaults to datetime.datetime. :keyword empty: Transformation of empty cells. :keyword transpose: Transpose values. :keyword expand: One of 'table', 'down', 'right'. :keyword chunksize: 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. :keyword err_to_str: If True, will include cell errors such as #N/A as strings. By default, they will be converted to None. New in version 0.28.0.

For converter-specific options, see converters.

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

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

パラメータ:

paste (str | 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 のいずれか。
operation (str | None) -- "add" 、 "divide" 、 "multiply" 、 "subtract" のいずれか。
skip_blanks (bool) -- True を設定すれば、空白セルを飛ばします。
transpose (bool) -- True を設定すれば、行と列を入れ替えます。」

property raw_value: Any¶: 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をリサイズします

パラメータ:

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

Added in version 0.3.0.

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

Added in version 0.3.5.

property row_height: float | None¶

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

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

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

Added in version 0.4.0.

property rows: RangeRows¶: Returns a RangeRows object that represents the rows in the specified range.

Added in version 0.9.0.

select()¶

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

Added in version 0.9.0.

property shape: tuple[int, int]¶: Rangeの次元を表すタプル

Added in version 0.3.0.

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

Added in version 0.9.0.

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

Added in version 0.3.0.

property table: Table | None¶: Returns a Table object if the range is part of one, otherwise None.

Added in version 0.21.0.

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

Exports the range as PDF.

パラメータ:

path (str | PathLike[str] | 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.
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).
show (bool | None) -- Once created, open the PDF file with the default application.
quality (str) -- 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.

パラメータ:: path (str | PathLike[str] | 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: float¶: 1行目の上端からrangeの上端までの距離をポイント単位で返します。読み取り専用。

Added in version 0.6.0.

ungroup(by=None)¶

Ungroup rows or columns

パラメータ:: by (str | None) -- "columns" or "rows". Figured out automatically if the range is defined as '1:3' or 'A:C', respectively.

unmerge()¶

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

property value: Any¶: 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.

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

Added in version 0.4.0.

property wrap_text: bool | None¶: 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.