Metadata-Version: 2.4
Name: plystra
Version: 0.0.1
Summary: Official Python SDK for the Plystra Kernel Phase 1 API.
Project-URL: Homepage, https://plystra.com
Project-URL: Documentation, https://docs.plystra.com
Project-URL: Repository, https://github.com/plystra/python-sdk
Project-URL: Issues, https://github.com/plystra/python-sdk/issues
Author: Plystra
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: auth,authorization,identity,plystra,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28
Description-Content-Type: text/markdown

# plystra

Official Python SDK for the Plystra Kernel Phase 1 API.

PyPI package name: `plystra`
Repository name: `plystra/python-sdk`

Requires Python 3.10 or newer.

## Install

```bash
pip install plystra
```

## Usage

Phase 1 is Context Mode: your trusted backend keeps its existing users, organizations, roles, and business rows, then calls Plystra to protect one action.

```python
from plystra import Plystra

with Plystra("https://plystra.internal", api_key="ply_kernel_secret") as plystra:
    decision = plystra.authz.check(
        actor={
            "user_id": "user_external_alice",
            "member_id": "member_finance_reviewer",
            "binding_id": "binding_external_alice_finance",
            "space_id": "space_acme",
        },
        resource={
            "type": "invoice",
            "external_id": "invoice_001",
            "space_id": "space_acme",
            "group_path": "finance.apac",
            "owner_member_id": "member_invoice_creator",
        },
        grants=[{
            "role_key": "finance_approver",
            "resource": "invoice",
            "action": "approve",
            "scope": "group_tree",
            "space_id": "space_acme",
            "scope_anchor_group_path": "finance",
        }],
        action="approve",
        explain=True,
    )
```

Inline actor, resource, and grant context is trusted server-side input. Build it from your authenticated session and database state, never directly from browser-submitted JSON.

## Async Usage

```python
import asyncio
from plystra import AsyncPlystra


async def main() -> None:
    async with AsyncPlystra("https://plystra.internal", api_key="ply_kernel_secret") as plystra:
        print(await plystra.system.capabilities())


asyncio.run(main())
```

## Kernel Surfaces

- `system.health()`, `system.ready()`, `system.version()`
- `system.capabilities()`
- `resource_types.list()`
- `authz.check()` and `authz.explain()`
- `audit.list()` and `audit.get()`
- `request()` for low-level calls

Attach a correlation id to a group of calls:

```python
scoped = plystra.with_request_id("req_01HY...")
scoped.authz.explain(**context_mode_request)
```

Protected routes require a scoped server API key. Public health, readiness, and version checks do not send the key.
