Metadata-Version: 2.4
Name: osbe-client
Version: 0.1.0a3
Summary: Python SDK for OpenSchool Backend (OSBE) API
Author-email: Iles Wade <iles@openschool.dev>
License-Expression: MIT
Project-URL: Homepage, https://osbe.dev
Project-URL: Documentation, https://osbe.dev
Project-URL: API, https://api.osbe.dev
Project-URL: Repository, https://github.com/openschool/osbe-client
Project-URL: Changelog, https://github.com/openschool/osbe-client/blob/main/CHANGELOG.md
Keywords: openschool,osbe,api,client,sdk,education,sdc,kds
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Internet :: WWW/HTTP :: Session
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# OSBE client SDK

`osbe-client` is the Python SDK for server-side applications that call `https://api.osbe.dev`.
It has no database dependency and uses an application bearer token stored in a protected file or secret manager.

## Install

```bash
python -m pip install osbe-client
```

For TestPyPI or local wheel testing:

```bash
python -m pip install /path/to/osbe_client-0.1.0a3-py3-none-any.whl
```

## Environment

Use one prefix per application:

```bash
SDC_OSBE_API_BASE_URL=https://api.osbe.dev
SDC_OSBE_API_APPLICATION_TOKEN_FILE=/run/secrets/sdc/osbe-api-token

KDS_OSBE_API_BASE_URL=https://api.osbe.dev
KDS_OSBE_API_APPLICATION_TOKEN_FILE=/run/secrets/kds/osbe-api-token
```

Token values must stay server-side. Do not expose them to browsers, logs, screenshots, receipts, or chat.

## Friendly SDK

```python
from osbe_client import connect_from_env

osbe = connect_from_env("SDC_OSBE_API", user_agent="sdc-osbe-client/1.0")

who = osbe.diagnostics.whoami()
ctx = osbe.courses.context("SAIT", "F26", "INTP302")
roster = osbe.courses.roster("SAIT", "F26", "INTP302", limit=1000)
assessments = osbe.assessments.for_course("SAIT", "F26", "INTP302")
groups = osbe.groups.for_assessment(assessments["items"][0]["id"])
status = osbe.submissions.status(assessments["items"][0]["id"])
content = osbe.content.for_assessment(
    assessments["items"][0]["id"],
    institution="SAIT",
    term="F26",
    course="INTP302",
    section="B",
)
```

These methods hide OSBE command names, low-level argument names, and pagination. They return predictable dictionaries with `items` for list results. The older `osbe.foundation.*` methods remain available for SDC/SDC4/KDS compatibility.

## Raw command access

Every API command is also available dynamically as `client.<family>.<verb>(**arguments)`:

```python
result = osbe.registrations.roster(institution="SAIT", term="F26", course="INTP302", limit=1000)
```

Binary upload arguments named `data` accept Python `bytes`; the client encodes them into the OSBE JSON wire format.

Transport failures raise `OsbeClientError(..., outcome_unknown=True)`. The client does not automatically retry mutations because a mutation may have committed before the network failed. Use `osbe.safe(...)`, `osbe.safe_call(...)`, `is_ok(...)`, and `error_code(...)` when an application wants an `ok/error` result instead of exceptions.

## CLI

```bash
OSBE_APPLICATION_TOKEN_FILE=/run/secrets/sdc/osbe-api-token   osbe get course-context --institution SAIT --term F26 --course INTP302
```
