How to use Worksheet.PrintOut in the xlwings API way

The PrintOut method of the Worksheet object in the Excel object model is a powerful feature for programmatically printing worksheets. In xlwings, this functionality is exposed through the api property, which provides direct access to the underlying Excel VBA object model. This allows for precise control over printing parameters, enabling automation of printing tasks directly from Python scripts.

Functionality
The PrintOut method prints the specified worksheet. It offers a range of optional parameters to control aspects such as the number of copies, print preview, printer selection, print range, and output to a file. This is essential for automating report generation, batch printing, or creating printed outputs from data processed in Python.

Syntax
In xlwings, the method is accessed via the worksheet’s api object. The full syntax, with parameters mapped from the VBA method, is as follows:
worksheet.api.PrintOut(From, To, Copies, Preview, ActivePrinter, PrintToFile, Collate, PrToFileName, IgnorePrintAreas)
Where:

• From: (Optional) The page number from which to start printing. If omitted, printing starts from the beginning.
• To: (Optional) The page number on which to stop printing. If omitted, printing goes to the end.
• Copies: (Optional) The number of copies to print. If omitted, one copy is printed.
• Preview: (Optional) True to have Excel invoke print preview before printing. False (default) to print immediately.
• ActivePrinter: (Optional) Sets the name of the active printer.
• PrintToFile: (Optional) True to print to a file. If PrToFileName is not specified, Excel prompts the user for the output filename.
• Collate: (Optional) True (default) to collate multiple copies.
• PrToFileName: (Optional) If PrintToFile is set to True, this specifies the path and filename of the output file (e.g., "C:\Output.pdf").
• IgnorePrintAreas: (Optional) True to ignore any print areas set in the worksheet and print the entire sheet.

Code Examples

1. Basic Print: Print the active worksheet immediately to the default printer.

import xlwings as xw
wb = xw.Book("report.xlsx")
ws = wb.sheets["Data"]
ws.api.PrintOut()

2. Print with Preview and Copies: Print two collated copies of the worksheet after showing the print preview.

ws.api.PrintOut(Copies=2, Preview=True, Collate=True)

3. Print Specific Pages: Print only pages 2 through 4 of the worksheet.

ws.api.PrintOut(From=2, To=4)

4. Print to PDF File: Print the entire worksheet to a PDF file, ignoring any set print area.

output_path = r"C:\Reports\output.pdf"
ws.api.PrintOut(PrintToFile=True, PrToFileName=output_path, IgnorePrintAreas=True)

5. Using Named Arguments for Clarity: Explicitly naming arguments is recommended for readability.

ws.api.PrintOut(From=1, To=1, Copies=1, Preview=False, Collate=True, IgnorePrintAreas=False)