Errors and Exceptions¶

get_last_error¶

get_last_error(xl_cell)

When a Python function is called from an Excel worksheet, if an uncaught exception is raised PyXLL caches the exception and traceback as well as logging it to the log file.

The last exception raised while evaluating a cell can be retrieved using this function.

The cache used by PyXLL to store thrown exceptions is limited to a maximum size, and so if there are more cells with errors than the cache size the least recently thrown exceptions are discarded. The cache size may be set via the error_cache_size setting in the config.

When a cell returns a value and no exception is thrown any previous error is not discarded. This is because doing so would add additional performance overhead to every function call.

Parameters:: xl_cell – An XLCell instance or a COM Range object (the exact type depends on the com_package setting in the config.
Returns:: The last exception raised by a Python function evaluated in the cell, as a tuple (type, value, traceback).

Example usage:

from pyxll import xl_func, xl_menu, xl_version, get_last_error
import traceback


@xl_func("xl_cell: string")
def python_error(cell):
    """Call with a cell reference to get the last Python error"""
    exc_type, exc_value, exc_traceback = pyxll.get_last_error(cell)
    if exc_type is None:
        return "No error"

    return "".join(traceback.format_exception_only(exc_type, exc_value))


@xl_menu("Show last error")
def show_last_error():
    """Select a cell and then use this menu item to see the last error"""
    selection = xl_app().Selection
    exc_type, exc_value, exc_traceback = get_last_error(selection)

    if exc_type is None:
        xlcAlert("No error found for the selected cell")
        return

    msg = "".join(traceback.format_exception(exc_type, exc_value, exc_traceback))
    if xl_version() < 12:
        msg = msg[:254]

    xlcAlert(msg)

ErrorContext¶

class ErrorContext

An ErrorContext is passed to any error handler specified in the pyxll.cfg file.

When an unhandled exception is raised, the error handler is called with a context object and the exception details.

See Error Handling for details about customizing PyXLL’s error handling.

type

Type of function where the exception occurred.

Can be any of the attributes of the ErrorContext.Type class.

function_name

Name of the function being called when the error occurred.

This may be none if the error was not the result of calling a function (eg when type == ErrorContext.Type.IMPORT).

import_errors

Only applicable when type == ErrorContext.Type.IMPORT.

A list of (modulename, (exc_type, exc_value, exc_traceback)) for all modules that failed to import.

ErrorContext.Type:

Enum-style type to indicate the origination of the error.

UDF: Used to indicate the error was raised while calling a UDF.

MACRO: Used to indicate the error was raised while calling a macro.

MENU: Used to indicate the error was raised while calling a menu function.

RIBBON: Used to indicate the error was raised while calling a ribbon function.

IMPORT: Used to indicate the error was raised while importing a Python module.

ObjectCacheKeyError¶

class ObjectCacheKeyError(KeyError)

ObjectCacheKeyError is raised when attempting to retrieve an object from PyXLL’s object cache with an object handle missing from the cache.

See Cached Objects for details of how to pass Python objects between Python and Excel using PyXLL’s object cache feature.

SpillError¶

class SpillError(RuntimeError)

SpillError is raised when attempting to write Python data to Excel using XLCell.value that doesn’t fit in the target range, and would cause existing data to be overwritten if the target range was to be resized, and resizing is enabled.

Resizing occurs when the value being written is larger than the cells referenced by the XLCell instance and, either auto_resize=True is passed to XLCell.options, or when writing an Excel table (tables are always resized to fit the data being written).

« Tables

Utility Functions »