duck.html.components.core.system

Manages the registration and lifecycle of HTML components, and enables communication with the browser via WebSocket to dispatch events and execute JavaScript in real-time.

Module Contents

Classes

LivelyComponentSystem

LivelyComponentSystem class.

API

class duck.html.components.core.system.LivelyComponentSystem

LivelyComponentSystem class.

OWNER_COOKIE_KEY: str

‘_lively_owner’

The cookie key to set in response when owner token is set.

OWNER_TOKEN_MAX_AGE: float

3600

The maximum seconds for the owner token to last.

OWNER_TOKEN_NBYTES: int

16

Number of bytes for the Lively owner token registration.

OWNER_TOKEN_REQUEST_KEY: str

‘LIVELY_OWNER_TOKEN’

Key to set in request.META when owner token is generated.

classmethod add_to_registry(uid: str, component: duck.html.components.Component) → None

Add a component to the internal Lively registry.

For the first component registered under a given root_uid (which must be the root component itself), this also mints a cryptographically random owner token and binds it to the component’s request. The WebSocket layer later checks incoming dispatch_component_event calls against this token to confirm the connection actually owns that root_uid before touching anything in the registry.

Parameters:

• uid – The unique identifier for the component within its root tree.

• component – The component instance to register.

Raises:

• ComponentSystemError – If component isn’t a Component; if the first-ever registration under a fresh root_uid is not the root component; or if a root component has no request bound to it.

• AlreadyInRegistry – If a root component is registered twice under the same UID.

classmethod get_from_registry(root_uid: str, uid: str, default: Optional[Any] = None) → Optional[duck.html.components.Component]

Retrieve a component from the registry using its UID.

Parameters:

• root_uid – The UID of the root component group.

• uid – The unique identifier of the component.

• default – The value to return if the component is not found.

Returns:

The component if found, otherwise the default value.

Return type:

Component | Any

classmethod get_html_tags() → List[duck.html.components.templatetags.ComponentTag]

Returns loaded HTML component template tags defined in settings.py.

Raises:

ComponentSystemError – If any component cannot be imported or instantiated.

classmethod get_owner(root_uid: str, entry: Optional[Tuple[str, Dict[str, duck.html.components.Component], Optional[float]]] = None) → Optional[str]

Get the owner token bound to a root_uid, lazily expiring it first if needed.

If the root_uid’s component tree has been disconnected (via mark_disconnected) for longer than OWNER_TOKEN_MAX_AGE, the entry is deleted and treated as gone rather than being returned. This enforces a time-bounded expiry without a background sweep task – the check simply runs on whatever access happens to come in next (a reconnect attempt, a dispatch call, etc.).

Parameters:

• root_uid – The root component’s UID to look up.

• entry – An already-fetched (owner_token, root_registry, disconnected_at) tuple for this root_uid, if the caller has one on hand (e.g. from a prior cls.registry.get(root_uid)). Pass this to avoid a redundant registry lookup. If omitted, it’s fetched here.

Returns:

The owner token if the entry exists and hasn’t expired, else None.

classmethod get_urlpatterns() → List[duck.urls.URLPattern]

Returns the appropriate URL patterns for the whole system.

classmethod get_websocket_view_cls() → Type

Returns the WebSocket view class responsible for handling communication between the server and the client, including event dispatching.

Returns:

The WebSocket view class used for client communication.

Return type:

Type

classmethod is_active() → bool

Returns boolean on whether the component system is active.

classmethod mark_connected(root_uid: str) → None

Mark a root_uid’s component tree as having an active WebSocket connection.

Clears any pending disconnect timestamp, so the entry is treated as alive indefinitely for as long as the connection stays open – expiry only starts counting again after the next mark_disconnected.

Parameters:

root_uid – The root component’s UID whose WebSocket just connected.

classmethod mark_disconnected(root_uid: str) → None

Mark a root_uid’s component tree as having lost its WebSocket connection.

Stamps the current time so that a subsequent get_owner call can lazily expire this entry once OWNER_TOKEN_MAX_AGE has elapsed since disconnect, giving the client a grace period to reconnect (e.g. after a sleep/wake or brief network drop) before the entry is discarded.

Parameters:

root_uid – The root component’s UID whose WebSocket just disconnected.

registry: duck.utils.caching.InMemoryCache

‘InMemoryCache(…)’

Mapping of UIDs to components.

Format: {root_uid: (owner_token, {root_uid: component, child_uid: component, …}, disconnected_at)}