Metadata-Version: 2.4
Name: kotharcomputing
Version: 1.5.0
Summary: Python SDK for the Kothar API
Author: Kothar Computing
License-Expression: Apache-2.0
Keywords: kothar,api,sdk
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Kothar Python SDK

Python SDK for the [Kothar API](https://docs.kotharcomputing.com/docs/the-forge/API).

## Workshop API tokens

Create an immutable token in **Account settings → API tokens**, explicitly select its permissions, and save the
credential when it is shown. Delete it to revoke access; create a replacement to change metadata, expiration, or grants.
Non-expiring tokens keep their issued grants until revoked.

This example needs **Files → List (All files)** and **Targets → List**. Set the credential and the workspace/user IDs shown
on the account page in environment variables. API tokens cannot use the session-only `personal` or `me` aliases.

```python
import os
from kotharcomputing import KotharClient

client = KotharClient(access_token=os.environ["KOTHAR_API_TOKEN"])
files = client.workspaces.id(os.environ["KOTHAR_WORKSPACE_ID"]).files.list()
targets = client.users.id(os.environ["KOTHAR_USER_ID"]).targets.list()
```

Creating tasks also needs read access to the chosen task definition and any specified target.

## Aleph language server

The SDK also provides a separate anonymous HTTP client for the Aleph language
server. It does not use Kothar API authentication:

```python
from kotharcomputing import AlephLanguageServerClient

aleph = AlephLanguageServerClient()
analysis = aleph.analyze('print("hello")', include_ast=True)
parsed = aleph.ast('print("hello")', format=True, discover_test=True)
tests = aleph.discover_tests('test "example" {}')
formatted = aleph.format('print( "hello" )')
```

## HDF5 dataset reads

Generated operations use GET with no body and encode a nested `ranges` array as
one JSON query parameter. Use `[]` for scalar/null dataspaces.

```python
from kotharcomputing import ApiTransport
from kotharcomputing._generated.operations import read_file_dataset

transport = ApiTransport("https://api.kotharcomputing.com", access_token="YOUR_TOKEN")
response = read_file_dataset(
    transport,
    workspace_id="WORKSPACE_ID",
    path="measurements.h5",
    version_id="immutable-version-id",
    object_path="/samples",
    ranges=[[0, 10, 2]],
)
selection = response.json()  # shape, datatype, values; optional base64 data
```

Use `representation="binary"` and `response.body` for little-endian numeric/enum
bytes or decoded scalar-string bytes; `response.headers` preserves identity and
dtype metadata. Fixed-length string arrays require JSON. Enum symbols contain
exact decimal codes; JSON values retain the existing 64-bit tags. External callers
must replace POST reads with GET; stored files need no migration.
