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-vision-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.

Notebooks

Four example notebooks ship inside the package:

python -m blobhub.notebooks list
python -m blobhub.notebooks copy onnx/super-resolution     # writes ./super-resolution.ipynb
pip install nbclient ipykernel && jupyter execute super-resolution.ipynb

From Python: blobhub.notebooks.list() and blobhub.notebooks.copy("onnx/super-resolution", dest="."). Each notebook installs its own dependencies in its first cell. Only onnx/super-resolution-end-to-end needs a credential.

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.2.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.2.0
File Size Uploaded Provenance Actions
blobhub-0.2.0.tar.gz 33.7 kB With provenance Details for blobhub-0.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 82.6 kB

Release files / blobhub-0.2.0.tar.gz

Download URL blobhub-0.2.0.tar.gz
Size 33.7 kB
Tags Source
SHA-256 checksum
How to use checksums
e4ef51b6e2677fae1a3549ac31dd8d48db20ac7eb7c1b5311e4c9ad8caad312b
BLAKE2b-256 checksum
How to use checksums
38288adb25b805fed36796f403d7bdd89eba74a65f52efd2166552a5cb7895e8
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 8, 2026.

Transparency log

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

Download URL blobhub-0.2.0-py3-none-any.whl
Size 48.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
08162e925a9324968598e2a27bcbe4012a6862fe437bdf9b1ac21d7e673a2c68
BLAKE2b-256 checksum
How to use checksums
29d13f0b76e09c22b56c79b9e17cc1c9aaae48915c1ca2faeab069911fc6ee5f
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 8, 2026.

Transparency log

Security for blobhub 0.2.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.2.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 8, 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