Module astrapy.exceptions.devops_api_exceptions

Classes

class DevOpsAPIErrorDescriptor (error_dict: dict[str, Any])

Expand source code

@dataclass
class DevOpsAPIErrorDescriptor:
    """
    An object representing a single error returned from the DevOps API,
    typically with an error code and a text message.

    A single response from the Devops API may return zero, one or more of these.

    Attributes:
        id: a numeric code as found in the API "ID" item.
        message: the text found in the API "error" item.
        attributes: a dict with any further key-value pairs returned by the API.
    """

    id: int | None
    message: str | None
    attributes: dict[str, Any]

    def __init__(self, error_dict: dict[str, Any]) -> None:
        self.id = error_dict.get("ID")
        self.message = error_dict.get("message")
        self.attributes = {
            k: v for k, v in error_dict.items() if k not in {"ID", "message"}
        }

An object representing a single error returned from the DevOps API, typically with an error code and a text message.

A single response from the Devops API may return zero, one or more of these.

Attributes

id

a numeric code as found in the API "ID" item.

message

the text found in the API "error" item.

attributes

a dict with any further key-value pairs returned by the API.

Instance variables

var attributes : dict[str, typing.Any]

The type of the None singleton.

var id : int | None

The type of the None singleton.

var message : str | None

The type of the None singleton.

class DevOpsAPIException (text: str | None = None)

Expand source code

class DevOpsAPIException(Exception):
    """
    An exception specific to issuing requests to the DevOps API.
    """

    def __init__(self, text: str | None = None):
        Exception.__init__(self, text or "")

An exception specific to issuing requests to the DevOps API.

Ancestors

• builtins.Exception
• builtins.BaseException

Subclasses

• DevOpsAPIHttpException
• DevOpsAPIResponseException
• DevOpsAPITimeoutException
• UnexpectedDevOpsAPIResponseException

class DevOpsAPIHttpException (text: str | None,
*,
httpx_error: httpx.HTTPStatusError,
error_descriptors: list[DevOpsAPIErrorDescriptor])

Expand source code

@dataclass
class DevOpsAPIHttpException(DevOpsAPIException, httpx.HTTPStatusError):
    """
    A request to the DevOps API resulted in an HTTP 4xx or 5xx response.

    Though the DevOps API seldom enriches such errors with a response text,
    this class acts as the DevOps counterpart to DataAPIHttpException
    to facilitate a symmetryc handling of errors at application lebel.

    Attributes:
        text: a text message about the exception.
        error_descriptors: a list of all DevOpsAPIErrorDescriptor objects
            found in the response.
    """

    text: str | None
    error_descriptors: list[DevOpsAPIErrorDescriptor]

    def __init__(
        self,
        text: str | None,
        *,
        httpx_error: httpx.HTTPStatusError,
        error_descriptors: list[DevOpsAPIErrorDescriptor],
    ) -> None:
        DevOpsAPIException.__init__(self, text)
        httpx.HTTPStatusError.__init__(
            self,
            message=str(httpx_error),
            request=httpx_error.request,
            response=httpx_error.response,
        )
        self.text = text
        self.httpx_error = httpx_error
        self.error_descriptors = error_descriptors

    def __str__(self) -> str:
        return self.text or str(self.httpx_error)

    @classmethod
    def from_httpx_error(
        cls,
        httpx_error: httpx.HTTPStatusError,
        **kwargs: Any,
    ) -> DevOpsAPIHttpException:
        """Parse a httpx status error into this exception."""

        dictforced_response: dict[str, Any]
        # the attempt to extract a response structure cannot afford failure.
        try:
            raw_response = httpx_error.response.json()
            if isinstance(raw_response, dict):
                dictforced_response = raw_response
            else:
                dictforced_response = {}
        except Exception:
            dictforced_response = {}
        error_descriptors = [
            DevOpsAPIErrorDescriptor(error_dict)
            for error_dict in dictforced_response.get("errors") or []
        ]
        if error_descriptors:
            text = f"{error_descriptors[0].message}. {str(httpx_error)}"
        else:
            text = str(httpx_error)

        return cls(
            text=text,
            httpx_error=httpx_error,
            error_descriptors=error_descriptors,
            **kwargs,
        )

A request to the DevOps API resulted in an HTTP 4xx or 5xx response.

Though the DevOps API seldom enriches such errors with a response text, this class acts as the DevOps counterpart to DataAPIHttpException to facilitate a symmetryc handling of errors at application lebel.

Attributes

text

a text message about the exception.

error_descriptors

a list of all DevOpsAPIErrorDescriptor objects found in the response.

Ancestors

• DevOpsAPIException
• httpx.HTTPStatusError
• httpx.HTTPError
• builtins.Exception
• builtins.BaseException

Static methods

def from_httpx_error(httpx_error: httpx.HTTPStatusError, **kwargs: Any) ‑> DevOpsAPIHttpException

Parse a httpx status error into this exception.

Instance variables

var error_descriptors : list[DevOpsAPIErrorDescriptor]

The type of the None singleton.

var text : str | None

The type of the None singleton.

class DevOpsAPIResponseException (text: str | None = None,
*,
command: dict[str, Any] | None = None,
error_descriptors: list[DevOpsAPIErrorDescriptor] = [])

Expand source code

class DevOpsAPIResponseException(DevOpsAPIException):
    """
    A request to the DevOps API returned with a non-success return code
    and one of more errors in the HTTP response.

    Attributes:
        text: a text message about the exception.
        command: the raw payload that was sent to the DevOps API.
        error_descriptors: a list of all DevOpsAPIErrorDescriptor objects
            returned by the API in the response.
    """

    text: str | None
    command: dict[str, Any] | None
    error_descriptors: list[DevOpsAPIErrorDescriptor]

    def __init__(
        self,
        text: str | None = None,
        *,
        command: dict[str, Any] | None = None,
        error_descriptors: list[DevOpsAPIErrorDescriptor] = [],
    ) -> None:
        super().__init__(text or self.__class__.__name__)
        self.text = text
        self.command = command
        self.error_descriptors = error_descriptors

    @staticmethod
    def from_response(
        command: dict[str, Any] | None,
        raw_response: dict[str, Any],
    ) -> DevOpsAPIResponseException:
        """Parse a raw response from the API into this exception."""

        dictforced_response = raw_response if isinstance(raw_response, dict) else {}
        error_descriptors = [
            DevOpsAPIErrorDescriptor(error_dict)
            for error_dict in dictforced_response.get("errors") or []
        ]
        if error_descriptors:
            _text = error_descriptors[0].message
        else:
            _text = None
        return DevOpsAPIResponseException(
            text=_text, command=command, error_descriptors=error_descriptors
        )

A request to the DevOps API returned with a non-success return code and one of more errors in the HTTP response.

Attributes

text

a text message about the exception.

command

the raw payload that was sent to the DevOps API.

error_descriptors

a list of all DevOpsAPIErrorDescriptor objects returned by the API in the response.

Ancestors

• DevOpsAPIException
• builtins.Exception
• builtins.BaseException

Class variables

var command : dict[str, typing.Any] | None

The type of the None singleton.

var error_descriptors : list[DevOpsAPIErrorDescriptor]

The type of the None singleton.

var text : str | None

The type of the None singleton.

Static methods

def from_response(command: dict[str, Any] | None, raw_response: dict[str, Any]) ‑> DevOpsAPIResponseException

Expand source code

@staticmethod
def from_response(
    command: dict[str, Any] | None,
    raw_response: dict[str, Any],
) -> DevOpsAPIResponseException:
    """Parse a raw response from the API into this exception."""

    dictforced_response = raw_response if isinstance(raw_response, dict) else {}
    error_descriptors = [
        DevOpsAPIErrorDescriptor(error_dict)
        for error_dict in dictforced_response.get("errors") or []
    ]
    if error_descriptors:
        _text = error_descriptors[0].message
    else:
        _text = None
    return DevOpsAPIResponseException(
        text=_text, command=command, error_descriptors=error_descriptors
    )

Parse a raw response from the API into this exception.

class DevOpsAPITimeoutException (text: str, *, timeout_type: str, endpoint: str | None, raw_payload: str | None)

Expand source code

@dataclass
class DevOpsAPITimeoutException(DevOpsAPIException):
    """
    A DevOps API operation timed out.

    Attributes:
        text: a textual description of the error
        timeout_type: this denotes the phase of the HTTP request when the event
            occurred ("connect", "read", "write", "pool") or "generic" if there is
            not a specific request associated to the exception.
        endpoint: if the timeout is tied to a specific request, this is the
            URL that the request was targeting.
        raw_payload:  if the timeout is tied to a specific request, this is the
            associated payload (as a string).
    """

    text: str
    timeout_type: str
    endpoint: str | None
    raw_payload: str | None

    def __init__(
        self,
        text: str,
        *,
        timeout_type: str,
        endpoint: str | None,
        raw_payload: str | None,
    ) -> None:
        super().__init__(text)
        self.text = text
        self.timeout_type = timeout_type
        self.endpoint = endpoint
        self.raw_payload = raw_payload

A DevOps API operation timed out.

Attributes

text

a textual description of the error

timeout_type

this denotes the phase of the HTTP request when the event occurred ("connect", "read", "write", "pool") or "generic" if there is not a specific request associated to the exception.

endpoint

if the timeout is tied to a specific request, this is the URL that the request was targeting.

raw_payload

if the timeout is tied to a specific request, this is the associated payload (as a string).

Ancestors

• DevOpsAPIException
• builtins.Exception
• builtins.BaseException

Instance variables

var endpoint : str | None

The type of the None singleton.

var raw_payload : str | None

The type of the None singleton.

var text : str

The type of the None singleton.

var timeout_type : str

The type of the None singleton.

class UnexpectedDevOpsAPIResponseException (text: str, raw_response: dict[str, Any] | None)

Expand source code

@dataclass
class UnexpectedDevOpsAPIResponseException(DevOpsAPIException):
    """
    The DevOps API response is malformed in that it does not have
    expected field(s), or they are of the wrong type.

    Attributes:
        text: a text message about the exception.
        raw_response: the response returned by the API in the form of a dict.
    """

    text: str
    raw_response: dict[str, Any] | None

    def __init__(
        self,
        text: str,
        raw_response: dict[str, Any] | None,
    ) -> None:
        super().__init__(text)
        self.text = text
        self.raw_response = raw_response

The DevOps API response is malformed in that it does not have expected field(s), or they are of the wrong type.

Attributes

text

a text message about the exception.

raw_response

the response returned by the API in the form of a dict.

Ancestors

• DevOpsAPIException
• builtins.Exception
• builtins.BaseException

Instance variables

var raw_response : dict[str, typing.Any] | None

The type of the None singleton.

var text : str

The type of the None singleton.