Skip to content

Latest commit

 

History

History
56 lines (44 loc) · 2.81 KB

python-api.md

File metadata and controls

56 lines (44 loc) · 2.81 KB

Python SDK

Direct metadata discovery and installed CLI (0.1.3)

Library.read_metadata(path, limits=Limits()) reads only the fixed header and YLSpec frame. Library.read_metadata_reader(size, reader, limits=Limits()) accepts exact byte ranges without a local plugin copy. Both return canonical TOML, retain no handle, and skip TOC/payload/signature validation. In contrast, Package.metadata follows an indexed open. See metadata-only reads.

Platform wheels also include the core and native CLI. Pip registers ylplugin in the environment scripts directory; python -m ylplugin works as well. See installation and PATH behavior. These APIs and CLI entry points are new in 0.1.3 and absent from 0.1.2.

ylplugin requires Python 3.11+. Version 0.1.3 platform wheels contain the native CLI and a ctypes runtime built from the same core. Source/facade-only installs require an installed SDK or explicit path. Published v0.1.0's facade-only wheel is preserved.

import json
from ylplugin import Library, Limits

sdk = Library()  # bundled runtime, YLPLUGIN_LIBRARY, or installed SDK
print(sdk.read_metadata("data.ylplugin"))  # no TOC or payload reads
with sdk.open("data.ylplugin", Limits(record=64 * 1024 * 1024)) as plugin:
    plugin.validate()
    print(json.loads(plugin.read("catalog.json"))["total"])

Use Library('/absolute/path/libylplugin.so') or YLPLUGIN_LIBRARY for local builds. Runtime/package versions must match. Nothing is downloaded at import. The package has a py.typed marker and annotations; native validation remains authoritative.

Library.create/sign and Package.metadata/inspect/targets/entrypoints/read/ read_slice/validate/verify/check/extract call the C ABI. Metadata is TOML text; reports are dictionaries/lists, integers preserve permission bits, resources are bytes. The SDK does not invent meanings for permission names or bits.

Keys/trust callbacks return exactly 32 bytes or None. Callback exceptions deny the key; cancellation exceptions cancel. Error.code is the native status. Unknown-profile target/entrypoint access raises the profile error rather than returning an empty list. Negative, bool, fractional and overflowing ranges/limits fail before ctypes can truncate them. Paths are UTF-8 without NUL.

A handle serializes operations and close with an RLock; callback close/reentry is rejected. Use context managers and separate handles for parallel I/O. Avoid cross-thread lock cycles in callbacks. User-owned Python key bytes cannot promise erasure. The SDK is a host library, not a Python execution adapter; SDK loading, preflight and plugin activation are separate trust decisions.

permission_bytes(target, optional=True) copies the native byte representation to Python bytes and rejects string/mask declarations; no decimal-string encoding is involved.