Skip to content

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
def __init__(
    self,
    message: str,
    *,
    status: int | None = None,
    method: str = "",
    endpoint: str = "",
    detail: str = "",
) -> None:
    """Carry *message* plus the request facts a caller branches on."""
    super().__init__(message)
    self.status = status
    self.method = method
    self.endpoint = endpoint
    self.detail = detail

status instance-attribute

status = status

method instance-attribute

method = method

endpoint instance-attribute

endpoint = endpoint

detail instance-attribute

detail = detail

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
def __init__(
    self,
    message: str,
    *,
    reset_at: float | None,
    status: int | None = None,
    method: str = "",
    endpoint: str = "",
    detail: str = "",
) -> None:
    """Carry *message*, the request facts, and when the budget returns."""
    super().__init__(
        message, status=status, method=method, endpoint=endpoint, detail=detail
    )
    self.reset_at = reset_at

reset_at instance-attribute

reset_at = reset_at

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

refuse_unknown_labels(names: tuple[str, ...], known: Container[str], base: str) -> None

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.

Source code in packages/forge/src/livery/forge/_errors.py
def refuse_unknown_labels(
    names: tuple[str, ...], known: Container[str], base: str
) -> None:
    """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*.
    """
    missing = [name for name in names if name not in known]
    if missing:
        raise ForgeError(
            f"labels do not exist on {base}: {', '.join(missing)}."
            " Configure them first.",
            status=422,
        )