How to use Range.AddCommentThreaded in the xlwings API way

The AddCommentThreaded member of the Range object in the Excel object model enables the creation of a modern, threaded comment (introduced in Microsoft 365) within a specified cell or range. Unlike traditional notes or legacy comments, threaded comments support conversational replies, mentions (@), and are stored separately, making them ideal for collaborative discussions directly within a spreadsheet. In xlwings, this functionality is exposed through the api property, which provides direct access to the underlying Excel object model, allowing precise control over comment creation and properties.

Syntax in xlwings:
range.api.AddCommentThreaded(Text)

• range: An xlwings Range object representing the target cell or range (e.g., sheet.range('A1')).
• .api: Accesses the native Excel VBA object model.
• Text (optional): A string specifying the initial text of the comment thread. If omitted, an empty comment is created.

This method returns a CommentThreaded object, which can be further manipulated—for instance, to add replies, edit text, or resolve the thread. Key properties of the returned object include Text (for the initial comment), Author (the creator’s name), and Replies (a collection of reply objects).

Example Usage with xlwings:

1. Creating a Basic Threaded Comment:

import xlwings as xw

# Connect to the active workbook and sheet
wb = xw.books.active
sheet = wb.sheets['Sheet1']

# Add a threaded comment to cell B5
target_cell = sheet.range('B5')
new_thread = target_cell.api.AddCommentThreaded("Initial review: Please verify these figures by EOD.")

2. Adding a Comment with a Mention and Retrieving Properties:

# Add a comment with a mention (using the @ symbol to tag a collaborator)
thread = sheet.range('C10').api.AddCommentThreaded("@Alex, can you provide the Q3 data here?")

# Access properties of the new threaded comment
print(f"Author: {thread.Author}")
print(f"Text: {thread.Text}")
print(f"Date/Time: {thread.Date}")

# Add a reply to the thread
thread.Replies.Add("I'll upload the file by 3 PM today.")

3. Handling an Existing Comment Thread:
   If a cell already contains a threaded comment, using AddCommentThreaded will raise an error. To avoid this, check for existing comments first:

cell = sheet.range('D2')
if cell.api.CommentThreaded is None:
    cell.api.AddCommentThreaded("New discussion thread.")
else:
    print("A threaded comment already exists in this cell.")