standcloud-integration

Русская версия: README.ru.md

standcloud-integration — a Python SDK for exporting specialized test reports from the StandCloud service via its public API. An optional command-line interface ships alongside the SDK.

License

MIT

Requirements

• Python 3.11+
• A StandCloud API key — generate one in the portal at https://standcloud.everypin.io → Settings → API Keys.

Installation

Install the SDK from PyPI:

pip install standcloud-integration

This gives you the library itself — the StandCloudClient client, the typed models, and helpers for building reports — with a minimal set of dependencies and no CLI framework.

If you also need the standcloud-integration command-line tool, install it together with the cli extra:

pip install 'standcloud-integration[cli]'

Authentication

SDK. The client is authenticated only by the key you give it:

client = StandCloudClient(api_key)   # sent as Authorization: Bearer <key>

It does not read the environment or prompt for anything: deciding where to get the key is your application's job. An empty key raises ValueError immediately.

CLI. The standcloud-integration command finds the key itself, in this order:

1. the --api-key <KEY> option;
2. the STANDCLOUD_API_KEY environment variable (recommended);
3. an interactive secure prompt if the first two are not set.

export STANDCLOUD_API_KEY="ak_..."

Prefer passing the key via the environment variable rather than --api-key: command-line arguments can leak into your shell history and the process list.

Using the SDK

A report is a transformation of StandCloud API data into typed report records. TestRun is one of the API's models; a given report works with the models it needs.

from standcloud_integration import StandCloudClient
from standcloud_integration.reports.devices_with_last_stage import (
    DEVICES_WITH_LAST_STAGE_REPORT,
    DevicesWithLastStageRecord,
)

sc_client = StandCloudClient(api_key)
runs = sc_client.get_test_runs(part_number="ACME-CTRL-001 Rev A")

records: list[DevicesWithLastStageRecord] = DEVICES_WITH_LAST_STAGE_REPORT.build(runs)
# records is typed data — plot it, load it into pandas, write your own CSV, …

Each bundled report is a Report pairing a builder with its record type (the full list is standcloud_integration.reports.REPORTS). Writing files is not the SDK's job — it only returns the built report. A complete, runnable example (with a plain-csv writer) is in examples/custom_report.py; to create your own report, see docs/en/writing-reports.md.

The SDK logs through the standard logging module under the standcloud_integration logger and installs no handlers of its own. To surface request traces and warnings, attach your own handler — one logging.basicConfig() call is enough; see writing-reports.md.

Command-line interface (optional)

If the cli extra is installed, the package adds the standcloud-integration command (short alias sci):

standcloud-integration [GLOBAL OPTIONS] <report> [REPORT OPTIONS]

Global options come before the report name:

Option	Env variable	Default	Description
--api-key	STANDCLOUD_API_KEY	— (prompted)	API key. If omitted, taken from the env variable or a secure prompt.
--timeout	—	30.0	HTTP request timeout in seconds.
-v, --verbose	—	off	Print DEBUG logs (request traces) to stderr.
-h, --help	—	—	Show help.
--version	—	—	Show the package version.

List reports and options with --help:

standcloud-integration --help

A report's own options come after its name.

Report help:

standcloud-integration devices-with-last-stage --help

Example query:

standcloud-integration \
    devices-with-last-stage \
    --part-number "ACME-CTRL-001 Rev A" \
    -o devices.csv

Reports

For now the package ships a single example report, devices-with-last-stage. Its options and output format are described in docs/en/reports.md.

If you need your own report type, see the development docs.

Development

This project uses the uv package manager.

Linux, macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

macOS:

brew install uv

Windows

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

The installer places uv in %USERPROFILE%\.local\bin and adds that directory to PATH, but your current PowerShell session does not know about it yet. Close and reopen the PowerShell window — after that the uv command becomes available. Verify with: uv --version.

If uv is still not found after reopening, add the directory to PATH manually:

$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"

The command above only affects the current session. To make it permanent:

[Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\.local\bin;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")

Set up the environment and run the tooling:

uv venv .venv                   # create the virtual environment
source .venv/bin/activate        # activate it
uv sync --group dev              # install the package (with the cli extra) + dev tools
uv run standcloud-integration --help   # run the CLI from the source checkout

uv run pytest              # run the tests
uv run ruff check          # lint
uv run ruff format         # format
uv run ty check ./src      # type-check
pre-commit install         # enable the git hooks (optional)