The official Python client for the Codesphere API.
uv add codesphereEvery option can be passed directly to the constructor:
fromcodesphereimportCodesphereSDKsdk=CodesphereSDK(token="your-api-token")
# or, e.g. against a different deployment:sdk=CodesphereSDK(token="your-api-token", base_url="https://my-instance.example.com/api")Alternatively, configure via environment variables (or a .env file in your
project root). Explicit constructor arguments always win over the environment:
| Variable | Description | Default |
|---|---|---|
CS_TOKEN | API token (required) | – |
CS_BASE_URL | API base URL | https://codesphere.com/api |
If no token is provided at all, CodesphereSDK() raises an
AuthenticationError at construction (importing the package never requires
any environment variable).
Transient failures are retried automatically (2 retries by default).
Requests using an idempotent method (GET, HEAD, PUT, DELETE) are
retried on 429, 502, 503, and 504 responses as well as on
connect/timeout errors. The delay honors the server's Retry-After header
(seconds or HTTP-date) when present, otherwise exponential backoff with
jitter (backoff_factor * 2**attempt).
Tune or disable the behavior with a RetryConfig:
fromcodesphereimportCodesphereSDK, RetryConfigsdk=CodesphereSDK(
token="your-api-token",
retry=RetryConfig(max_retries=0), # disable retries entirely
)POST is never retried unless you add it to retry_methods explicitly
(only do this if your endpoints tolerate duplicate submissions):
RetryConfig(max_retries=3, retry_methods=frozenset({"GET", "POST"}))Platform instances enable different features. Inspect them via sdk.flags:
snapshot=awaitsdk.flags.get() # fetched once, then cachedifawaitsdk.flags.is_enabled("workspace-ssh"):
...
awaitsdk.flags.refresh() # re-fetch after platform changesSDK features that depend on a platform flag raise FeatureNotEnabledError
(or FeatureNotAvailableError if the instance doesn't have the feature at
all) before sending any request when the flag is off.
importasynciofromcodesphereimportCodesphereSDKasyncdefmain():
asyncwithCodesphereSDK() assdk:
teams=awaitsdk.teams.list()
forteaminteams:
print(f"{team.name} (ID: {team.id})")
asyncio.run(main())The same API is available without async/await — ideal for scripts and
tools that don't run an event loop:
fromcodesphere.syncimportCodesphereSDKwithCodesphereSDK() assdk:
teams=sdk.teams.list()
forteaminteams:
print(f"{team.name} (ID: {team.id})")Both flavors share the same request/response models, configuration, and
error types; only the entities with API methods (Workspace, Team, …)
exist per flavor.
teams=awaitsdk.teams.list()
team=awaitsdk.teams.get(team_id=123)
awaitteam.delete()workspaces=awaitsdk.workspaces.list(team_id=123)
workspace=awaitsdk.workspaces.get(workspace_id=456)
result=awaitworkspace.execute_command("ls -la")
print(result.output)
awaitworkspace.env_vars.set([{"name": "API_KEY", "value": "secret"}])
env_vars=awaitworkspace.env_vars.get()team=awaitsdk.teams.get(team_id=123)
domains=awaitteam.domains.list()
domain=awaitteam.domains.create(name="api.example.com")datacenters=awaitsdk.metadata.list_datacenters()
plans=awaitsdk.metadata.list_plans()
images=awaitsdk.metadata.list_images()git clone https://github.com/Datata1/codesphere-python.git
cd codesphere-python
uv sync --all-extras
uv run pytestMIT – see LICENSE for details.