Real Time Data¶

Please see Real Time Data in the User Guide for more details about writing RTD functions.

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.

Since PyXLL 5.12, when using Python 3.9 or later, the RTD type is a generic type and can be used in type hints as RTD[T], where T denotes the type of the value property.

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)[source]

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.

disconnect(self)[source]

Called when Excel no longer needs the RTD instance. This is usually because there are no longer any cells that need it or because Excel is shutting down.

May be overridden in the sub-class.

@Since PyXLL 4.2.0: May be an async method.

detach(self)[source]

Detatches the RTD instance from any Excel RTD functions.

After detaching, any subsequent calls to the Excel RTD function that created this object will result in the Python function be re-run.

See Restarting RTD Functions for more details.

@Since PyXLL 5.9.0

set_error(self, exc_type, exc_value, exc_traceback)[source]

Update Excel with an error. E.g.:

def update(self):
    try:
        self.value = get_new_value()
    except:
        self.set_error(*sys.exc_info())

class IterRTD(RTD)

IterRTD implements the RTD base class and wraps a Python iterator.

This class creates a background thread and iterates over the iterator in that thread. Each value yielded by the iterator is sent to Excel.

In Python 3.7 and above, the background thread is run in the same context as the calling thread (see contextvars in the Python documentation for details about contexts and context variables).

When writing an RTD generator (RTD Generators) this class is what is used to wrap the generator object into an RTD object.

__init__(iterator, auto_detach: bool = None)

Parameters:

iterator – A Python iterable object that will be iterated over.
auto_detach – If True, calls RTD.detach when then iterator is complete.

class AsyncIterRTD(RTD)

AsyncIterRTD implements the RTD base class and wraps a Python async iterator.

This class iterates over the async iterator in PyXLL’s asyncio event loop. Each value yielded by the iterator is sent to Excel.

In Python 3.7 and above, the background thread is run in the same context as the calling thread (see contextvars in the Python documentation for details about contexts and context variables).

When writing an RTD async generator (Async RTD Generators) this class is what is used to wrap the async generator object into an RTD object.

__init__(iterator, auto_detach: bool = None)

Parameters:

iterator – A Python async iterable object that will be iterated over.
auto_detach – If True, calls RTD.detach when then iterator is complete.

type RTDGenerator

New in PyXLL 5.12, requires Python 3.12+

RTDGenerator is a generic type alias that can be used as a type hint for RTD generators.

Using the RTDGenerator type avoids the need for a function signature to be used when registering an RTD generator with @xl_func.

See Using Type Hints.

from pyxll import xl_func, RTDGenerator
from typing import Any
import time

@xl_func
def my_rtd_generator(...) -> RTDGenerator[Any]:
    i = 0
    while True:
        i += 1
        yield i
        time.sleep(5)

type RTDAsyncGenerator

New in PyXLL 5.12, requires Python 3.12+

RTDAsyncGenerator is a generic type alias that can be used as a type hint for RTD async generators.

Using the RTDAsyncGenerator type avoids the need for a function signature to be used when registering an RTD async generator with @xl_func.

See Using Type Hints.

from pyxll import xl_func, RTDAsyncGenerator
from typing import Any
import asyncio

@xl_func
async def my_async_rtd_generator(...) -> AsyncRTDGenerator[Any]:
    i = 0
    while True:
        i += 1
        yield i
        await asyncio.sleep(5)

« Worksheet Functions

Macro Functions »