operations API

完整接口目录 · 插件运行时用法 · 工具包下载

模块说明

Native managed actions over the existing IPC dispatcher; no retries or tasks.

OperationIntent

@dataclass(frozen=True)
class OperationIntent

SDK 说明：

Prepare before IO and retain for reconciliation. Payloads may be sensitive.

该类型另有以下内部字段，参与数据类声明但不建议直接读写；创建对象时优先使用专题中的工厂方法：

_json: str = field(repr=False)

OperationIntent.payload

def payload(self)

SDK 说明：

Return an independent copy, including the original key and deadline.

OperationSubmissionError

class OperationSubmissionError(ProtocolError)

OperationSubmissionError.__init__

def __init__(self, intent, operation_id=None)

OperationSubmissionError.intent

self.intent

公开实例属性，在 __init__ 中设置。

OperationSubmissionError.operation_id

self.operation_id

公开实例属性，在 __init__ 中设置。

OperationSubmissionTimeout

class OperationSubmissionTimeout(TimeoutError)

OperationSubmissionTimeout.__init__

def __init__(self, intent)

另继承外部类型 TimeoutError；其通用方法不在本 SDK 目录中重复展开。

OperationSubmissionTimeout.intent

self.intent

公开实例属性，在 __init__ 中设置。

OperationWaitTimeout

class OperationWaitTimeout(TimeoutError)

OperationWaitTimeout.__init__

def __init__(self, operation_id)

另继承外部类型 TimeoutError；其通用方法不在本 SDK 目录中重复展开。

OperationWaitTimeout.operation_id

self.operation_id

公开实例属性，在 __init__ 中设置。

OperationCancellationUncertain

class OperationCancellationUncertain(ProtocolError)

OperationCancellationUncertain.__init__

def __init__(self, operation_id)

OperationCancellationUncertain.operation_id

self.operation_id

公开实例属性，在 __init__ 中设置。

operation_context

def operation_context(error: BaseException) -> tuple[OperationIntent | None, str | None]

SDK 说明：

Read execute's reconciliation context, including chained task cancellation.

Python 3.10 can replace CancelledError across a Task boundary and retain the
original in __context__. This helper reads that chain without changing it.

Operations

class Operations

SDK 说明：

Use with a ManagedPeer and capabilities.get's game session.

HostSession is installation metadata, not the game session. The caller owns
the peer and retains prepared intents before awaiting submit. Cancellation
or timeout of Python waiting never requests cancellation of a world action.
submit returns admission only. wait returns every terminal state, including
failed/unknown; inspect result.evidence before claiming world success.
Neither this object nor wait creates background tasks or owns a scheduler.

Operations.__init__

def __init__(self, peer, session)

Operations.prepare

def prepare(
    self,
    operation: str,
    arguments: dict,
    *,
    idempotency_key: str,
    deadline: str,
) -> OperationIntent

SDK 说明：

Snapshot a caller-chosen key and fixed deadline without IO.

Operations.submit

async def submit(self, intent: OperationIntent, *, timeout=10) -> str

SDK 说明：

Submit once. Explicitly reusing an intent is the caller's decision.

Definite IPC rejections propagate with their original code. Transport
failures and malformed admissions retain intent because acceptance may
already have happened. Never replace its key or infer that it was unsent.

Operations.get

async def get(self, operation_id: str, *, timeout=10) -> OperationReceipt

SDK 说明：

Read an owned operation; preserve completion and evidence verbatim.

Operations.execute

async def execute(
    self,
    intent: OperationIntent,
    *,
    submit_timeout = 10,
    timeout = 30,
    poll_interval = 0.05,
) -> OperationReceipt

SDK 说明：

Submit once, then return the unchanged terminal receipt.

Both budgets and the poll interval are validated before submission.
Exceptions retain their type/code and gain intent and operation_id
(None until admission is known), including asyncio cancellation. Use
operation_context for cancellation propagated across Task boundaries.
Waiting never cancels or retries the action. Persist intent before calling when
reconciliation must survive worker exit.

Operations.cancel

async def cancel(self, operation_id: str, *, timeout=10) -> CancellationReceipt

SDK 说明：

Explicit cancellation request, never proof that a dispatched effect stopped.

Operations.wait

async def wait(
    self,
    operation_id: str,
    *,
    timeout = 30,
    poll_interval = 0.05,
) -> OperationReceipt

SDK 说明：

Bound total waiting by one monotonic budget; no implicit cancel/retry.

Operations.peer

self.peer

公开实例属性，在 __init__ 中设置。

Operations.session

self.session

公开实例属性，在 __init__ 中设置。