How to use Worksheet.PageSetup in the xlwings API way

The PageSetup member of the Worksheet object in xlwings provides comprehensive control over printing settings, allowing users to configure page layout, margins, orientation, scaling, headers, footers, and other print-related properties programmatically. This is essential for generating professional reports and ensuring printed documents match specific formatting requirements. Through xlwings, you can access these settings using the api property to interact with the underlying Excel object model, enabling automation of print preparation tasks directly from Python.

Functionality:
The PageSetup object is used to manage all aspects of page setup for printing a worksheet. Key functionalities include setting page orientation (portrait or landscape), adjusting margins (top, bottom, left, right, header, footer), defining paper size, scaling printouts (by percentage or to fit a certain number of pages), and configuring headers and footers with text, page numbers, dates, or other elements. It also allows control over print titles, gridlines, and comments.

Syntax:
In xlwings, you access the PageSetup member via the worksheet object’s api property. The general syntax is:

worksheet.api.PageSetup.PropertyName
worksheet.api.PageSetup.MethodName(Arguments)

Where worksheet is an xlwings Worksheet object. Properties can be get or set, while methods perform actions. Common properties and methods include:

• Properties: Orientation, Zoom, FitToPagesTall, FitToPagesWide, TopMargin, BottomMargin, LeftMargin, RightMargin, HeaderMargin, FooterMargin, PaperSize, PrintTitleRows, PrintTitleColumns, PrintGridlines, PrintHeadings, LeftHeader, CenterHeader, RightHeader, LeftFooter, CenterFooter, RightFooter.
• Methods: PrintPreview(), PrintOut().

Parameters for methods like PrintOut() typically include: From, To, Copies, Preview, ActivePrinter, PrintToFile, Collate, PrToFileName. These can be specified as keyword arguments. Property values are often integers or strings; for example, Orientation can be set to 1 for portrait or 2 for landscape, and margins are in points.

Examples:
Here are xlwings API code instances demonstrating the use of PageSetup:

1. Setting Page Orientation and Scaling:

import xlwings as xw
wb = xw.Book('example.xlsx')
sheet = wb.sheets['Sheet1']

# Set landscape orientation
sheet.api.PageSetup.Orientation = 2 # 2 for landscape, 1 for portrait

# Set zoom to 80%
sheet.api.PageSetup.Zoom = 80

# Scale to fit to 1 page wide and 1 page tall
sheet.api.PageSetup.FitToPagesTall = 1
sheet.api.PageSetup.FitToPagesWide = 1

2. Adjusting Margins:

# Set margins in points (1 point = 1/72 inch)
sheet.api.PageSetup.TopMargin = 50
sheet.api.PageSetup.BottomMargin = 50
sheet.api.PageSetup.LeftMargin = 70
sheet.api.PageSetup.RightMargin = 70
sheet.api.PageSetup.HeaderMargin = 30
sheet.api.PageSetup.FooterMargin = 30

3. Configuring Headers and Footers:

# Set header and footer text
sheet.api.PageSetup.LeftHeader = "&LReport Date: &D"
sheet.api.PageSetup.CenterHeader = "&CSales Data"
sheet.api.PageSetup.RightHeader = "&RPage &P of &N"
sheet.api.PageSetup.LeftFooter = "&LConfidential"
sheet.api.PageSetup.CenterFooter = "&C&F"
sheet.api.PageSetup.RightFooter = "&RPrinted at &T"

Here, &L, &C, &R align left, center, right; &D is current date, &T is current time, &P is page number, &N is total pages, &F is file name.

4. Setting Print Titles and Gridlines:

# Set rows 1:1 as print titles
sheet.api.PageSetup.PrintTitleRows = "$1:$1"

# Print gridlines
sheet.api.PageSetup.PrintGridlines = True

# Print row and column headings
sheet.api.PageSetup.PrintHeadings = True

5. Printing the Worksheet:

# Preview print
sheet.api.PageSetup.PrintPreview()

# Print directly (optional parameters)
sheet.api.PageSetup.PrintOut(From=1, To=1, Copies=2, Preview=False, Collate=True)