Skip to content

Python SDK

Cavanshirpro edited this page Nov 7, 2026 · 3 revisions

Python SDK

0.1.3 additions: direct metadata-only reads request only the 128-byte header and YLSpec frame. TOC, payload and signature regions are not read. Discovery returns unverified metadata; validation and host preflight remain separate. Python/npm now bundle the native CLI alongside the core; Java/Kotlin supply a Java CLI entry point. See core/CLI installation and PATH behavior. These additions are available from 0.1.3.

The ylplugin package is a typed ctypes facade over the native C ABI. It does not contain a second container parser or a Python plugin execution engine. Version 0.1.3 requires Python 3.11+ and supplies platform wheels with core and CLI.

python -m pip install ylplugin==0.1.3

Open, validate and read

import json
from ylplugin import Library, Limits

sdk = Library()
with sdk.open("data.ylplugin", Limits(record=64 * 1024 * 1024)) as plugin:
    plugin.validate()
    print(json.loads(plugin.read("catalog.json"))["total"])
    print(plugin.targets)
    print(plugin.permission_bytes(0, optional=True))

Library() discovers the bundled runtime, an explicit environment selection or an installed SDK. Use Library('/absolute/path/libylplugin.so') or YLPLUGIN_LIBRARY for source builds. The runtime and facade version must match; a newer source facade cannot load an older registry runtime merely because the C ABI number has not changed.

Operations and types

Library.create accepts manifest text/resource dictionaries and optional key/ cancellation providers. Library.sign accepts caller-owned PEM bytes. Package operations include metadata, inspection, targets/entrypoints, read, read_slice, permission_bytes, validate, verify, check and extract.

Metadata is public TOML text. Reports use Python dictionaries/lists. Integers remain exact Python int values, byte permissions return bytes, and resource reads return bytes. Decode JSON/text only when the resource's content requires it; a binary resource is not a Unicode string.

key = bytes.fromhex("00" * 32)  # illustrative test key, not a deployment key
def content_key(key_id):
    return key if key_id == "example-content" else None

with sdk.open("encrypted.ylplugin") as plugin:
    data = plugin.read("catalog.json", keys=content_key)

A real host obtains keys from its entitlement/key-management policy. Keys and trust providers return exactly 32 bytes or None. Python provider exceptions deny the key; cancellation exceptions request cancellation. Native failures are Error with the C status in code.

Ownership and concurrency

Use context managers or close explicitly. A handle serializes operations and close with an RLock; reentry/close from an active callback is rejected. Avoid cross-thread callback waits that require the same handle lock. Separate handles are appropriate for independently scheduled I/O.

The facade validates negative/fractional/bool/overflowing ranges before ctypes can narrow them. read_slice(path, offset, count) has no cancellation argument; full reads and validation do. In 0.1.3, plaintext validation uses bounded streaming hash checks; full read still returns the complete resource.

See the complete Python guide, performance and troubleshooting.

Clone this wiki locally