How to use Range.NoteText in the xlwings API way

The NoteText member of the Range object in the Excel object model is accessible through the xlwings library in Python, enabling programmatic interaction with cell notes (formerly known as comments in older Excel versions, but distinct from the modern threaded comments). This functionality is crucial for automating the retrieval, modification, or insertion of textual annotations within specific cells of an Excel workbook, facilitating tasks such as data validation notes, instructional text, or historical data tracking directly from Python scripts.

In xlwings, the NoteText property is used to get or set the text of a cell note. The syntax for accessing this property is straightforward, as it behaves like a standard property of a Range object. The general format is range_object.note_text, where range_object is an instance of xlwings’ Range. When getting the property, it returns a string containing the note’s text if a note exists; otherwise, it returns None. When setting the property, you assign a string to it, which will either create a new note with that text or update the text of an existing note in the specified cell. It’s important to note that this property specifically handles the legacy “note” feature, not the newer “comments” (threaded comments) introduced in recent Excel versions, which are managed through a different API.

For example, consider a scenario where you need to read an existing note from cell A1 in the active worksheet and then update it with additional information. The xlwings code would be:

import xlwings as xw

# Connect to the active Excel instance and workbook
app = xw.apps.active
wb = app.books.active
sheet = wb.sheets.active

# Define the target cell range
target_cell = sheet.range('A1')

# Get the existing note text
current_note = target_cell.note_text
print(f"Current note in A1: {current_note}")

# Set new note text, adding to the existing content if desired
new_text = "Updated: Review completed on 2023-10-05."
target_cell.note_text = new_text

# Alternatively, append to the existing note
if current_note:
    updated_note = current_note + "\n" + new_text
else:
    updated_note = new_text
    target_cell.note_text = updated_note

Another common use case is iterating through a range of cells to check for notes and perform actions based on their content. For instance, you might want to extract all notes from a column and log them:

# Assume we have data in column B from rows 1 to 10
for i in range(1, 11):
    cell = sheet.range(f'B{i}')
    note = cell.note_text
    if note:
        print(f"Note in B{i}: {note}")