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 loginstores 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 withapi_key=orprofile=it raisesValueError.hub.identitysays 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.