Range Object

Analogous to its counterpart in Excel, the xlwings Range object represents a selection of cells containing one or more contiguous blocks of cells in Excel.

class xlwings.Range(*args, **kwargs)

A Range object can be created with the following arguments:

Range('A1')          Range('Sheet1', 'A1')          Range(1, 'A1')
Range('A1:C3')       Range('Sheet1', 'A1:C3')       Range(1, 'A1:C3')
Range((1,2))         Range('Sheet1, (1,2))          Range(1, (1,2))
Range((1,1), (3,3))  Range('Sheet1', (1,1), (3,3))  Range(1, (1,1), (3,3))
Range('NamedRange')  Range('Sheet1', 'NamedRange')  Range(1, 'NamedRange')

If no worksheet name is provided as first argument (as name or index), it will take the Range from the active sheet.

You usually want to go for Range(...).value to get the values (as list of lists).

Parameters:
  • *args

    Definition of sheet (optional) and Range in the above described combinations.

  • asarray (boolean, default False) – Returns a NumPy array (atleast_1d) where empty cells are transformed into nan.
  • index (boolean, default True) – Includes the index when setting a Pandas DataFrame or Series.
  • header (boolean, default True) – Includes the column headers when setting a Pandas DataFrame.
  • atleast_2d (boolean, default False) – Returns 2d lists/arrays even if the Range is a Row or Column.
is_cell()

Returns True if the Range consists of a single Cell otherwise False

is_row()

Returns True if the Range consists of a single Row otherwise False

is_column()

Returns True if the Range consists of a single Column otherwise False

is_table()

Returns True if the Range consists of a 2d array otherwise False

value

Gets and sets the values for the given Range.

Returns:Empty cells are set to None. If asarray=True, a numpy array is returned where empty cells are set to nan.
Return type:list or numpy array
formula

Gets or sets the formula for the given Range.

table

Returns a contiguous Range starting with the indicated cell as top-left corner and going down and right as long as no empty cell is hit.

Parameters:strict (boolean, default False) – strict stops the table at empty cells even if they contain a formula. Less efficient than if set to False.
Return type:xlwings Range object

Examples

To get the values of a contiguous range or clear its contents use:

Range('A1').table.value
Range('A1').table.clear_contents()
vertical

Returns a contiguous Range starting with the indicated cell and going down as long as no empty cell is hit. This corresponds to Ctrl + Shift + Down Arrow in Excel.

Parameters:strict (bool, default False) – strict stops the table at empty cells even if they contain a formula. Less efficient than if set to False.
Return type:xlwings Range object

Examples

To get the values of a contiguous range or clear its contents use:

Range('A1').vertical.value
Range('A1').vertical.clear_contents()
horizontal

Returns a contiguous Range starting with the indicated cell and going right as long as no empty cell is hit.

Parameters:strict (bool, default False) – strict stops the table at empty cells even if they contain a formula. Less efficient than if set to False.
Return type:xlwings Range object

Examples

To get the values of a contiguous range or clear its contents use:

Range('A1').horizontal.value
Range('A1').horizontal.clear_contents()
current_region

The current_region 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 + *.

Returns:
Return type:xlwings Range object
clear()

Clears the content and the formatting of a Range.

clear_contents()

Clears the content of a Range but leaves the formatting.

Previous topic

Workbook Object

Next topic

Chart Object

This Page