RTD
RTD is a base class that should be derived from for use by functions wishing to return real time ticking data instead of a static value.
See Real Time Data for more information.
value
Current value. Setting the value notifies Excel that the value has been updated and the new value will be shown when Excel refreshes.
connect
(self)Called when Excel connects to this RTD instance, which occurs shortly after an Excel function has returned an RTD object.
May be overridden in the sub-class.
@Since PyXLL 4.2.0: May be an async method.
XLCell
XLCell represents the data and metadata for a cell (or range of cells) in Excel.
XLCell instances are passed as an xl_cell
argument to a function registered with xl_func
, or
may be constructed using from_range
.
Some of the properties of XLCell
instances can only be accessed if the calling function has been registered as a macro sheet
equivalent function [1].
Example usage:
from pyxll import xl_func
@xl_func("xl_cell cell: string", macro=True)
def xl_cell_test(cell):
return "[value=%s, address=%s, formula=%s, note=%s]" % (
cell.value,
cell.address,
cell.formula,
cell.note)
value
Get or set the value of the cell.
The type conversion when getting or setting the cell content is determined by the type
passed to options
. If no type is specified then the type conversion
will be done using the var
type.
Must be called from a macro or macro sheet equivalent function [1]
address
String representing the address of the cell, or None
if a value was passed to the function and not a cell reference.
Must be called from a macro or macro sheet equivalent function [1]
formula
Formula of the cell as a string
, or None
if a value was passed to the function and not a cell reference or if the cell has no formula.
Must be called from a macro or macro sheet equivalent function [1]
note
Note on the cell as a string
, or None
if a value was passed to the function and not a cell reference or if the cell has no note.
Must be called from a macro or macro sheet equivalent function [1]
rect
XLRect
instance with the coordinates of the cell.
is_calculated
True or False indicating whether the cell has been calculated or not. In almost all cases this will always be True as Excel will automatically have recalculated the cell before passing it to the function.
options
(self[, type][, auto_resize][, type_kwargs][, nan_value][, posinf_value][, neginf_value])Sets the options on the XLCell instance.
Parameters: |
|
---|---|
Returns: | self. The cell options are modified and the same instance is returned, for easier method chaining. |
Example usage:
cell.options(type='dataframe', auto_resize=True).value = df
from_range
(range)Static method to construct an XLCell from an Excel Range instance. The ‘Range’ class is part of
the Excel Object Model, and can be obtained via xl_app
.
See Python as a VBA Replacement.
By getting an XLCell from a Range, values can be set in Excel using PyXLL type converters and object cache.
Parameters: | range – Excel Range object obtained via xl_app . |
---|
Example usage:
xl = xl_app()
range = xl.Selection
cell = XLCell.from_range(range)
cell.options(type='object').value = x
Must be called from a macro or macro sheet equivalent function [1]
XLRect
XLRect instances are accessed via XLCell.rect
to get the coordinates of the cell.
XLAsyncHandle
XLAsyncHandle instances are passed to Asynchronous Functions as the async_handle argument.
They are passed to xlAsyncReturn
to return the result from an asynchronous function.
set_value
(value)Set the value on the handle and return it to Excel.
Equivalent to xlAsyncReturn
.
@Since PyXLL 4.2.0
Example usage:
from pyxll import xl_func
import threading
import sys
@xl_func("async_handle h, int x")
def async_func(h, x):
def thread_func(h, x):
try:
result = do_calculation(x)
h.set_value(result)
except:
result.set_error(*sys.exc_info())
thread = threading.Thread(target=thread_func, args=(h, x))
thread.start()
New in PyXLL 4.2
For Python 3.5.1 and later, asynchronous UDFs can be simplified by simply using the async keyword on the function declaration and dropping the async_handle argument.
Async functions written in this way run in an asyncio event loop on a background thread.
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.
type
Type of function where the exception occurred.
Can be any of the attributes of the ErrorContext.Type
class.
Footnotes
[1] | (1, 2, 3, 4, 5, 6) A macro sheet equivalent function is a function exposed using xl_func with macro=True. |