plystra 1.0.0.dev2__tar.gz → 1.0.0.dev10__tar.gz

{plystra-1.0.0.dev2 → plystra-1.0.0.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plystra
-Version: 1.0.0.dev2
+Version: 1.0.0.dev10
 Summary: Official Python SDK for Plystra.
 Project-URL: Homepage, https://plystra.com
 Project-URL: Documentation, https://docs.plystra.com
@@ -13,12 +13,11 @@ 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.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Requires-Dist: httpx>=0.28
 Description-Content-Type: text/markdown
 
@@ -27,6 +26,9 @@ Description-Content-Type: text/markdown
 Official Python SDK for Plystra Core v1.0.
 
 PyPI package name: `plystra`
+Repository name: `plystra/python-sdk`
+
+Requires Python 3.10 or newer.
 
 ## Install
 
@@ -36,12 +38,45 @@ 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",
+        actor_member_id="member_finance_reviewer",
+        actor_user_member_id="um_alice_finance_reviewer",
+        space_id="space_acme",
+        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"))
+```
+
+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",
@@ -65,8 +100,7 @@ from plystra import AsyncPlystra
 
 
 async def main() -> None:
-    async with AsyncPlystra("http://localhost:8080") as plystra:
-        await plystra.auth.login("alice@example.com", "plystra-demo")
+    async with AsyncPlystra("https://plystra.internal", api_key="ply_ak_...") as plystra:
         decision = await plystra.authz.check(
             actor_user_id="user_alice",
             actor_member_id="member_finance_reviewer",
@@ -90,6 +124,7 @@ The SDK exposes v1.0 Core modules as attributes:
 - `auth`
 - `actor`
 - `admin`
+- `api_keys`
 - `users`
 - `spaces`
 - `groups`
@@ -107,4 +142,6 @@ The SDK exposes v1.0 Core modules as attributes:
 - `plugins`
 - `templates`
 
-Non-public endpoints require a Bearer session whose user has an active admin grant.
+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.

plystra-1.0.0.dev10/README.md

@@ -0,0 +1,124 @@
+# 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",
+        actor_member_id="member_finance_reviewer",
+        actor_user_member_id="um_alice_finance_reviewer",
+        space_id="space_acme",
+        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"))
+```
+
+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",
+            actor_member_id="member_finance_reviewer",
+            actor_user_member_id="um_alice_finance_reviewer",
+            space_id="space_acme",
+            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.

{plystra-1.0.0.dev2 → plystra-1.0.0.dev10}/plystra/__init__.py

@@ -1,8 +1,10 @@
 from .client import (
     AsyncPlystra,
     Plystra,
-    PlystraAPIError,
     PlystraClient,
+)
+from .exceptions import (
+    PlystraAPIError,
     PlystraError,
     PlystraNetworkError,
     PlystraTimeoutError,

plystra-1.0.0.dev10/plystra/_utils.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+from urllib.parse import quote
+
+import httpx
+
+from .exceptions import PlystraAPIError
+from .types import Query
+
+def _data_or_raise(response: httpx.Response) -> Any:
+    try:
+        envelope = response.json()
+    except ValueError as exc:
+        raise PlystraAPIError(
+            "INVALID_JSON_RESPONSE",
+            f"Plystra returned non-JSON response with HTTP {response.status_code}",
+            status_code=response.status_code,
+            details=response.text,
+        ) from exc
+
+    error = envelope.get("error") if isinstance(envelope, dict) else None
+    if response.status_code >= 400 or error:
+        error = error or {}
+        raise PlystraAPIError(
+            error.get("code", "HTTP_ERROR"),
+            error.get("message", response.reason_phrase),
+            status_code=response.status_code,
+            details=error.get("details"),
+            request_id=error.get("request_id") or envelope.get("request_id") or envelope.get("meta", {}).get("request_id"),
+            trace_id=error.get("trace_id"),
+            audit_log_id=error.get("audit_log_id"),
+        )
+    return envelope.get("data") if isinstance(envelope, dict) else envelope
+
+
+def _clean_query(query: Query | None) -> dict[str, str]:
+    if not query:
+        return {}
+    return {key: str(value).lower() if isinstance(value, bool) else str(value) for key, value in query.items() if value is not None}
+
+
+def _e(value: str) -> str:
+    return quote(value, safe="")
+
+
+def _store_tokens(client: Plystra | AsyncPlystra, data: Mapping[str, Any]) -> None:
+    access_token = data.get("access_token")
+    refresh_token = data.get("refresh_token")
+    client.set_tokens(
+        access_token=access_token if isinstance(access_token, str) else client.access_token,
+        refresh_token=refresh_token if isinstance(refresh_token, str) else client.refresh_token,
+    )