Metadata-Version: 2.5
Name: oceanum-prax-sdk
Version: 0.3.2
Summary: Typed clients and data models for PRAX platform
License-Expression: MIT
License-File: LICENSE
Keywords: api,client,prax,pydantic
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: datamodel-code-generator>=0.25.0; extra == 'dev'
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.3.1; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# prax (PRAX SDK)

Typed HTTP clients, API models, and authored input helpers for PRAX applications.
The Python distribution and import name are **`prax`**.

## Working with PRAX

Use the SDK to:

- Read exact service-instance health, metrics and usage, and stream logs with
  `PraxAPIClient`.
- Read and compare authored ProjectSpec revisions with bounded history operations.
- Validate and manipulate pipeline/stage inputs with `prax.spec` and
  `prax.project_spec_workflow`.
- Work with typed request/response data through `prax.models`.

The asynchronous client supports context-manager cleanup, request timeouts, and
bounded pagination. Authorize requests with an API token for your environment;
resource access follows your account's permissions.

## Example

Set `PRAX_API_URL` to your PRAX endpoint and `PRAX_API_TOKEN` to your API token.
Substitute a project name and revision number accessible to your account.

<!-- sdk-http-example:start -->
```python
import asyncio
import os

from prax import PraxAPIClient


async def main():
    async with PraxAPIClient(
        os.environ["PRAX_API_URL"], token=os.environ["PRAX_API_TOKEN"]
    ) as client:
        revision = await client.get_project_spec_revision("forecast-project", 1)
        print(revision.model_dump_json())


if __name__ == "__main__":
    asyncio.run(main())
```
<!-- sdk-http-example:end -->

## Following service-instance logs

Use the complete project, stage, service and stage-incarnation identity returned
by the API. Open logs with `async with`, not `await`: the context owns the response
and closes it on completion, an early exit, error or cancellation.

```python
async with client.stream_service_instance_logs(
    project_ref="forecast-project",
    stage_ref="production",
    service_name="api",
    stage_incarnation=stage_incarnation,
    org="oceanum",
    follow=True,
    tail=100,
) as response:
    async for line in response.aiter_lines():
        print(line)
```

Read the response only inside this context. Follow has no idle read deadline;
connection, write and pool timeouts remain those of the client. Snapshot requests
retain the normal read timeout. Injected/shared HTTP clients remain caller-owned.
No status lookup or repeated reconnection is needed to receive a live line.

## Errors

Client operations raise `PraxAPIError`. Use its `.status`, `.code`, and `.reason`
attributes to handle errors programmatically.

Catch this exception around awaited client operations to distinguish API responses
from transport failures and decide whether to retry.

## Requirements

Python **3.11+** is required. Runtime dependencies are Pydantic, Pydantic Settings,
HTTPX, and PyYAML; version bounds are declared in `pyproject.toml`.

## Versions

The SDK and CLI share the same release version. Each CLI release depends on the
matching `prax` SDK release. To inspect your installed SDK version:

```python
from importlib.metadata import version

print(version("oceanum-prax-sdk"))
```

## See also

- [PRAX command-line interface](https://github.com/oceanum/prax-cli)
