How to use Range.InsertIndent in the xlwings API way

The InsertIndent method in Excel’s object model, accessible through the xlwings Python library, is a powerful tool for adjusting the indentation level of text within a cell or a range of cells. This functionality is essential for improving the readability and hierarchical structure of data, such as in outlines, nested lists, or financial statements where subtotals are indented. Unlike simply adding spaces, InsertIndent formally changes the cell’s formatting, ensuring consistent appearance and proper alignment.

Functionality
The primary purpose of the InsertIndent method is to increase the indentation of the text content. It shifts the text further from the left border of the cell by a specified number of levels. Each indent level corresponds to the standard indent increment defined in Excel (typically equivalent to three spaces or the width of one character in the default font). This method directly modifies the Range.IndentLevel property. It is important to note that InsertIndent only adds indentation; to decrease it, you would adjust the IndentLevel property directly or use other formatting methods.

Syntax in xlwings
In xlwings, the method is called on a Range object. The syntax is straightforward:

range_object.api.InsertIndent(InsertAmount)

• range_object: This is your xlwings Range object (e.g., sheet.range('A1') or sheet.range('B2:D5')).
• .api: This property provides direct access to the underlying Excel object model (the COM API). The InsertIndent method is part of this native API.
• InsertAmount: A required parameter of type Integer. It specifies the number of indent levels to add. The value must be greater than or equal to 0. Passing 0 has no effect.

Code Examples

1. Basic Indentation of a Single Cell:
   This example indents the text in cell A1 by one level.

import xlwings as xw
# Connect to the active Excel instance and workbook
app = xw.apps.active
wb = app.books.active
sheet = wb.sheets['Sheet1']

# Target cell A1 and insert one indent level
target_cell = sheet.range('A1')
target_cell.api.InsertIndent(1)

2. Indenting a Contiguous Range:
   You can apply indentation to an entire row, column, or block of cells. This code indents all cells in the range B3 through B10 by two levels, useful for creating a sub-list.

import xlwings as xw
wb = xw.books.active
sheet = wb.sheets[0]

list_range = sheet.range('B3:B10')
# Increase indentation by 2 levels for the entire range
list_range.api.InsertIndent(2)

3. Indenting Based on a Condition:
   This demonstrates a practical application where indentation is applied dynamically. It scans column A for cells containing the word “Subtotal” and indents those cells to visually distinguish them from main items.

import xlwings as xw
wb = xw.books.active
main_sheet = wb.sheets['Report']

# Find the last used row in column A
last_row = main_sheet.range('A' + str(main_sheet.cells.last_cell.row)).end('up').row

for row in range(1, last_row + 1):
    cell = main_sheet.range((row, 1)) # Column A
    if 'Subtotal' in str(cell.value):
        # Indent subtotal rows by one level
        cell.api.InsertIndent(1)