Python SDK Reference

Six functions, frozen for this release. Every SDK function accepts optional registry=/cache= overrides — see Architecture.

heepx.learn

heepx.learn(
    name: str,
    *,
    version: str | None = None,
    offline: bool = False,
    registry: Registry | None = None,
    cache: Cache | None = None,
) -> Capability

Loads a capability, downloading and caching it first if necessary. A version already in the cache is never re-downloaded.

warrant = heepx.learn("warrant")
heepx.learn("warrant", version="1.3.0")
heepx.learn("warrant", offline=True)  # never touches the network

heepx.search

heepx.search(query: str, *, registry: Registry | None = None) -> Sequence[SearchResult]

Matches against both the capability name and its description.

for result in heepx.search("assert"):
    print(result.name, "-", result.description)

heepx.info

heepx.info(name: str, *, registry: Registry | None = None) -> CapabilityInfo

Registry metadata for a capability, without downloading it.

meta = heepx.info("warrant")
print(meta.latest_version, meta.versions)

heepx.list

heepx.list(*, cache: Cache | None = None) -> Sequence[str]

The names of every capability currently in the local cache — what's installed, not what the registry offers (for that, use search).

heepx.verify

heepx.verify(
    name: str,
    *,
    version: str | None = None,
    cache: Cache | None = None,
) -> VerificationResult

Recomputes the fingerprint of a cached capability's files and compares it to what was recorded when it was downloaded — never touches the network.

result = heepx.verify("warrant")
if not result.ok:
    print(result.reasons)

heepx.update

heepx.update(name: str, *, registry: Registry | None = None, cache: Cache | None = None) -> Capability

Fetches the newest version of a capability and loads it — equivalent to learn with no version pinned.

Errors

Every exception is a heepx.HeepXError: CapabilityNotFoundError, VersionNotFoundError, RegistryError (and its NetworkError subclass), OfflineError, CorruptedCacheError, InvalidCapabilityError.