Skip to main content

BlobHub Python SDK

blobhub is the Python SDK for BlobHub, a platform for versioned blobs: ONNX models, graphs, workflows and more. It reads and writes blobs and their revisions, runs any blob type's data commands, and has typed modules for ONNX models, OrientDB graphs and workflows.

Install

pip install blobhub

Python 3.10 or newer. The only dependencies are httpx and PyYAML.

Connect

import blobhub

hub = blobhub.connect()
print(hub.identity)        # Identity(source='profile:work', api_url='https://api.blobhub.io/v1')

connect() makes no network call. It resolves each value from the first source that has it:

Value 1 2 3 4
profile name profile= BLOBHUB_PROFILE the file's default: none
API key api_key= BLOBHUB_API_KEY the profile's key an anonymous token
API URL api_url= BLOBHUB_API_URL the profile's url https://api.blobhub.io/v1
  • Profiles are the ones blobhub-cli's blobhub login stores in ~/.blobhub/credentials.yaml. The SDK reads that file and never writes it. A file readable by group or other is refused: chmod 600 ~/.blobhub/credentials.yaml.
  • blobhub.connect(profile="work") picks a profile; blobhub.connect(api_key="…") passes a key directly.
  • blobhub.connect(anonymous=True) reads public content with no credential at all, and ignores the profile file. Combined with api_key= or profile= it raises ValueError.
  • hub.identity says where the key came from. The key itself is never printed, logged or put in an error.

A short tour

blob = hub.blob("onnx-models", "super-resolution")    # org and blob, each an alias or an id
blob.type, blob.visibility, blob.default_revision_id

rev = blob.revision()                    # the default revision; blob.revision("<id>") for another
for r in blob.revisions():               # every revision, newest first
    print(r.id, r.phase, r.status)

rev.query("describe")                    # any read the blob's type supports
rev.command("<command>", key="value")    # any write; arguments set to None are left out

Revisions

draft = blob.create_revision("retrain")  # needs a committed default revision; waits until ready
draft.commit("v2")                       # waits until committed

ONNX models

from blobhub.types.onnx import Onnx

model = Onnx(rev)                        # or rev.typed()
model.artifacts()                        # [Artifact(path='model.onnx', size=…), …]
path = model.download()                  # model.onnx, cached under ~/.cache/blobhub
model.download("model.tar.gz", dest="./model.tar.gz")
model.topology()                         # the graph without its weights

operation = Onnx(draft).upload("super_resolution.onnx")   # packs, uploads, waits for processing

A committed revision's download is cached and reused; a draft's is fetched again each time. Large files move in parts over presigned URLs, and an upload that fails part-way is cancelled.

Graphs

from blobhub.types.orientdb import Graph

graph = Graph(rev)                       # or rev.typed() for a blobhub.graph.orientdb blob
result = graph.execute("SELECT FROM V WHERE name = :name", {"name": "fox"})
result.vertices, result.edges            # OrientDB records, each with its "@rid" and "@class"
graph.execute("CREATE VERTEX V SET name = 'fox'", write=True)

A read runs one SELECT, TRAVERSE or MATCH statement; anything else needs write=True, which a committed revision refuses with Conflict. Parameters are a dict for :name placeholders or a list for ?. A statement returns at most 50 records. When OrientDB rejects a statement, the CommandError message gives its reason.

Workflows

from blobhub.types.workflow import Workflow

question = {"type": "message", "message": {"role": "user", "content": [{"type": "text", "text": "Why?"}]}}
run = Workflow(rev).execute(             # or rev.typed() for a blobhub.compute.workflow blob
    "summarize",                         # a definition alias or id, or "<org>/<blob>/<revision>/<definition>"
    input_data={"question": question},   # component alias to value
    session="sdk-demo",                  # an alias, created when absent, or an id; None starts a fresh session
)
print(run.id, run.session_id, run.url)   # url opens the execution in blobhub.io's debugger
# run.stop()                            # while it runs, instead of waiting: only a running execution stops
status = run.wait(timeout=900, on_event=print)   # "completed", "failed" or "stopped"
for event in run.events():               # the whole event log, oldest first
    print(event["type"], event.get("message"))

execute returns as soon as the execution exists. An input value reaches the workflow's data component whose alias port names it and whose persistence is execution. A session that is not open is refused with Conflict before anything is created. wait gives up with WaitTimeout and leaves the execution running. Writing and deploying definitions is blobhub-cli's job.

Errors

Every error is a blobhub.BlobHubError carrying the server's error code, a message and the HTTP status: AuthError (401), PermissionDenied (403, also answered for many missing resources), NotFound (404), Conflict (409, e.g. revision_not_writable), RateLimited (429), ServerError (5xx), NetworkError and its subclass RequestNotSent, CommandError, ConfigError, TypeMismatch, OperationFailed and WaitTimeout. When the client found no key and fell back to an anonymous token, an AuthError or PermissionDenied message says so. When the server's failure carries a details list, the error keeps it in details.

Reads are retried on throttling, server errors and network failures. Writes are retried only when the failure proves the request never ran, so a retry can never repeat a write.

Raw requests

hub.request("GET", f"revisions/{rev.id}/metadata/readme")

Migrating from 0.1.x

0.1.x cannot talk to the current API, so there is no compatibility layer.

0.1.x 0.2
Blob(org_id, blob_id, api_key=…) from blobhub.blob blobhub.connect(api_key=…).blob(org, blob)
blob.revisions.latest() blob.revision() (the default revision)
revision["status"], revision[Revision.FIELD_PHASE] revision.status, revision.phase
from blobhub.presets.onnx import Onnx, Model from blobhub.types.onnx import Onnx
onnx.upload(Model.from_local_file(onnx, path)) returns True onnx.upload(path) returns an Operation
onnx.download() returns a Model; model.path onnx.download() returns a Path
models stored under ~/.blobhub/ models cached under ~/.cache/blobhub/revisions/<revision>/
CallFailure, BadRequest, Forbidden the classes in blobhub.errors

License

MIT

Metadata

Release files for blobhub 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for blobhub 0.3.0
File Size Uploaded Provenance Actions
blobhub-0.3.0.tar.gz 26.7 kB With provenance Details for blobhub-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for blobhub 0.3.0
File Interpreter ABI Platform Actions
blobhub-0.3.0-py3-none-any.whl Python 3 none any Details for blobhub-0.3.0-py3-none-any.whl

Total release size: 64.7 kB

Release files / blobhub-0.3.0.tar.gz

Download URL blobhub-0.3.0.tar.gz
Size 26.7 kB
Tags Source
SHA-256 checksum
How to use checksums
206056b2b0ea2a69219b2d676911ab2559ac0f73dd15ddfc548d80e50026ab09
BLAKE2b-256 checksum
How to use checksums
40865cdf674fd842695a5ed4a9fbb0ce9a4cbd126cc405bde3556e2cbf147f8d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.

Transparency log

Release files / blobhub-0.3.0-py3-none-any.whl

Download URL blobhub-0.3.0-py3-none-any.whl
Size 38.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
31125f20eb2c2afb38464940f62989f4d423ce1270ffd2b601a2bcc009e4aa33
BLAKE2b-256 checksum
How to use checksums
5bed21a936319982c12414f5d37f6abfce4194a86834391c42890845af87f24a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.

Transparency log

Security for blobhub 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for blobhub-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page