How to use Range.Copy in the xlwings API way

The Copy method in Excel’s Range object is a fundamental operation for duplicating cell contents, formatting, and formulas to another location within the same workbook or to a different workbook. In xlwings, this functionality is accessed through the api property, which provides direct access to the underlying Excel object model. This allows for precise control over the copy operation, including specifying a destination range.

Functionality
The primary purpose of the Copy method is to replicate a source range. It copies all elements: values, formulas, number formats, cell formatting (like borders and fill), and column widths/row heights if the entire column/row is selected. This is equivalent to performing a standard copy-paste operation in the Excel UI. The method can be used without a destination to copy to the Clipboard, or with a destination to paste directly.

Syntax
The xlwings API call follows the pattern of the Excel VBA Range.Copy method.

range_object.api.Copy(Destination)

• range_object: Your xlwings Range object (e.g., sheet.range('A1:B2')).
• .api: The gateway to the native Excel object model.
• .Copy: The method itself.
• Destination (Optional): An xlwings Range object specifying the top-left cell of the destination range. If omitted, the range is copied to the Clipboard.

Parameter Details

Parameter	Type	Description	Required
Destination	xlwings Range Object	The target cell where the copied range will be pasted. Only the top-left cell needs to be specified; the paste area will match the size of the source range.	No

Code Examples

1. Copy to a specific destination (direct paste):
   This is the most common use case. It copies A1:D5 from Sheet1 and pastes it starting at cell F1 on the same sheet.

import xlwings as xw
wb = xw.Book.active
sht = wb.sheets['Sheet1']
source_range = sht.range('A1:D5')
destination_cell = sht.range('F1')
source_range.api.Copy(Destination=destination_cell.api)

2. Copy to the Clipboard:
   By not providing a Destination argument, the range is placed on the Windows/macOS Clipboard. Another application (like another Excel instance or Notepad) can then paste it.

import xlwings as xw
sht = xw.Book.active.sheets[0]
sht.range('A1:A10').api.Copy() # Data is now on the clipboard

3. Copy between different worksheets:
   This example copies data from Sheet1 to Sheet2, starting at cell A1 on the target sheet.

import xlwings as xw
wb = xw.Book.active
source_sht = wb.sheets['Sheet1']
target_sht = wb.sheets['Sheet2']
source_sht.range('C10:F20').api.Copy(Destination=target_sht.range('A1').api)

4. Copy using a Range object variable for the destination:
   This demonstrates using a pre-defined Range object as the target, which can be useful in dynamic scripts.

import xlwings as xw
app = xw.App(visible=False)
wb = app.books.open('report.xlsx')
source = wb.sheets['Data'].range('Table1[#All]') # Copy an entire Table
target_start = wb.sheets['Summary'].range('B5')
source.api.Copy(Destination=target_start.api)
wb.save()
app.quit()