Source code for pyvergeos.exceptions

"""Custom exceptions for pyvergeos.

Note: Exception names are prefixed with 'Verge' to avoid shadowing
Python builtins (ConnectionError, TimeoutError).
"""

from typing import Any, Optional


[docs] class VergeError(Exception): """Base exception for all pyvergeos errors.""" pass
[docs] class VergeConnectionError(VergeError): """Connection to VergeOS failed.""" pass
[docs] class NotConnectedError(VergeError): """Operation attempted without an active connection.""" pass
[docs] class VergeTimeoutError(VergeError): """Request timed out.""" pass
[docs] class APIError(VergeError): """Base class for API errors. Attributes: status_code: HTTP status code, when available. response_body: Complete parsed JSON error body, or raw text for non-JSON responses. Defaults to None for errors without a response body. May contain sensitive data; inspect it before logging or sharing it. """
[docs] def __init__( self, message: str, status_code: Optional[int] = None, *, response_body: Any = None ) -> None: super().__init__(message) self.status_code = status_code self.response_body = response_body
[docs] class AuthenticationError(APIError): """Authentication failed (401/403).""" pass
[docs] class NotFoundError(APIError): """Resource not found (404).""" pass
[docs] class ConflictError(APIError): """Resource conflict (409).""" pass
[docs] class ValidationError(APIError): """Validation error (422).""" pass
[docs] class FieldNotProjectedError(VergeError): """An accessor's backing field was not included in the projection. Raised instead of inventing a value when the field an accessor reads is absent from the row, which happens whenever the caller narrowed ``fields`` (issue #117). Before this existed, ``is_running`` answered ``False`` for a running VM and ``status`` answered ``"unknown"`` -- indistinguishable from a real answer, and exactly the guard a caller puts in front of a destructive operation. Deliberately *not* an ``AttributeError``. ``ResourceObject.__getattr__`` is the dict fallback, and Python calls it whenever normal attribute lookup raises ``AttributeError`` -- so an ``AttributeError`` subclass raised inside a property is swallowed and re-raised as a bare "has no attribute", losing the diagnostic. It would also make ``hasattr()`` answer ``False`` for a field that exists but was not fetched, which is the same silent lie in a new place. Attributes: field: Name of the field that was not projected. """
[docs] def __init__(self, field: str, owner: str = "resource") -> None: self.field = field super().__init__( f"{owner} has no {field!r} field: it was not included in the " f"projection, so no value can be reported. Re-fetch with the " f"manager's default fields, or add {field!r} to the fields " f"argument." )
[docs] class TaskError(VergeError): """Task execution failed."""
[docs] def __init__(self, message: str, task_id: Optional[int] = None) -> None: super().__init__(message) self.task_id = task_id
[docs] class TaskTimeoutError(TaskError): """Task wait timed out.""" pass