App

class App(visible=None, spec=None, add_book=True)

An app corresponds to an Excel instance and should normally be used as context manager to make sure that everything is properly cleaned up again and to prevent zombie processes. New Excel instances can be fired up like so:

import xlwings as xw

with xw.App() as app:
    print(app.books)

An app object is a member of the apps collection:

>>> xw.apps
Apps([<Excel App 1668>, <Excel App 1644>])
>>> xw.apps[1668]  # get the available PIDs via xw.apps.keys()
<Excel App 1668>
>>> xw.apps.active
<Excel App 1668>

參數:

• visible (bool | None) -- Returns or sets a boolean value that determines whether the app is visible. The default leaves the state unchanged or sets visible=True if the object doesn't exist yet.

• spec (str | None) -- Mac-only, use the full path to the Excel application, e.g., /Applications/Microsoft Office 2011/Microsoft Excel or /Applications/Microsoft Excel. On Windows, if you want to change the version of Excel that xlwings talks to, go to Control Panel > Programs and Features and Repair the Office version that you want as default.

備註

On Mac, while xlwings allows you to run multiple instances of Excel, it's a feature that is not officially supported by Excel for Mac: Unlike on Windows, Excel will not ask you to open a read-only version of a file if it is already open in another instance. This means that you need to watch out yourself so that the same file is not being overwritten from different instances.

activate(steal_focus=False)

Activates the Excel app.

參數:

steal_focus (bool) -- If True, make frontmost application and hand over focus from Python to Excel.

在 0.9.0 版被加入.

alert(prompt, title=None, buttons='ok', mode=None, callback=None)

This corresponds to MsgBox in VBA, shows an alert/message box and returns the value of the pressed button. For xlwings Server, instead of returning a value, the function accepts the name of a callback to which it will supply the value of the pressed button.

參數:

• prompt (str) -- The message to be displayed.

• title (str | None) -- The title of the alert.

• buttons (str) -- Can be either "ok", "ok_cancel", "yes_no", or "yes_no_cancel".

• mode (str | None) -- Can be "info" or "critical". Not supported by Google Sheets.

• callback (str | None) -- Only used by xlwings Server: you can provide the name of a function that will be called with the value of the pressed button as argument. The function has to exist on the client side, i.e., in VBA or JavaScript.

回傳型別:

str | None

回傳:

None when used with xlwings Server, otherwise the value of the pressed button in lowercase: "ok", "cancel", "yes", "no".

回傳型別:

str | None

在 0.27.13 版被加入.

property api: Any

Returns the native object (pywin32 or appscript obj) of the engine being used.

在 0.9.0 版被加入.

property books: Books

A collection of all Book objects that are currently open.

在 0.9.0 版被加入.

calculate()

Calculates all open books.

在 0.3.6 版被加入.

property calculation: str

Returns or sets a calculation value that represents the calculation mode. Modes: 'manual', 'automatic', 'semiautomatic'

範例

>>> import xlwings as xw
>>> wb = xw.Book()
>>> wb.app.calculation = 'manual'

在 0.9.0 版的變更.

property cut_copy_mode: str | None

Gets or sets the status of the cut or copy mode. Accepts False for setting and returns None, copy or cut when getting the status.

Setter type:

bool

在 0.24.0 版被加入.

property display_alerts: bool

The default value is True. Set this property to False to suppress prompts and alert messages while code is running; when a message requires a response, Excel chooses the default response.

在 0.9.0 版被加入.

property enable_events: bool

True if events are enabled. Read/write boolean.

在 0.24.4 版被加入.

async get_selection()

Returns the selected cells as Range, fetched live from Excel.

Requires xlwings Lite.

在 0.35.0 版被加入.

回傳型別:

Range | None

property hwnd: int | None

Returns the Window handle (Windows-only).

在 0.9.0 版被加入.

property interactive: bool

True if Excel is in interactive mode. If you set this property to False, Excel blocks all input from the keyboard and mouse (except input to dialog boxes that are displayed by your code). Read/write Boolean. NOTE: Not supported on macOS.

在 0.24.4 版被加入.

kill()

Forces the Excel app to quit by killing its process.

在 0.9.0 版被加入.

macro(name)

Runs a Sub or Function in Excel VBA that are not part of a specific workbook but e.g. are part of an add-in.

參數:

name (str) -- e.g., 'Module1.MyMacro' or 'MyMacro'

回傳型別:

Macro

範例

Function MySum(x, y)
    MySum = x + y
End Function

can be accessed like this:

>>> import xlwings as xw
>>> app = xw.App()
>>> my_sum = app.macro('MySum')
>>> my_sum(1, 2)
3

Types are supported too:

Function MySum(x as integer, y as integer)
    MySum = x + y
End Function

>>> import xlwings as xw
>>> app = xw.App()
>>> my_sum = app.macro('MySum')
>>> my_sum(1, 2)
3

However typed arrays are not supported. So the following won't work

Function MySum(arr() as integer)
    ' code here
End Function

See also: Book.macro

在 0.9.0 版被加入.

property path: str

Returns the path to where the App is installed.

在 0.28.4 版被加入.

property pid: int

Returns the PID of the app.

在 0.9.0 版被加入.

properties(**kwargs)

Context manager that allows you to easily change the app's properties temporarily. Once the code leaves the with block, the properties are changed back to their previous state. Note: Must be used as context manager or else will have no effect. Also, you can only use app properties that you can both read and write.

範例

import xlwings as xw
app = App()

# Sets app.display_alerts = False
with app.properties(display_alerts=False):
# do stuff

# Sets app.calculation = 'manual' and app.enable_events = True
with app.properties(calculation='manual', enable_events=True):
# do stuff

# Makes sure the status bar is reset even if an error happens in the with block
with app.properties(status_bar='Calculating...'):
# do stuff

在 0.24.4 版被加入.

回傳型別:

Generator[App, None, None]

quit()

Quits the application without saving any workbooks.

在 0.3.3 版被加入.

range(cell1, cell2=None)

Range object from the active sheet of the active book, see Range.

在 0.9.0 版被加入.

回傳型別:

Range

render_template(template=None, output=None, book_settings=None, **data)

This function requires xlwings PRO.

This is a convenience wrapper around mysheet.render_template

Writes the values of all key word arguments to the output file according to the template and the variables contained in there (Jinja variable syntax). Following variable types are supported:

strings, numbers, lists, simple dicts, NumPy arrays, Pandas DataFrames, pictures and Matplotlib/Plotly figures.

參數:

• template (str | PathLike[str] | None) -- Path to your Excel template, e.g. r'C:\Path\to\my_template.xlsx'

• output (str | PathLike[str] | None) -- Path to your Report, e.g. r'C:\Path\to\my_report.xlsx'

• book_settings (dict[str, Any] | None) -- A dictionary of xlwings.Book parameters, for details see: xlwings.Book. For example: book_settings={'update_links': False}.

• data (Any) -- All key/value pairs that are used in the template.

回傳型別:

Book

在 0.24.4 版被加入.

property screen_updating: bool

Turn screen updating off to speed up your script. You won't be able to see what the script is doing, but it will run faster. Remember to set the screen_updating property back to True when your script ends.

備註

On xlwings Server and xlwings Lite, screen updating can only be suspended until the next sync rather than turned off indefinitely, so the effect ends on its own before your script does. Setting it back to True is a no-op there, and reading the property isn't supported.

在 0.3.3 版被加入.

property selection: Range | None

Returns the selected cells as Range.

在 0.9.0 版被加入.

property startup_path: str

Returns the path to XLSTART which is where the xlwings add-in gets copied to by doing xlwings addin install.

在 0.19.4 版被加入.

property status_bar: str | bool

Gets or sets the value of the status bar. Returns False if Excel has control of it.

在 0.20.0 版被加入.

property version: VersionNumber

Returns the Excel version number object.

範例

>>> import xlwings as xw
>>> xw.App().version
VersionNumber('15.24')
>>> xw.apps[10559].version.major
15

在 0.9.0 版的變更.

property visible: bool

Gets or sets the visibility of Excel to True or False.

在 0.3.3 版被加入.