Function push

python/nemo_relay/scope.py:86–147

Push a new child scope and return its handle. Args: name: Human-readable name for the new scope. scope_type: Semantic scope type, such as ``ScopeType.Agent`` or ``ScopeType.Function``. handle: Optional parent scope handle. When omitted, the current

(
    name: str,
    scope_type: ScopeType,
    *,
    handle: ScopeHandle | None = None,
    attributes: ScopeAttributes | None = None,
    data: Json | None = None,
    metadata: Json | None = None,
    input: Json | None = None,
    timestamp: datetime | None = None,
)

def push(
    name: str,
    scope_type: ScopeType,
    *,
    handle: ScopeHandle | None = None,
    attributes: ScopeAttributes | None = None,
    data: Json | None = None,
    metadata: Json | None = None,
    input: Json | None = None,
    timestamp: datetime | None = None,
) -> ScopeHandle:
    """Push a new child scope and return its handle.

    Args:
        name: Human-readable name for the new scope.
        scope_type: Semantic scope type, such as ``ScopeType.Agent`` or
            ``ScopeType.Function``.
        handle: Optional parent scope handle. When omitted, the current
            top-of-stack scope becomes the parent.
        attributes: Optional native scope attributes attached to the emitted
            start event.
        data: Optional JSON application payload stored on the scope handle.
        metadata: Optional JSON metadata recorded on the scope start event.
        input: Optional JSON payload exported as the semantic scope input.
        timestamp: Optional timezone-aware ``datetime`` recorded as the handle
            start time and on the scope start event. When omitted, the current
            runtime time is used.

    Returns:
        ScopeHandle: Handle for the newly pushed scope.

    Notes:
        A scope stack is created automatically if the current context does not
        yet have one. ``timestamp`` must be a timezone-aware ``datetime``;
        strings and naive datetimes are rejected.

    Example::

        import nemo_relay

        with nemo_relay.scope.scope("parent", nemo_relay.ScopeType.Agent) as parent:
            handle = nemo_relay.scope.push(
                "worker",
                nemo_relay.ScopeType.Function,
                handle=parent,
                attributes=None,
                data={"step": 1},
                metadata={"source": "scope.push"},
            )
            nemo_relay.scope.pop(handle)
    """
    _ensure_scope_stack()
    return _native_push_scope(
        name,
        scope_type,
        handle=handle,
        attributes=attributes,
        data=data,