burdenoff-hookmovies-sdk
Official Python SDK for HookMovies, the multi-language streaming network on the Burdenoff platform. It gives you typed async clients for the catalog (titles, studios, people, episodes), short-form clips, rights windows, entitlements and public embeds, plus helpers for the embeddable player.
The package is a thin shell over burdenoff-sdk-libs; the import name is hookmovies_sdk. Its TypeScript twin is @burdenoff/hookmovies-sdk.
Features
- Async/await throughout, built on
httpx - Dual-endpoint GraphQL client (workspace + global gateways)
sdk.hookmovieswith titles, clips, rights, entitlements, embeds and the rest of the HookMovies domain- Anonymous public-embed lookup and the app's
<iframe>snippet - Multiple auth flows: email/password, device code, PKCE, client credentials
- Automatic token refresh, typed error hierarchy,
py.typed
Installation
pip install burdenoff-hookmovies-sdk
Quick Start
import asyncio
from hookmovies_sdk import HookmoviesSDK, HokCreateEmbedInput, HokPaginationInput, SignInInput
async def main():
# Defaults to the production gateways. Override with constructor arguments
# or HOOKMOVIES_WORKSPACE_ENDPOINT / HOOKMOVIES_GLOBAL_ENDPOINT.
sdk = HookmoviesSDK()
await sdk.auth.sign_in(SignInInput(username="user@example.com", password="secret"))
page = await sdk.hookmovies.titles.list(HokPaginationInput(limit=20), status="PUBLISHED")
title = page.items[0]
clips = await sdk.hookmovies.clips.list(HokPaginationInput(limit=10), title_id=title.id)
windows = await sdk.hookmovies.rights.list(title_id=title.id)
access = await sdk.hookmovies.entitlements.check(title.id, "IN")
embed = await sdk.hookmovies.embeds.create(
HokCreateEmbedInput(title_id=title.id, kind="TRAILER")
)
print(sdk.embed_url(embed.public_id))
print(sdk.iframe_snippet(embed.public_id, title=title.title))
await sdk.close()
asyncio.run(main())
Embeds and the public player
iframe_snippet returns the same responsive snippet the HookMovies app shows on a title's Embeds panel. get_public_embed resolves an embed anonymously, exactly like the player inside a third-party page: it sends no credentials, returns None for unknown or revoked embeds, and its media_url / poster_url are presigned until expires_at. Failures raise the usual SDK errors (NetworkError, or HookmoviesError when the gateway rejects the request). It runs the shared burdenoff-sdk-libs operation on a credential-less client.
from hookmovies_sdk import embed_url, get_public_embed, iframe_snippet
public = await get_public_embed("<publicId>") # no SDK instance or sign-in needed
html = iframe_snippet("<publicId>", title="My Film")
sdk.hookmovies.embeds also has list(pagination, status, title_id) and revoke(id); a revoked embed's public link stops resolving.
Modules
All methods are async. Only modules whose GraphQL documents validate against the production supergraph (the sdk-libs Operation Conformance check) are mounted: auth, conversations, export, files, groups, health, hookmovies, integrations, notifications, organizations, products, rbac, security, store, support, tags, tours, workspaces.
sdk.hookmovies nests the domain: titles, studios, people, episodes, productions, auditions, reviews, lists, entitlements, watch_progress, rights, clips, embeds, analytics.
Configuration
from hookmovies_sdk import HookmoviesSDK
sdk = HookmoviesSDK(
workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
global_endpoint="https://graphql.burdenoff.com/global/graphql",
client_id="burdenoff_cli_hookmovies", # default
oidc_issuer=None, # derived from global_endpoint
api_key=None,
access_token=None,
refresh_token=None,
workspace_token=None,
timeout=30.0,
auto_refresh=True,
app_origin="https://app.hookmovies.com", # app shell serving the public player
)
Error Handling
from hookmovies_sdk import (
HookmoviesError,
AuthenticationError,
AuthorizationError,
NetworkError,
ValidationError,
RateLimitError,
DeviceCodeExpiredError,
DeviceCodeDeniedError,
)
try:
await sdk.auth.sign_in(SignInInput(username="user@example.com", password="wrong"))
except AuthenticationError:
print("Invalid credentials")
except NetworkError:
print("Could not reach the API")
except HookmoviesError as e:
print(f"SDK error: {e}")
Releases
Versions are CalVer (YYYY.MDD.PATCH). A release is cut from .github/workflows/release.yml (tag push or manual dispatch) and published to PyPI by CI; the version is stamped at build time and never committed back.
Development
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
make format # black + isort
make lint # flake8
make type-check # mypy (strict)
make test # pytest
make sanity # format-check + lint + type-check + test (cov>=80) + build
License
Proprietary — Copyright Burdenoff Consultancy Services Pvt. Ltd.
Support
- Issues: GitHub Issues
Metadata
Release files for burdenoff-hookmovies-sdk 2026.1102.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| burdenoff_hookmovies_sdk-2026.1102.2.tar.gz | 23.2 kB | Without provenance | Details for burdenoff_hookmovies_sdk-2026.1102.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| burdenoff_hookmovies_sdk-2026.1102.2-py3-none-any.whl | Python 3 | none | any | Details for burdenoff_hookmovies_sdk-2026.1102.2-py3-none-any.whl |
Total release size: 35.6 kB
Release files / burdenoff_hookmovies_sdk-2026.1102.2.tar.gz
| Download URL | burdenoff_hookmovies_sdk-2026.1102.2.tar.gz |
|---|---|
| Size | 23.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
31bd0d282d6a8672cfdc83adcbd50c83a5e17b2633de8037544ab0a1ce1c99f0
|
|
BLAKE2b-256 checksum How to use checksums |
bc40dc421901a1b7e4368c4ffa01a940dcd633d549092e222d7a70f9b41cf02f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / burdenoff_hookmovies_sdk-2026.1102.2-py3-none-any.whl
| Download URL | burdenoff_hookmovies_sdk-2026.1102.2-py3-none-any.whl |
|---|---|
| Size | 12.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cdfbb28bf8a1514f18f4028359331396a9d65785604ab8f5af4dce364e148814
|
|
BLAKE2b-256 checksum How to use checksums |
f23f3a87f5da809c73b909cf6367d5f624265d88ba8bb5015e31cca13aabc2e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for burdenoff-hookmovies-sdk 2026.1102.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.