Metadata-Version: 2.4
Name: plystra
Version: 1.0.0rc5
Summary: Official Python SDK for Plystra.
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 Plystra Core v1.0.

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

Requires Python 3.10 or newer.

## Install

```bash
pip install plystra
```

## Synchronous Usage

For production backend code, prefer passing a server-side access token or API key that was issued outside the request path. Keep password login available for admin tools and bootstrap flows, not for routine service-to-service checks.

Using an API key:

```python
from plystra import Plystra

with Plystra("https://plystra.internal", api_key="ply_ak_...") as plystra:
    decision = plystra.authz.check(
        actor={
            "user_id": "user_alice",
            "space_id": "space_acme",
            "member_id": "member_finance_reviewer",
            "user_member_id": "um_alice_finance_reviewer",
        },
        resource_type="invoice",
        resource_id="invoice_001",
        action="approve",
    )
```

Using an access token received from your frontend or gateway session:

```python
from plystra import Plystra

with Plystra("https://plystra.internal", access_token=session["plystra_access_token"]) as plystra:
    print(plystra.authz.check(action="approve", resource_type="invoice", resource_id="invoice_001"))
```

Access-token calls may omit `actor`; Core uses the token's active actor. API key calls must pass the nested `actor` explicitly.

Attach an application request id to a group of calls with `with_request_id`:

```python
from plystra import Plystra

with Plystra("https://plystra.internal", access_token=session["plystra_access_token"]) as plystra:
    scoped = plystra.with_request_id("req_01HY...")
    decision = scoped.authz.check(
        resource_type="invoice",
        resource_id="invoice_001",
        action="approve",
    )
```

Password login is still supported:

```python
from plystra import Plystra

with Plystra("http://localhost:8080") as plystra:
    plystra.auth.login("alice@example.com", "plystra-demo")

    # Core rotates refresh tokens. Omitting the argument uses the stored one.
    plystra.auth.refresh()

    decision = plystra.authz.check(
        actor={
            "user_id": "user_alice",
            "space_id": "space_acme",
            "member_id": "member_finance_reviewer",
            "user_member_id": "um_alice_finance_reviewer",
        },
        resource_type="invoice",
        resource_id="invoice_001",
        action="approve",
    )

    print(decision["decision"])
```

## Asynchronous Usage

```python
import asyncio
from plystra import AsyncPlystra


async def main() -> None:
    async with AsyncPlystra("https://plystra.internal", api_key="ply_ak_...") as plystra:
        decision = await plystra.authz.check(
            actor={
                "user_id": "user_alice",
                "space_id": "space_acme",
                "member_id": "member_finance_reviewer",
                "user_member_id": "um_alice_finance_reviewer",
            },
            resource_type="invoice",
            resource_id="invoice_001",
            action="approve",
        )
        print(decision["decision"])


asyncio.run(main())
```

## Modules

The SDK exposes v1.0 Core modules as attributes:

- `system`
- `auth`
- `actor`
- `admin`
- `api_keys`
- `users`
- `spaces`
- `groups`
- `members`
- `user_members`
- `roles`
- `member_roles`
- `permissions`
- `role_permissions`
- `resource_types`
- `resources`
- `authz`
- `audit`
- `data`
- `plugins`
- `templates`

Non-public endpoints require either a Bearer session whose user has an active admin grant or a scoped API key with matching permission keys.

Keep SDK tokens in a server-side encrypted session store. `login()` and `refresh()` update `access_token` and `refresh_token` on the client; call `plystra.tokens()` when you need to persist the rotated token pair.
