HomeCloud SDK
Polyglot SDK for HomeCloud — Python at the repo root (pip install homecloud-sdk), Node.js under js/ (@homecloud-platform/sdk).
Parity goal: both languages expose the same HomeCloud capabilities and ship on the same v* tag. Track gaps in js/PARITY.md. Node is MVP today (STS / Functions-first); full surface is the committed target.
Auth model (cloud-style)
| Who | How | MFA |
|---|---|---|
| SDK / automation | Access Key ID + Secret (SigV1 data plane) | Never on requests |
| CLI / humans | homecloud login → console JWT |
At login / step-up only |
Access Keys are created once in the Console (human + MFA there). Runtime SDK calls do not re-prompt MFA.
from homecloud import HomeCloud
# Recommended — explicit credentials (CI / servers)
client = HomeCloud(
access_key="HCAK...",
secret_key="...",
)
# Or environment (HOMECLOUD_* / HC_*)
client = HomeCloud.from_env()
# Or ~/.homecloud/credentials (+ optional HC_PROFILE)
client = HomeCloud()
# Data plane — Access Key only, no login
client.so.upload("docs", "./file.txt", key="a.txt")
client.mq.send("orders", {"id": 1})
# Interactive helpers only (CLI/tools) — may involve MFA
# client.login("alice", "…")
# client.login_browser()
Node.js (@homecloud-platform/sdk)
const { HomeCloud } = require("@homecloud-platform/sdk");
const client = HomeCloud.fromSts(context.sts.archive, {
accountId: context.account_id,
});
await client.so.putJson("docs", "a.json", { ok: true });
See js/README.md. Same STS / mailapi rewrite rules as Python ≥0.4.9.
Publish Node via the same tag as Python: v0.5.0 runs PyPI + npm together.
See js/README.md and ./scripts/bump-version.sh.
Async
from homecloud import AsyncHomeCloud
async with AsyncHomeCloud.from_env() as client:
meta = await client.so.head_object("docs", "a.txt")
await client.mq.send("orders", {"id": 1})
from homecloud_sdk import … still works (compatibility). Prefer from homecloud import ….
Errors
HTTP failures raise typed subclasses of HomeCloudError (catch specific types or the base):
| Type | Typical status |
|---|---|
NotFoundError |
404 (bucket / object / queue) |
UnauthorizedError |
401 |
PermissionDeniedError |
403 |
BadRequestError |
400 |
ConflictError |
409 |
RateLimitError |
429 |
ServiceUnavailableError |
502–504 |
ApiError |
other HTTP errors |
from homecloud import HomeCloud, NotFoundError, HomeCloudError
client = HomeCloud()
try:
client.so.head_object("docs", "a.txt")
except NotFoundError as exc:
print(exc.resource_type, exc.resource, exc) # object / docs/a.txt / …
except HomeCloudError as exc:
print(exc.status_code, exc)
Architecture
homecloud/ ← preferred public import (Python)
homecloud_core/ ← auth, routing, signing, sessions, MFA helpers
homecloud_sdk/ ← HomeCloud + AsyncHomeCloud
js/ ← @homecloud-platform/sdk (Node.js 20+)
CLI (homecloud-cli) is a Typer/Rich wrapper; it opts into interactive_mfa=True on the sync client.
Install
pip install homecloud-sdk
Until PyPI is configured, use a Git checkout or sibling editable install:
pip install -e "../homecloud-sdk"
PyPI publish is wired via .github/workflows/publish-pypi.yml (tag v* + Trusted Publishing).
npm publish is wired via .github/workflows/publish-npm.yml (same v* tag → aligned versions).
./scripts/bump-version.sh 0.5.0
# commit, push, then:
git tag v0.5.0 && git push origin v0.5.0
Operations by plane
| API | Auth | Notes |
|---|---|---|
so.upload / download / sync_* / list_objects / delete |
Access Key | Primary SDK path |
so.head_object (object_metadata) |
Access Key | Metadata only — no object body (AWS HeadObject) |
so.get_object_uri |
Access Key | so:// + public HTTPS URL |
so.generate_presigned_url |
Access Key | Time-limited GET URL |
mq.send / receive |
Access Key | Primary SDK path |
account_id() |
Access Key whoami | No JWT |
so.list_buckets / create_bucket |
Console JWT | Management helper |
queues.list / apps.list / accounts.* |
Console JWT | Management helper |
Async mirrors the same surface on AsyncHomeCloud (await client.so.…).
Configuration
| File | Purpose |
|---|---|
~/.homecloud/credentials |
Access Keys (multi-profile JSON) |
~/.homecloud/session |
Console JWT (interactive only) |
Profile / env
- Constructor
profile=/access_key_id=… HOMECLOUD_PROFILE/HC_PROFILE- credentials
default_profile default
| Variable | Short | Effect |
|---|---|---|
HOMECLOUD_PROFILE |
HC_PROFILE |
Active profile |
HOMECLOUD_ACCESS_KEY_ID |
HC_ACCESS_KEY_ID |
Access key |
HOMECLOUD_SECRET_ACCESS_KEY |
HC_SECRET_ACCESS_KEY |
Secret |
HOMECLOUD_ACCOUNT_ID |
HC_ACCOUNT_ID |
Optional account |
HOMECLOUD_APEX |
HC_APEX |
Platform domain |
Development
pip install -e ".[dev]"
pytest tests/ -q
pytest tests/test_live_integration.py -q # needs Access Keys in ~/.homecloud
cd js && npm test
Service-account verification (pre-PyPI)
Mints a dedicated Access Key named homecloud-sdk-test (requires a one-time
homecloud login to create the key), then runs a clean subprocess with
HomeCloud.from_env() — no JWT session, no MFA, no browser:
python scripts/verify_service_account_flow.py
Expected: PASS: service-account flow works without login/JWT/MFA/browser.
1 maintainer
Metadata
1 maintainer
Release files for homecloud-sdk 0.5.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 | |
|---|---|---|---|---|
| homecloud_sdk-0.5.0.tar.gz | 45.6 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| homecloud_sdk-0.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 89.2 kB
Release files / homecloud_sdk-0.5.0.tar.gz
| Download URL | homecloud_sdk-0.5.0.tar.gz |
|---|---|
| Size | 45.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ca9d35a149b1e3abc307e085086d4e355c4ff3ffeddb2f0d9e3577fd473b5d21
|
|
BLAKE2b-256 checksum How to use checksums |
2ce82e7d9a259706c1d6c64d2994bd0ffd70c49220d12351b795adda0df380da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.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 Jul 23, 2026.
Transparency logRelease files / homecloud_sdk-0.5.0-py3-none-any.whl
| Download URL | homecloud_sdk-0.5.0-py3-none-any.whl |
|---|---|
| Size | 43.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0278521d179cc505361118e8cf947b4bdce2ac88b931c6ae0770e29945127001
|
|
BLAKE2b-256 checksum How to use checksums |
0833e1966c8896bcc12cf3c1c4d7cdcd7559caf776ae9f65fa9e075dc66d0fc6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.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 Jul 23, 2026.
Transparency logSecurity for homecloud-sdk 0.5.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
All 2 files in this release have been uploaded with provenance metadata.
Attestation for homecloud_sdk-0.5.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 Jul 23, 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.
