pysdk

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 1, 2026 License: MIT, MIT Imports: 3 Imported by: 0

README

pig-sdk (Python)

Python SDK for building pig subprocess extensions.

This SDK is a language bridge into the same extension API that upstream pi exposes to TypeScript extensions: the wire protocol, register payload, tool/command/event semantics, request/response and host-call shapes are identical to the Go SDK (extensions/sdk) and the Rust SDK (extensions/sdk-rs). See docs/extension-api-parity.md for the host API parity matrix and docs/extension-runtime-cells.md for how factory extensions are packed into generated runner subprocesses.

Breaking changes in 0.3.0

Host-backed Context getters raise HostCallError on a host failure or a reply that lacks its field, and never return an empty value. get_session_name, get_session_file and get_leaf_id return None when absent, and get_branch and get_entries raise a failed session-log subscription. timeout options accept a float. See the migration tables in docs/site/docs/extensions.md.

Status

maturity: production bridge
runtime:  subprocess (no in-process, no WASM)
wire:      current Pig subprocess contract (no independent version)
host APIs implemented:
  full host-call bridge matching the Go SDK method set
declaration kinds implemented:
  tools
  commands
  event handlers
  shortcuts
  flags
  providers
  message renderers
  widgets / widget_push

The Python SDK is a first-class bridge into the same subprocess protocol as Go and Rust. When a new host API is added, update all SDKs and the parity matrix in the same change.

Authoring a factory extension

import pig_sdk


def new_extension() -> pig_sdk.Extension:
    ext = pig_sdk.Extension("my-py-ext")

    def hello(ctx: pig_sdk.Context, args: dict) -> dict:
        ctx.notify(f"hello, {args.get('name', 'world')}")
        return {"content": "ok"}

    ext.tool("hello", "Say hello", {"type": "object"}, hello)
    return ext


if __name__ == "__main__":
    new_extension().run()

Optional packing override:

kind: Extension
metadata:
  name: my-py-ext
spec:
  runtime:
    language: python
    isolation: shared-ok
    entrypoint:
      mode: factory
      package: my_py_ext
      factory: new_extension

Two or more factory-style Python extensions with isolation: shared-ok are automatically packed into a single generated runner subprocess by PlanCells (see docs/extension-runtime-cells.md).

Threading and cancellation

The SDK uses one reader thread plus one worker thread per in-flight request. Host calls from a handler block on a single shared write lock and use the reader thread to deliver call_result envelopes.

Each handler receives a Context exposing cooperative cancellation:

def slow_tool(ctx, args):
    for chunk in stream():
        if ctx.is_cancelled():
            return {"content": "", "is_error": True}

Cancellation is cooperative; a handler that never checks it will run until the process exits or shuts down.

Terminal strings

on_terminal_input receives strings with the same UTF-16 units as Pi. A high or low surrogate can arrive without its partner. Python str retains that unit, and the SDK's JSON encoder sends it as a standard \u escape. Return it directly in TerminalInputResult(data=...). Do not encode it to UTF-8 yourself or replace it with U+FFFD. Callback order and cancellation are unchanged.

Development

cd extensions/sdk-py
uv run python -m ast pig_sdk/__init__.py >/dev/null
uv run pytest

License

MIT: see LICENSE.

Documentation

Overview

Package pysdk carries the Python extension SDK sources so an installed pig can stage a buildable copy to disk. See extensions/sdk/bundle.go for the rationale; this is the Python analogue. The Python SDK is not a Go package, so this small Go file colocated with it provides the embed. Staging writes these files under <config-root>/state/pigsdk/sdk-py so packed Python cells resolve the SDK on a clean host (findPythonSDKRoot's staged-source strategy).

Index

Constants

This section is empty.

Variables

View Source
var Source embed.FS

Functions

func BundledFiles

func BundledFiles() []string

BundledFiles lists the embedded files, relative to the SDK root, in a stable order. Paths use forward slashes; a stager recreates subdirectories.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL