bootstack.streams.Stream#

class bootstack.streams.Stream(owner, *, _source=None, _scheduler=None)#

Bases: Generic[T]

A composable push-stream for widget events.

Created by widget.on(event) (no handler). Chain operators to transform or filter events, then call .listen(handler) to attach a handler and activate the upstream event binding.

Usage:

# Simple — bind immediately, return Subscription
sub = widget.on("change", handler)

# Composed — lazy bind, activated by .listen()
sub = (
    widget.on("change")
    .debounce(300)
    .filter(lambda e: len(e.value or "") > 1)
    .listen(on_search)
)

sub.cancel()   # detach handler and remove the event binding

All operator methods return a new Stream — they do not consume the original. .listen() is the only terminal; it activates the binding and returns a cancellable handle.

Parameters:

owner (tk.Misc) – Widget used for timer scheduling (debounce/throttle delays).
_source (Optional[Callable[[Callable[[T], Any]], AnySubscription]]) – Internal — callable that, given a downstream handler, installs the upstream binding and returns a handle.

debounce(ms)#

Emit after ms milliseconds of silence — resets on each new value.

Useful for search-as-you-type: only fires after the user stops typing.

Parameters:: ms (int) – Quiet period in milliseconds before emission.
Returns:: New stream emitting debounced values.
Return type:: Stream[T]

delay(ms)#

Re-emit each value after a fixed ms millisecond delay.

Parameters:: ms (int) – Delay in milliseconds applied to each value.
Returns:: New stream emitting delayed values.
Return type:: Stream[T]

filter(pred)#

Emit only values for which pred(value) is True.

Parameters:: pred (Callable[[T], bool]) – Predicate — values returning False are dropped.
Returns:: New stream emitting only matching values.
Return type:: Stream[T]

listen(handler)#

Attach handler and activate the upstream event binding.

This is the only terminal operator. Returns a cancellable handle — call .cancel() to detach the handler and clean up all resources (event binding, pending timers) in the operator chain.

Parameters:: handler (Callable[[T], Any]) – Callable invoked for each event value.
Returns:: Cancellable handle.
Return type:: Subscription | Handle

map(fn)#

Transform each event value through fn.

Parameters:: fn (Callable[[T], U]) – Mapping function applied to each value.
Returns:: New stream emitting transformed values.
Return type:: Stream[U]

tap(fn)#

Call fn for side-effects on each value; forward value unchanged.

Parameters:: fn (Callable[[T], Any]) – Side-effect function (result is ignored).
Returns:: New stream emitting the original values.
Return type:: Stream[T]

throttle(ms)#

Emit at most once per ms milliseconds (leading edge).

Parameters:: ms (int) – Minimum interval between emissions in milliseconds.
Returns:: New stream emitting throttled values.
Return type:: Stream[T]