livery.forge._http¶
livery.forge._http ¶
The HTTP plumbing every REST backend shares.
One JSON client over urllib: authenticated requests, refusal of redirects, error translation into livery.forge.ForgeError with the server's words attached, and pagination that is complete or raises. The network seam is the opener, anything satisfying livery.forge.testing.UrlOpener, so a backend records and replays its traffic by construction argument alone.
Classes:
| Name | Description |
|---|---|
Opener |
The network seam: urllib's opener shape, replayable in tests. |
JsonClient |
An authenticated JSON API client for one server. |
Functions:
| Name | Description |
|---|---|
default_opener |
The opener a backend uses when none is injected. |
spent |
Whether a refusal says the API budget is spent, not that access is denied. |
reset_time |
When the budget returns, as seconds since the epoch; None when unsaid. |
read_budget |
The budget a response reports, or None when it reports none. |
limit_message |
The refusal for a spent budget, naming when it returns. |
Attributes:
| Name | Type | Description |
|---|---|---|
PAGE_SIZE |
|
|
PAGE_CAP |
|
|
REDIRECT_HOPS |
|
Opener ¶
JsonClient ¶
JsonClient(api_base: str, *, headers: dict[str, str], opener: Opener | None = None, timeout: float = 30)
An authenticated JSON API client for one server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
api_base
|
str
|
The API root, no trailing slash. |
required |
headers
|
dict[str, str]
|
The authentication headers, sent on every request. An empty mapping reads anonymously. |
required |
opener
|
Opener | None
|
The network seam; the redirect-refusing default when omitted. |
None
|
Bind the client to api_base with headers.
timeout bounds each request unless a call overrides it: a heavyweight server (a single-node GitLab under load) needs more headroom than a light one, and the backend knows which it is talking to.
Methods:
| Name | Description |
|---|---|
request |
Make one request; the parsed JSON answer, or None per none_on. |
text |
GET endpoint as plain text (a job log), or None per none_on. |
upload |
POST data as one raw body to endpoint; the parsed JSON answer. |
multipart |
POST data as the file part field of a multipart form; the JSON answer. |
download |
GET endpoint and return its bytes, redirects followed. |
paginate |
Collect every page from fetch, or raise on an unfinished walk. |
pages |
Yield the items from fetch page by page, fetching as they are read. |
Attributes:
| Name | Type | Description |
|---|---|---|
api_base |
|
|
budget |
RateBudget | None
|
|
Source code in packages/forge/src/livery/forge/_http.py
request ¶
request(endpoint: str, *, method: str = 'GET', data: dict[str, Any] | None = None, none_on: tuple[int, ...] = (), timeout: float | None = None) -> Any
Make one request; the parsed JSON answer, or None per none_on.
Returns the parsed JSON body ({} for an empty one). Statuses in
none_on return None instead of raising; every other HTTP
error raises livery.forge.ForgeError with the status as a
number and the body verbatim in detail. An unreachable
server raises the same type with no status. A redirect is
refused rather than followed and raises with the 3xx status.
data is sent as a JSON body whenever it is not None, so an empty mapping means "an empty object", not "no body".
Source code in packages/forge/src/livery/forge/_http.py
text ¶
GET endpoint as plain text (a job log), or None per none_on.
Source code in packages/forge/src/livery/forge/_http.py
upload ¶
upload(endpoint: str, data: bytes, *, content_type: str = 'application/octet-stream', timeout: float | None = None) -> Any
POST data as one raw body to endpoint; the parsed JSON answer.
endpoint is relative to the API root, or absolute when it
starts with http: GitHub takes uploads on a host of its
own. Every error raises as request does.
Source code in packages/forge/src/livery/forge/_http.py
multipart ¶
multipart(endpoint: str, field: str, filename: str, data: bytes, *, timeout: float | None = None) -> Any
POST data as the file part field of a multipart form; the JSON answer.
Source code in packages/forge/src/livery/forge/_http.py
download ¶
GET endpoint and return its bytes, redirects followed.
The one read that must follow a redirect: a forge hands the bytes of a release asset to a signed URL on a store of its own. The credential rides the first hop alone. A hop to another host drops it, because the signed URL carries its own authorisation and a second one is rejected by the store.
accept sets the Accept header, which is how GitHub is asked for the bytes of an asset rather than its JSON.
Raises:
| Type | Description |
|---|---|
ForgeError
|
for any HTTP error, an unreachable server, or
a redirect chain longer than
|
Source code in packages/forge/src/livery/forge/_http.py
paginate ¶
Collect every page from fetch, or raise on an unfinished walk.
fetch takes a 1-based page number and returns that page's items; a batch shorter than size, the page size fetch asks for, ends the walk. Hitting livery.forge._http.PAGE_CAP with a full last page raises livery.forge.ForgeError naming subject: the listing is not complete, and a prefix is never the answer.
Source code in packages/forge/src/livery/forge/_http.py
pages ¶
Yield the items from fetch page by page, fetching as they are read.
The walk livery.forge._http.JsonClient.paginate collects,
for a caller that stops at its first match: no page after the
one holding it is fetched. size is the page size fetch asks
for, and a shorter page is the last. The walk raises as
paginate does, and only when a caller reads past
livery.forge._http.PAGE_CAP full pages.
Source code in packages/forge/src/livery/forge/_http.py
default_opener ¶
default_opener() -> Opener
The opener a backend uses when none is injected.
Keeps every default handler (proxies included) except the redirect one, which livery.forge._http._RefuseRedirect replaces.
Source code in packages/forge/src/livery/forge/_http.py
spent ¶
Whether a refusal says the API budget is spent, not that access is denied.
A 429 always is. A 403 is when the primary budget reads zero
(GitHub's X-RateLimit-Remaining: 0) or the server asks the
caller to come back later (Retry-After, GitHub's secondary
limit); any other 403 is a permission the token lacks.
Source code in packages/forge/src/livery/forge/_http.py
reset_time ¶
When the budget returns, as seconds since the epoch; None when unsaid.
Retry-After wins, in seconds or as an HTTP date; else the reset
the budget headers name (GitHub's X-RateLimit-Reset, GitLab's
RateLimit-Reset), which are epoch seconds.
Source code in packages/forge/src/livery/forge/_http.py
read_budget ¶
read_budget(headers: Message | None) -> RateBudget | None
The budget a response reports, or None when it reports none.
Source code in packages/forge/src/livery/forge/_http.py
limit_message ¶
The refusal for a spent budget, naming when it returns.