Metadata-Version: 2.4
Name: kotharcomputing
Version: 1.0.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 generated from `schemas/openapi.yml`.

Install the published SDK with `pip install kotharcomputing`. Starting with `1.0.0`,
the package is released from `kothardev/kothar-platform` and its version follows the
platform tag (`v1.0.0` publishes `1.0.0`). It replaces the package previously built
in `kothar-backend`; use the workspace and target API examples below when updating
applications from the legacy SDK. Existing PyPI releases remain available for pinned installations.

## 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" )')
```

Pass `base_url=` or `AlephLanguageServerClientOptions` to use another Aleph
deployment. The default endpoint is `https://aleph.kotharcomputing.com`.

`ast` accepts an optional structured `filter` and returns a required AST with syntax and light binding diagnostics,
without establishing full type correctness. Both `ast` and `analyze` accept `format` and `discover_test`; their optional
`tests` field and the direct `discover_tests` result use `AlephTestDiscoverySection`, with recursive sections and typed
test metadata. Discovery does not execute source or tests. The client-level `timeout` applies to these methods too.

The reviewed contract is pinned in `schemas/aleph-openapi.json`; maintenance and SDK parity checks are documented in
[RFC 0013](../../../docs/rfcs/0013-workshop-tasks-and-aleph-execution.md).

## 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. Never
save credentials in source code, logs, or browser storage.

```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. Task search-schema
discovery needs **Targets → List** and **Task definitions → List**. Add these grants explicitly when needed.
