Python SDK how-to¶

The cloudsprite package is how scripts talk to your workspace. This page is the navigation and publish loop. Per-method signatures live in the SDK reference; for the zero-to-first-upload path, start with the Quickstart.

The library is a private beta and needs Python 3.11 or newer. Install the wheel from the URL in your invite, not PyPI:

pip install "cloudsprite[rf] @ https://cloudsprite-sdk-dist.s3.us-east-2.amazonaws.com/sdk/0.1.2/cloudsprite-0.1.2-py3-none-any.whl"
cloudsprite init

Drop [rf] if you do not need Touchstone / scikit-rf support.

Or export CLOUDSPRITE_API_KEY. Multi-org keys also need a default org:

import cloudsprite as cs

cs.connect()
cs.set_org("acme")
cs.set_team("rf-lab")

Prefer Client(api_key=..., org="acme", team="rf-lab") in libraries and notebooks so two sessions cannot clobber each other’s team/project.

Configuration¶

Credentials resolve in order: explicit Client(api_key=...) → CLOUDSPRITE_API_KEY → ~/.cloudsprite/config (written by cloudsprite init, owner-only permissions). Other environment variables:

Variable	Effect
`CLOUDSPRITE_API_KEY`	API key for scripts, CI, headless jobs
`CLOUDSPRITE_TIMEOUT`	HTTP timeout in seconds (single float, or connect/read pair)
`CLOUDSPRITE_NO_TELEMETRY=1`	Blanket opt-out of lineage extras: source upload, git state, error messages

Navigate¶

Hierarchy in the SDK:

org / team → project → dataset → traces
                       notebook

Nothing hits the network until you read data (.x, .y, iterate, .params, …). A typo in a bracket name shows up then, not at assignment.

ds = cs.projects["cable-qual"].datasets["sweep-25c"]
s21 = ds.traces["S21"]
x, y = s21.x, s21.y

Queries:

cs.projects["cable-qual"].datasets                  # all
cs.projects["cable-qual"].datasets["sweep-*"]       # glob on name
cs.projects["cable-qual"].datasets.filter(cs.params.temp > 25)

There is no collection-level datasets.traces["S21"] yet. Pull S21 per dataset.

Compute locally, publish back¶

cs.set_project("cable-qual")
cs.track_script(__file__)          # optional lineage — off until you call it
result = s21 * 0.5
result.name = "filtered"
cs.publish(traces=[result], name="filtered-results")

cs.track_script() may attach the script file to the published dataset. It does not run until you opt in. Use it for analysis you want to reproduce; skip it for throwaway REPL math.

scikit-rf¶

network = s21.to_trace().to_network()   # skrf.Network; needs cloudsprite[rf]

Use this when you need a full Network (mixed-mode conversion, cascading), then publish the traces you care about as a new dataset.

What not to do in customer scripts¶

Do not hard-code REST paths. Use cs.projects / ds.upload / cs.publish.
Do not put API keys in notebooks you will share. cloudsprite init or CI secrets.
Do not publish into a project you have not set. Failed publish is better than silent writes to the last set_project.