foley.sources.http#

Injectable HTTP transport for foley’s live source adapters.

Live SOURCE adapters (Freesound, #5; hosted generators, #6) speak HTTP. To keep import foley dependency-light (dol-only) and the test suite hermetic (no network, no HTTP library), the HTTP call is a dependency-injected callable — a Transport — that each adapter takes by keyword, defaulting to requests_transport(). Tests inject a fake transport returning canned responses; the real requests is imported lazily inside requests_transport() and nowhere else, so it stays behind the foley[freesound] extra (never pulled by the core or by the fake-injection tests).

A Transport is any callable with the shape:

transport(method, url, *, params=None, headers=None, json=None) -> Response

and a Response is any object exposing status_code / content / json() — a structural subset of requests.Response (which therefore satisfies it with no wrapper).

The keyword-only json body was added for the hosted generate adapters (#6: ElevenLabs Sound Effects POSTs a JSON body), where Freesound (#5) only ever did GET-with-params. It defaults to None and is passed straight through to requests.request(..., json=...), so every existing GET caller (and the Freesound fake transport) is unaffected.

Module Attributes

DEFAULT_TIMEOUT_S

Per-request timeout (seconds) for the default requests transport.

Functions

requests_transport(method, url, *[, params, ...])

The default Transport — a thin, lazy wrapper over requests.

Classes

Response(*args, **kwargs)

The minimal HTTP response surface an adapter needs.

Transport(*args, **kwargs)

A callable performing ONE HTTP request and returning a Response.
foley.sources.http.DEFAULT_TIMEOUT_S: int = 30#

Per-request timeout (seconds) for the default requests transport. A live adapter never blocks foley indefinitely on a hung connection.

class foley.sources.http.Response(*args, **kwargs)[source]#

Bases: Protocol

The minimal HTTP response surface an adapter needs.

A structural subset of requests.Response — requests satisfies it with no wrapper, and a test double is a tiny dataclass with the same three members.

content: bytes#

Raw response body bytes (used for audio/preview downloads).

json()[source]#

Decode the response body as JSON.

Return type:

Any

status_code: int#

HTTP status code (200 on success).

class foley.sources.http.Transport(*args, **kwargs)[source]#

Bases: Protocol

A callable performing ONE HTTP request and returning a Response.

The dependency-injection seam: the default is requests_transport(); tests pass a fake. Keyword-only params / headers mirror requests.

foley.sources.http.requests_transport(method, url, *, params=None, headers=None, json=None)[source]#

The default Transport — a thin, lazy wrapper over requests.

requests is imported HERE and only here (the foley[freesound] / foley[elevenlabs] extras), so the foley core stays dol-only and the fake-injection test path never needs an HTTP library at all. The returned requests.Response structurally satisfies Response.

Parameters:

  • method (str) – HTTP method ('GET' / 'POST' …).

  • url (str) – The full request URL.

  • params (Optional[dict]) – Optional query-string parameters.

  • headers (Optional[dict]) – Optional request headers (e.g. the auth token).

  • json (Optional[dict]) – Optional JSON request body (POST), serialized by requests.

Return type:

Response

Returns:

The requests.Response (a Response).