livery.forge._errors¶
livery.forge._errors ¶
The exceptions every backend raises the same way.
Classes:
| Name | Description |
|---|---|
ForgeError |
Raised when a forge operation fails. |
RateLimited |
Raised when the forge refuses a request because its API budget is spent. |
Unsupported |
Raised when a forge cannot honour a protocol operation. |
Functions:
| Name | Description |
|---|---|
refuse_unknown_labels |
Raise livery.forge.ForgeError naming the labels base lacks among names. |
ForgeError ¶
ForgeError(message: str, *, status: int | None = None, method: str = '', endpoint: str = '', detail: str = '')
Bases: Exception
Raised when a forge operation fails.
The message says what failed, in the words of the server that refused it. A caller that branches on the failure reads the attributes, never the message text.
Attributes:
| Name | Type | Description |
|---|---|---|
status |
The HTTP status code, or None when the server never answered. An unreachable server is a different decision for the caller than any code it could have returned. |
|
method |
The HTTP method of the failing request, when known. |
|
endpoint |
The endpoint of the failing request, when known. |
|
detail |
The response body, verbatim. |
Carry message plus the request facts a caller branches on.
Source code in packages/forge/src/livery/forge/_errors.py
RateLimited ¶
RateLimited(message: str, *, reset_at: float | None, status: int | None = None, method: str = '', endpoint: str = '', detail: str = '')
Bases: ForgeError
Raised when the forge refuses a request because its API budget is spent.
Asking again before the budget returns gets the same answer. A caller that can wait (a watch that follows a pull request) sleeps until then and continues; one that cannot names the time.
Attributes:
| Name | Type | Description |
|---|---|---|
reset_at |
When the budget returns, as seconds since the epoch; None when the forge did not say. |
Carry message, the request facts, and when the budget returns.
Source code in packages/forge/src/livery/forge/_errors.py
Unsupported ¶
Bases: Exception
Raised when a forge cannot honour a protocol operation.
The message says why: a server version that predates the operation, or a capability the forge declines by name. Kept apart from livery.forge.ForgeError because retrying cannot change the answer: the forge is reachable, and the operation is one it does not offer. Probe with livery.forge.Forge.supports before relying on a capability-gated operation.
refuse_unknown_labels ¶
Raise livery.forge.ForgeError naming the labels base lacks among names.
Every backend asks this before it writes a label onto an issue or a pull request: GitHub and GitLab create a label they do not know on such a write, and Gitea takes ids, which an unknown name has none of, so the one refusal by name is made here, before anything is written. Nothing is raised when every name is in known.