Gumlet

This library provides convenient access to the Gumlet REST API from Python.

The REST API documentation can be found on docs.gumlet.com. The full API of this library can be found in api.md.

Contents

• Installation
• Usage
• API Reference
• Async
• Authentication
• Errors
• Client Options
• Retries and Timeouts
• Webhooks
• Helpers
• Logging
• Requirements

Installation

pip install gumlet

Usage

import os

from gumlet import Gumlet

client = Gumlet(
    api_key=os.environ.get("API_KEY"),
)

video_asset = client.video_assets.create(
    input="http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8",
    format="ABR",
    title="Example Title",
    workspace_id="<your workspace id>",
)

print(video_asset)

The examples in the following sections assume a client configured as shown above.

See the API reference for every available operation.

Async

Every client has an Async counterpart (AsyncGumlet) exposing the same resource tree with await.

import asyncio

from gumlet import AsyncGumlet


async def main() -> None:
    client = AsyncGumlet()
    video_asset = await client.video_assets.create(
        input="http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8",
        format="ABR",
        title="Example Title",
        workspace_id="<your workspace id>",
    )


asyncio.run(main())

Authentication

Pass credentials to the generated client constructor. Environment variables are read automatically when supported by the target runtime.

Option	Type	Default	Description
api_key	str | None	-	Credential for the API_KEY scheme. Defaults to API_KEY.

Declared schemes:

• API_KEY bearer token

Errors

Non-success responses throw generated API errors. Error objects expose status, headers, response body, and request metadata where the target runtime supports it.

from gumlet import APIStatusError

try:
    video_asset = client.video_assets.create(
        input="http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8",
        format="ABR",
        title="Example Title",
        workspace_id="<your workspace id>",
    )
except APIStatusError as err:
    print(err.status_code, err.message)
    raise

Documented error statuses: 400, 401, 402, 403, 404, 413, 422, 500.

Client Options

Configure the generated client by setting any of these options when you create it.

from gumlet import Gumlet

client = Gumlet(
    timeout=60.0,
    max_retries=2,
)

Option	Type	Default	Description
api_key	str | None	os.environ.get("API_KEY")	Credential for the API_KEY scheme.
base_url	str | httpx.URL | None	-	Override the default API base URL.
timeout	float | Timeout | None	60.0	Maximum time in seconds to wait for a response before aborting a request.
max_retries	int	2	Number of retries for temporary failures.
default_headers	Mapping[str, str] | None	-	Headers sent with every request.
default_query	Mapping[str, object] | None	-	Query parameters sent with every request.

Retries and Timeouts

Generated clients support request timeouts and retry temporary failures such as network errors, 408, 409, 429, and 5xx responses. Retry delays honor Retry-After headers when present. Tune the retry and timeout client options shown above, or override them per request.

Webhooks

The webhook helper verifies the signature of each delivery your server receives, then decodes its body into a typed event. Pass it the request body exactly as it arrived, before any JSON parsing, together with the request headers: the signature covers the raw body, so one that was parsed and re-serialized fails verification. A delivery whose signature does not verify is rejected before it is decoded.

# `payload` is the raw request body; `headers` holds the request headers.
event = client.webhooks.unwrap(payload, headers=headers)

The signing secret comes from the client's webhook_secret option, which defaults to the GUMLET_WEBHOOK_SECRET environment variable. Pass key to use a different secret for one call.

The same resource also has:

• client.webhooks.verify_signature(payload, headers) checks a delivery's signature, and fails when it does not verify.
• client.webhooks.parse_unsafe(payload) decodes a body into a typed event without checking its signature. Use it only for a body verified elsewhere, or in tests.

Helpers

• Use client.with_raw_response.<resource>.<method>(...) to access the raw httpx.Response and parse it yourself.
• Use client.with_streaming_response.<resource>.<method>(...) to stream a response body without buffering it.

Logging

• Set the GUMLET_LOG environment variable to info or debug to enable HTTP logging.
• Logs are emitted through the standard logging module under the gumlet logger.
• Importing the SDK wraps the process's log record factory: records from the SDK, httpx, httpcore, hpack and websockets loggers have credential headers, credential query parameters and URL userinfo logged as ***. A record factory installed later that does not chain to the previous one turns this off.

Requirements

• Python 3.9 or newer