How to use Worksheet.CheckSpelling in the xlwings API way

The CheckSpelling member of a Worksheet object in Excel provides a programmatic way to initiate a spell check on the text within that specific worksheet. In xlwings, this functionality is exposed through the api property, which grants direct access to the underlying Excel object model. This is particularly useful for automating document review processes or for integrating spell-checking into larger data validation and reporting workflows. The method checks the spelling of words in the worksheet’s cells, leveraging the same dictionaries and custom dictionaries used by Excel’s native spell-check feature.

Syntax in xlwings:
The method is accessed via the worksheet’s api object. Its full syntax in the Excel object model is complex, but the xlwings call typically uses the most common parameters.

worksheet.api.CheckSpelling(CustomDictionary, IgnoreUppercase, AlwaysSuggest, SpellLang)

• CustomDictionary (Optional, String): The file name of the custom dictionary to be used if the word is not found in the main dictionary. If omitted, the currently specified dictionary is used.
• IgnoreUppercase (Optional, Boolean): True to have Excel ignore words in all uppercase letters (e.g., “USA”). False to check them. If omitted, the current application setting is used.
• AlwaysSuggest (Optional, Boolean): True to have Excel display a list of suggestions for misspelled words. False to just check spelling without suggestions. If omitted, the current application setting is used.
• SpellLang (Optional, Variant): The language of the dictionary to use. This can be a language ID (LCID). It’s often omitted to use the application’s default language.

In practice, when called without arguments, it starts the interactive spell-check dialog, just like pressing F7 in Excel.

Code Examples:

1. Basic Spell Check (Interactive Dialog):
   This code opens the specified workbook, activates the first worksheet, and starts the standard Excel spell-check dialog, pausing the script until the user closes it.

import xlwings as xw
# Connect to an open workbook or open a new one
app = xw.App(visible=True)
wb = app.books.open('report.xlsx')
ws = wb.sheets[0]
# Start the interactive spell check
ws.api.CheckSpelling()
# ... other operations can follow after the dialog is closed
wb.save()
wb.close()
app.quit()

2. Spell Check with Specific Parameters:
   This example performs a spell check that ignores words in all caps and uses a specific custom dictionary file. Note that the AlwaysSuggest parameter might not prevent the dialog from appearing if misspellings are found, depending on Excel’s version and settings.

import xlwings as xw
from pathlib import Path

custom_dict_path = str(Path.home() / 'custom.dic')
with xw.App(visible=False) as app:
wb = app.books.add()
ws = wb.sheets[0]
# Populate some cells with text for testing
ws.range('A1').value = "This is a testt for spellling."
ws.range('A2').value = "NASA and HTML are acronyms."

# Check spelling, ignoring uppercase words, using a custom dict
# The method likely returns True if no errors were found, False otherwise.
check_passed = ws.api.CheckSpelling(CustomDictionary=custom_dict_path,
IgnoreUppercase=True,
AlwaysSuggest=False)
print(f"Spell check passed without errors: {check_passed}")
# In a non-visible app, the dialog may not appear; the return value is key.