Introduction

The blobhub Python SDK: install it, connect, and read your first blob

blobhub is the Python SDK for BlobHub. It reads and writes blobs and their revisions, runs any blob type’s data commands, and has typed modules for the three types you are most likely to drive from Python: ONNX models, OrientDB graphs and workflows. Four example notebooks ship inside the package.

It is a synchronous client for the REST API. Nothing it does needs an endpoint of its own: every call goes through the public REST API, with the credential you connect with.

Install

pip install blobhub

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

This documents blobhub 0.2, a rewrite. Code written for 0.1.x does not run against it, and 0.1.x cannot reach the current API at all; see Migrating from 0.1.x.

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 takes its API key from the first place that has one: the api_key= argument, the BLOBHUB_API_KEY environment variable, or a profile that blobhub login stored in ~/.blobhub/credentials.yaml. With none of them, it reads as an anonymous visitor. Credentials and profiles has the full order and its rules.

hub.identity says where the key came from and which API the client talks to. It never shows the key itself. hub.whoami() returns your user record, or None for an anonymous client.

Read a public model

Public content needs no account. connect(anonymous=True) ignores any stored profile and reads as an anonymous visitor, so this runs on any machine:

import blobhub
from blobhub.types.onnx import Onnx

hub = blobhub.connect(anonymous=True)
revision = hub.blob("onnx-vision-models", "super-resolution").revision()
model_path = Onnx(revision).download()   # model.onnx, cached under ~/.cache/blobhub

hub.blob() takes an organization and a blob, each an alias or an id. revision() with no argument is the blob’s default revision. Onnx is the typed module for ONNX blobs, and download() returns the local path of the model.

What is in the package

Module	What it holds	Page
blobhub	connect, Client, Blob, Revision, Operation	Blobs and revisions
blobhub.types.onnx	Onnx, Artifact for blobhub.model.onnx blobs	ONNX
blobhub.types.orientdb	Graph, GraphResult for blobhub.graph.orientdb blobs	Graph
blobhub.types.workflow	Workflow, Execution for blobhub.compute.workflow blobs	Workflow
blobhub.notebooks	list, copy, and python -m blobhub.notebooks	Notebooks
blobhub.errors	BlobHubError and its subclasses	Errors and retries

The generic layer works with every blob type. A typed module is a view over one revision of one type, and it uses nothing below that revision. A type with no module of its own, such as a scheduler blob, is still reachable through the revision’s data channel, revision.query() and revision.command().

What it does not do

• No async client and no WebSocket. Waiting is polling. For live events, use the WebSocket API.
• No login. The SDK reads profiles and never writes them. blobhub login, from blobhub-cli, stores them.
• No organization or blob administration in its public API: creating and deleting blobs, API keys and members. hub.request() reaches those routes when you need them.
• No workflow authoring. Writing and deploying definitions is blobhub-cli’s job. The SDK runs what is deployed.

Next steps

Credentials and profiles

Where the SDK finds its key, and how to read public content without one.

Blobs and revisions

The generic layer: blobs, revisions, the data channel and operations.

Notebooks

Four example notebooks, copied out of the package in one command.

Errors and retries

What each error means, and which requests the SDK repeats.