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オブジェクトのいずれかで指定します。

サンプル

# Assumes an existing workbook object named book.
sheet1 = book.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_comment(text)

Add a plain-text threaded comment to one cell and return its handle.

Raises TypeError for non-text content and ValueError for empty text or a multi-cell range. Excel rejects a second comment on the same cell.

戻り値の型:: Comment

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

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

パラメータ:

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

Added in version 0.3.0.

add_note(text)

Add a note to this single cell and return it.

Raises TypeError for non-text content and ValueError for empty text, a multi-cell range, or a cell that already has a note.

戻り値の型:: Note

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.

property autofilter: AutoFilter

Returns the AutoFilter for this range.

The first row is treated as the header row and field arguments are one-based column positions relative to the range.

サンプル

data = sheet["A1:C100"]
data.autofilter.apply_values(1, ["East", "West"])
data.autofilter.apply_comparison(3, "greater_than_or_equal", 10)
data.autofilter.clear(1)
data.autofilter.clear()

Added in version 0.37.5.

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 で変更.

property borders: Borders

Returns the Borders collection of the range, which gives access to the eight individual Border sides.

サンプル

>>> myrange = sheet["A1:D10"]
>>> myrange.borders.line_style = "continuous"  # edges + inside borders
>>> myrange.borders["edge_bottom"].weight = "thick"
>>> myrange.borders.set("outside", line_style="double", color="#ff0000")
>>> myrange.borders.clear()

Added in version 0.37.1.

property characters: Characters: Returns the Characters object for the range, used to format part of the text.

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.

サンプル

>>> # Assumes an existing workbook object named book.
>>> sheet1 = book.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

Setter type:: tuple[int, int, int] | int | str | None

Added in version 0.3.0.

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

Added in version 0.3.5.

property column_width: float | None

Gets or sets the width of a Range.

The unit depends on the engine: characters with classic xlwings, where one unit is the width of one character in the Normal style (for proportional fonts, the character 0), and points with xlwings Server and xlwings Lite.

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

In characters, column_width must be in the range 0 <= column_width <= 255. In points it only has to be positive.

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

Setter type:: float

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.

property comment: Comment | None: The cell's threaded comment. In xlwings Lite, use await get_comment().

property conditional_formats: ConditionalFormats

Returns the conditional-format rules for this range.

In xlwings Lite, use await sheet["A1:D10"].get_conditional_formats() for inspection; sheet["A1:D10"].conditional_formats.clear() remains available.

Added in version 0.37.5.

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.

property data_validation: DataValidation

Returns the data validation object for the range.

Use it to create, replace, or remove a validation rule. On xlwings Lite, use Range.get_data_validation() instead.

サンプル

sheet["A1:A10"].data_validation.set_list(["Open", "Closed"])
sheet["B1:B10"].data_validation.set_list(sheet["D1:D3"])
sheet["C1:C10"].data_validation.set_list(book.names["Statuses"])
sheet["E1:E10"].data_validation.set_whole_number("between", 1, 10)
sheet["F1:F10"].data_validation.set_custom("=F1<>""")
sheet["A1:A10"].data_validation.delete()

Added in version 0.37.5.

delete(shift=None)

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

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

end(direction)

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

パラメータ:: direction (str)
戻り値の型:: Range

サンプル

>>> # Assumes an existing workbook object named book.
>>> sheet1 = book.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' のいずれか。
戻り値の型:: Range

サンプル

>>> # Assumes an existing workbook object named book.
>>> sheet1 = book.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.

find(text, *, whole=False, direction='forward', order='rows', match_case=False)

Find the first matching cell or return None; in xlwings Lite, use await rng.find(...).

Classic xlwings returns the result directly. The search starts at the first cell in the requested traversal direction and is restricted to this range.

パラメータ:

text (str) -- Text to find. An empty string is not allowed.
whole (bool) -- Match the entire cell rather than part of it.
direction (str) -- "forward" or "backward".
order (str) -- Search by "rows" or "columns".
match_case (bool) -- Whether matching is case-sensitive.

戻り値の型:

Range | None | Awaitable[Range | None]

サンプル

With classic xlwings:

# Assumes an existing workbook object named book.
sheet = book.sheets[0]
sheet["A1:A3"].value = [["North"], ["South"], ["North"]]
found = sheet["A1:A3"].find("South", whole=True)
print(found.address if found else None)  # $A$2

In xlwings Lite, await the same search:

# Assumes an existing workbook object named book.
sheet = book.sheets["Sheet1"]
sheet["A1:A3"].value = [["North"], ["South"], ["North"]]
await book.flush()
found = await sheet["A1:A3"].find("South", whole=True)
print(found.address if found else None)  # $A$2

property font: Font: Returns the Font object for the range, used to read or change font formatting.

property formula: str | list[str] | list[list[str]]

Gets or sets formulas using Excel's implicit-intersection formula semantics with classic xlwings.

Assign a formula string to fill the range, or a list or list of lists to write formulas to individual cells. Writing accepts the converters and shape options supported by Range.options.

For dynamic-array formulas with classic xlwings, use formula2. In xlwings Lite, both properties write through the same Office.js formula API, which supports dynamic arrays. Synchronous formula reads are not supported in xlwings Lite; use await rng.get_formula().

Setter type:: Any

property formula2: str | list[str] | list[list[str]]

Gets or sets formulas using Excel's dynamic-array formula semantics with classic xlwings.

Assign a formula string to fill the range, or a list or list of lists to write formulas to individual cells. Writing accepts the converters and shape options supported by Range.options.

In xlwings Lite, this property writes through the same Office.js formula API as formula. Read formulas with await rng.get_formula(); there is no separate get_formula2() method.

Setter type:: Any

property formula_array: str | None

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

Setter type:: str

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を設定すれば、アドレスにワークブック名とシート名が含まれます。

戻り値の型:

str

サンプル

>>> # Assumes an existing workbook object named book.
>>> sheet1 = book.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_color()

Fetch the fill color on demand, as an RGB tuple.

Returns None if the range has no fill.

Requires xlwings Lite.

戻り値の型:: tuple[int, int, int] | None

async get_colors()

Returns the fill color of every cell as a two-dimensional list.

Each entry is an RGB tuple, or None for no fill color. The result always has the range's row and column dimensions, including [[color]] for a single cell; conversion options such as ndim and transpose do not affect it.

Reads direct cell fills, excluding colors supplied by conditional formatting or table styles. For patterned fills, returns the background fill color, not the pattern color or rendered appearance.

A call supports at most 100,000 cells.

サンプル

colors = await sheet["A1:B2"].get_colors()
# [[(255, 0, 0), None], [(255, 255, 255), (0, 0, 255)]]

See get_color for a single range-level fill color.

Requires xlwings Lite.

Added in version 0.37.5.

戻り値の型:: list[list[tuple[int, int, int] | None]]

async get_column_width()

Fetch the column width on demand, in points.

Returns None if the range's columns aren't all the same width.

Requires xlwings Lite.

戻り値の型:: float | None

async get_comment()

Fetch the cell's threaded comment, or None.

Requires xlwings Lite.

戻り値の型:: Comment | None

async get_conditional_formats()

Fetch the ordered conditional-format rules on demand.

Rules are returned from highest to lowest evaluation priority. Requires xlwings Lite.

Added in version 0.37.5.

戻り値の型:: ConditionalFormats

async get_current_region()

Fetch the current region on demand.

The region bounded by blank rows and columns around this range, i.e. Ctrl-*.

Requires xlwings Lite.

戻り値の型:: Range

async get_data_validation()

Fetch this range's data-validation rule for the range.

Returns "none" when the range has no validation, "mixed_criteria" when only some cells have validation, and "inconsistent" when cells have different rules.

Requires xlwings Lite.

Added in version 0.37.5.

戻り値の型:: DataValidation

async get_formula()

Fetch formulas on demand.

The returned shape follows the same rules as reading value: a single cell gives a string, a 1-by-n or n-by-1 range a flat list, and anything else a nested list. options(ndim=...) applies as usual.

Requires xlwings Lite.

戻り値の型:: str | list[str] | list[list[str]]

async get_formula_array()

Fetch the array formula for this range on demand.

A single string, or None if the range holds no array formula. Unlike get_formula(), this isn't a value per cell.

Requires xlwings Lite.

戻り値の型:: str | None

async get_height()

Fetch the range's height in points, on demand.

Requires xlwings Lite.

戻り値の型:: float

async get_horizontal_alignment()

Fetch the horizontal alignment on demand.

None if the cells in the range don't all have the same alignment.

Requires xlwings Lite.

戻り値の型:: str | None

async get_hyperlink()

Fetch this cell's hyperlink address on demand.

The async equivalent of hyperlink: same result, including for cells that use a HYPERLINK() formula. Raises if the cell has no hyperlink.

Requires xlwings Lite.

戻り値の型:: str

async get_left()

Fetch the distance from the sheet's left edge, in points, on demand.

Requires xlwings Lite.

戻り値の型:: float

async get_merge_area()

Fetch the merged range containing this cell, on demand.

Returns this range itself if it isn't part of a merged range.

Requires xlwings Lite.

戻り値の型:: Range

async get_merge_cells()

Fetch whether this range contains merged cells, on demand.

True if the whole range is merged, False if none of it is, and None if it's only partly merged.

Requires xlwings Lite.

戻り値の型:: bool | None

async get_number_format()

Fetch the number format on demand.

A single format string, or None if the range's cells don't share one.

Requires xlwings Lite.

戻り値の型:: str | None

async get_row_height()

Fetch the row height on demand, in points.

Returns None if the range's rows aren't all the same height.

Requires xlwings Lite.

戻り値の型:: float | None

get_special_cells(cell_type, value_type=None)

Return matching rectangular areas; in xlwings Lite, use await rng.get_special_cells(...).

cell_type is "blanks", "constants", "formulas", or "visible". For constants or formulas, value_type may be "numbers", "text", "logical", or "errors"; omitting it selects all value types. Returns an empty list when no cells match. Classic xlwings returns the list directly.

戻り値の型:: list[Range] | Awaitable[list[Range]]

async get_table()

Fetch the Table this range is part of, on demand.

Returns None if the range isn't part of a table.

Requires xlwings Lite.

戻り値の型:: Table | None

async get_top()

Fetch the distance from the sheet's top edge, in points, on demand.

Requires xlwings Lite.

戻り値の型:: float

async get_value()

Reads the range's current values from Excel asynchronously.

Supports the same converters and options as value, including DataFrames, ndim, transpose, and chunksize. Without an explicit converter, a single cell returns a scalar, a single row or column returns a flat list, and a two-dimensional range returns a list of lists. Use rng.options(ndim=2) to always receive a list of rows.

サンプル

Inside an asynchronous script with a supplied book parameter:

sheet = book.sheets["Sheet1"]
rows = await sheet["A1:B10"].options(ndim=2).get_value()

Requires xlwings Lite.

戻り値の型:: Any

async get_vertical_alignment()

Fetch the vertical alignment on demand.

None if the cells in the range don't all have the same alignment.

Requires xlwings Lite.

戻り値の型:: str | None

async get_width()

Fetch the range's width in points, on demand.

Requires xlwings Lite.

戻り値の型:: float

async get_wrap_text()

Fetch the wrap text setting on demand.

None if the range doesn't have a uniform wrap setting.

Requires xlwings Lite.

戻り値の型:: bool | None

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 horizontal_alignment: Literal['general', 'left', 'center', 'right', 'fill', 'justify', 'center_across_selection', 'distributed'] | None

Returns or sets the horizontal alignment of the range.

One of 'general', 'left', 'center', 'right', 'fill', 'justify', 'center_across_selection' or 'distributed'. Returns None if the cells in the range don't all have the same alignment. The default is 'general', which right-aligns numbers and dates and left-aligns text.

Reading this property synchronously requires classic xlwings. Setting it is also supported with xlwings Lite and xlwings Server; in xlwings Lite, read it via get_horizontal_alignment().

サンプル

>>> sheet["A1"].horizontal_alignment = "center"
>>> sheet["A1"].horizontal_alignment
'center'

Setter type:: str

Added in version 0.37.3.

property hyperlink: str

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

サンプル

>>> # Assumes an existing workbook object named book.
>>> sheet1 = book.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の右下セルを返します。読み取り専用。

サンプル

>>> # Assumes an existing workbook object named book.
>>> sheet1 = book.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の名前を設定または取得します。

Setter type:: str

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 を取得または設定します。

サンプル

>>> # Assumes an existing workbook object named book.
>>> sheet1 = book.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.

戻り値の型:: Range

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.

キーワード引数:

ndim -- Number of dimensions.
numbers -- Type of numbers, e.g. int.
dates -- E.g. datetime.date, defaults to datetime.datetime.
empty -- Transformation of empty cells.
transpose -- Transpose values.
expand -- One of 'table', 'down', 'right'.
chunksize -- Number of rows per chunk when reading or writing large amounts of data, e.g. 10000. Large ranges are chunked automatically (reads above 4,000,000 cells, writes above 100,000 cells with classic xlwings and the remote engines); set chunksize explicitly to tune the row count, e.g. to prevent timeout, memory or payload-size issues, or chunksize=None to disable chunking. Works with all formats, including DataFrames, NumPy arrays, and list of lists.
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.

戻り値の型:

Range

Without an explicit converter, a single cell returns a scalar, a single row or column returns a flat list, and a two-dimensional range returns a list of lists. Use ndim=2 when code needs a list of rows regardless of the range shape: a single cell becomes [[value]], one row becomes [[a, b]], and one column becomes [[a], [b]].

Options apply to both value and, in xlwings Lite, get_value. For example, rng.options(ndim=2).value and await rng.options(ndim=2).get_value() both request a two-dimensional result. Converter-specific options are described in 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.

remove_duplicates(columns, has_headers=False)

Remove duplicate rows within this range, keeping the first occurrence.

パラメータ:

columns (int | Sequence[int]) -- One-based column positions within this range used to identify duplicates.
has_headers (bool) -- Keep the first row as a header.

Only cells inside this range are shifted. Ranges intersecting an Excel table are not supported. On macOS this method isn't supported and raises NotImplementedError.

replace_all(old, new, *, whole=False, match_case=False)

Replace matching text within this range.

An empty replacement string is allowed; an empty search string is not.

サンプル

# Assumes an existing workbook object named book.
sheet = book.sheets[0]
sheet["A1:A2"].value = [["Draft"], ["Draft report"]]
sheet["A1:A2"].replace_all("Draft", "Final")
print(sheet["A2"].value)  # Final report

In xlwings Lite, inside an asynchronous script with a supplied book parameter:

# Assumes an existing workbook object named book.
sheet = book.sheets["Sheet1"]
sheet["A1:A2"].value = [["Draft"], ["Draft report"]]
sheet["A1:A2"].replace_all("Draft", "Final")
await book.flush()
print(await sheet["A2"].get_value())  # Final report

resize(row_size=None, column_size=None)

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

パラメータ:

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

戻り値の型:

Range

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内の高さが異なる場合、最初の高さを返します。

Setter type:: float

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.

set_colors(colors)

Set direct fill colors cell by cell without changing cell contents.

colors must be a two-dimensional matrix exactly matching the range's shape, including [[color]] for one cell. An RGB tuple or list or a #RRGGBB hex string. None removes the fill; ... leaves that cell's existing fill unchanged. Conversion options do not change the required matrix shape.

サンプル

sheet["A1:C1"].set_colors([[(0, 128, 0), ..., None]])

Added in version 0.37.5.

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.

sort(keys, ascending=True, has_headers=False)

Sort the rows of this rectangular range by one or more columns.

パラメータ:

keys (int | Sequence[int]) -- One-based column positions within this range, in priority order.
ascending (bool | Sequence[bool]) -- One direction for every key, or one boolean per key.
has_headers (bool) -- Whether to keep the first row in place as a header.

The range is not expanded to adjacent data. Ranges intersecting an Excel table are not supported; use Table.sort instead.

サンプル

sheet["A1:D20"].sort([2, 1], [False, True], has_headers=True)

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

戻り値の型:

str

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.

Without an explicit converter, a single cell returns a scalar, a single row or column returns a flat list, and a two-dimensional range returns a list of lists. Use options to control dimensionality, convert values to a DataFrame, or set a chunk size.

In xlwings Lite, reads use the cell values loaded for the script. A script annotated with BookAsync does not preload cell values: use await rng.get_value() to read them.

property vertical_alignment: Literal['top', 'center', 'bottom', 'justify', 'distributed'] | None

Returns or sets the vertical alignment of the range.

One of 'top', 'center', 'bottom', 'justify' or 'distributed'. Returns None if the cells in the range don't all have the same alignment. The default is 'bottom'.

Reading this property synchronously requires classic xlwings. Setting it is also supported with xlwings Lite and xlwings Server; in xlwings Lite, read it via get_vertical_alignment().

サンプル

>>> sheet["A1"].vertical_alignment = "top"
>>> sheet["A1"].vertical_alignment
'top'

Setter type:: str

Added in version 0.37.3.

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.

Setter type:: bool

Added in version 0.23.2.