Metadata-Version: 2.5
Name: livepeer-frameworks
Version: 0.3.0
Summary: Typed client for the FrameWorks GraphQL API: operations, retries, pagination, typed errors, uploads, playback tokens, and webhooks
Project-URL: Documentation, https://logbook.frameworks.network/builders/sdks
Project-URL: Source, https://github.com/Livepeer-FrameWorks/monorepo/tree/master/sdk_python
Author: Livepeer FrameWorks
License-Expression: Unlicense
Keywords: frameworks,graphql,livepeer,sdk,streaming
Classifier: Framework :: AsyncIO
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: betterproto2==0.10.0
Requires-Dist: cryptography>=43
Requires-Dist: graphql-core<3.3,>=3.2
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: standardwebhooks<2,>=1.1.0
Requires-Dist: websockets<18,>=13
Provides-Extra: dev
Requires-Dist: ariadne-codegen==0.19.0; extra == 'dev'
Requires-Dist: betterproto2-compiler==0.10.1; extra == 'dev'
Requires-Dist: build==1.6.1; extra == 'dev'
Requires-Dist: mypy==2.3.1; extra == 'dev'
Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
Requires-Dist: pytest==9.1.1; extra == 'dev'
Requires-Dist: ruff==0.15.22; extra == 'dev'
Requires-Dist: twine==7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# livepeer-frameworks

Typed Python client for the [FrameWorks](https://frameworks.network) GraphQL API. It ships a sync
and an async client generated from the public GraphQL schema, with a method for every public root
field and argument-taking field, pydantic models, retries, pagination, typed errors, a VOD upload
helper, playback token signing, and webhook verification.

```sh
pip install livepeer-frameworks
```

```python
from livepeer_frameworks import FrameWorksClient, expect_result, paginate_relay
from livepeer_frameworks.graphql import ConnectionInput, CreateStreamInput, Stream

with FrameWorksClient(token="YOUR_API_TOKEN") as fw:
    created = fw.create_stream(input=CreateStreamInput(name="Studio A"))
    # Returns the Stream member or raises ResultError for ValidationError/AuthError.
    stream = expect_result(created.create_stream, Stream)
    print(stream.stream_key, stream.playback_id)

    for s in paginate_relay(
        lambda page: fw.list_streams(page=ConnectionInput.model_validate(page)).streams_connection
    ):
        print(s.name)
```

The client defaults to `https://bridge.frameworks.network/graphql` and reads no environment
variables. Pass `url=` only for a self-hosted or staging Bridge, and pass the token explicitly.
Per-call options are
keyword arguments of the generated methods: `idempotency_key=` (sent as `Idempotency-Key`; paid
mutations settled with x402 need one) and `playback_token=` (sent as `X-Frameworks-Playback-JWT`).

Queries are retried on network errors and HTTP 408, 429, and 5xx. A mutation is retried only when
the request provably never reached the server: the connection could not be established, or the
gateway answered 429. It is never sent again after a timeout, a dropped connection, or a 5xx,
because the gateway does not deduplicate replayed mutations.

## Subscriptions

Every public subscription is an async iterator method on `AsyncFrameWorksClient` (`tenant_events`,
`live_stream_events`, `skipper_chat`, ...) that yields the operation's pydantic model:

```python
async with AsyncFrameWorksClient(token="YOUR_API_TOKEN") as fw:
    async for event in fw.tenant_events(types=["stream.live", "stream.idle"]):
        print(event.tenant_events.type_, event.tenant_events.subject)
```

The sync `FrameWorksClient` has no subscription methods: ariadne-codegen, which generates the
clients, emits subscriptions only for an async client.

## Custom documents

Every public root field and argument-taking field has a generated method with a default
selection. The Python SDK has no typed builder for other selections: ariadne-codegen 0.19's custom
operation builder generates only queries and mutations (no subscriptions), and returns
`dict[str, Any]` with custom scalars undecoded (`Time` arrives as a `str`, where the generated
methods return `datetime`). For other selections, send your own document through the client's
`execute` (queries and mutations; `get_data` returns the data) or the async client's `execute_ws`
(subscriptions), which use the SDK's authentication, retries, and typed errors. Give it an
operation name of your own: the server version check looks up an SDK operation's release by name.

## Versions

The TypeScript, Go, and Python SDKs share one version. Until FrameWorks 1.0 the SDKs stay at 0.x,
and each minor line supports the FrameWorks releases listed for it; this line needs FrameWorks
v0.3.11 or later. Against an older stable release the client raises `ServerTooOldError` before
sending a call.

Documentation: <https://logbook.frameworks.network/builders/sdks>
