Metadata-Version: 2.4
Name: standcloud-integration
Version: 0.1.0
Summary: Python SDK (and CLI) to export StandCloud test reports to CSV via the public API
Project-URL: Homepage, https://github.com/everypinio/standcloud-integration
Project-URL: Repository, https://github.com/everypinio/standcloud-integration
Project-URL: Issues, https://github.com/everypinio/standcloud-integration/issues
Project-URL: Changelog, https://github.com/everypinio/standcloud-integration/blob/master/CHANGELOG.md
Project-URL: Documentation, https://github.com/everypinio/standcloud-integration/blob/master/docs/en/reports.md
Author: Everypin
License: MIT
License-File: LICENSE
Keywords: cli,csv,hardpy,manufacturing,sdk,standcloud,test-reports
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Provides-Extra: cli
Requires-Dist: click>=8.1; extra == 'cli'
Description-Content-Type: text/markdown

# standcloud-integration

*Русская версия: [README.ru.md](README.ru.md)*

[![CI](https://github.com/everypinio/standcloud-integration/actions/workflows/ci.yml/badge.svg)](https://github.com/everypinio/standcloud-integration/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/standcloud-integration.svg)](https://pypi.org/project/standcloud-integration/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

`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](./LICENSE)

## 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:

```bash
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:

```bash
pip install 'standcloud-integration[cli]'
```

## Authentication

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

```python
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.

```bash
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.

```python
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`](examples/custom_report.py);
to create your own report, see **[docs/en/writing-reports.md](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](docs/en/writing-reports.md#logging).

## Command-line interface (optional)

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

```bash
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`:

```bash
standcloud-integration --help
```

A report's own options come **after** its name.

Report help:
```
standcloud-integration devices-with-last-stage --help
```

Example query:
```bash
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](docs/en/reports.md).

If you need your own report type, **[see the development docs](docs/en/writing-reports.md)**.

## Development

This project uses the `uv` package manager.

Linux, macOS:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

macOS:
```bash
brew install uv
```

Windows

```powershell
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:
> ```powershell
> $env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
> ```
> The command above only affects the current session. To make it permanent:
> ```powershell
> [Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\.local\bin;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")
> ```

Set up the environment and run the tooling:

```bash
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
```

```bash
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)
```
