Skip to main content

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.hookmovies with 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

Metadata

Release files for burdenoff-hookmovies-sdk 2026.1107.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for burdenoff-hookmovies-sdk 2026.1107.1
File Size Uploaded Provenance Actions
burdenoff_hookmovies_sdk-2026.1107.1.tar.gz 23.2 kB Without provenance Details for burdenoff_hookmovies_sdk-2026.1107.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for burdenoff-hookmovies-sdk 2026.1107.1
File Interpreter ABI Platform Actions
burdenoff_hookmovies_sdk-2026.1107.1-py3-none-any.whl Python 3 none any Details for burdenoff_hookmovies_sdk-2026.1107.1-py3-none-any.whl

Total release size: 35.6 kB

Release files / burdenoff_hookmovies_sdk-2026.1107.1.tar.gz

Download URL burdenoff_hookmovies_sdk-2026.1107.1.tar.gz
Size 23.2 kB
Tags Source
SHA-256 checksum
How to use checksums
9142043fa480e92fa47be48ee8cb585550c4f7049232c368782d84a334aeff70
BLAKE2b-256 checksum
How to use checksums
4f6bff4aa7943ef083e7beffca22f74c76e1ebb582b6bc932f1585d5ea3b6953
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.1107.1-py3-none-any.whl

Download URL burdenoff_hookmovies_sdk-2026.1107.1-py3-none-any.whl
Size 12.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e90d63f143152c70043eb90ad3f573cae1d3fc19255d63992f78263ab2e1e18c
BLAKE2b-256 checksum
How to use checksums
edb530d5ad03f427c19e057e320a44dfb3fceab52fb2a87ea3f7aae3770013ab
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.1107.1

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page