academy.exception

academy/exception.py

ActionCancelledError

ActionCancelledError()

Bases: Exception

Action was cancelled by the agent.

This often happens when an agent is shutdown mid-action execution and configured to cancel running actions.

Source code in academy/exception.py

def __init__(self) -> None:
    super().__init__('Action was cancelled by the agent.')

ActionInvalidStateError

ActionInvalidStateError()

Bases: Exception

Action was in an invalid state to be cancelled.

This most often happens when an action has completed and is then cancelled.

Source code in academy/exception.py

def __init__(self) -> None:
    super().__init__('Action state invalid.')

AgentNotInitializedError

AgentNotInitializedError()

Bases: Exception

Agent runtime context has not been initialized.

This error is typically raised when accessing the runtime context for an agent before the agent has been executed.

Source code in academy/exception.py

def __init__(self) -> None:
    super().__init__(
        'Agent runtime context has not been initialized. '
        'Has the agent been started?',
    )

PingCancelledError

PingCancelledError()

Bases: Exception

Ping cancelled before response.

This error is typically raised when an agent receives a message before startup, then exits while starting.

Source code in academy/exception.py

def __init__(self) -> None:
    super().__init__(
        'Ping was cancelled. Agent may have exited before starting.',
    )

ExchangeError

Bases: Exception

Base type for exchange related errors.

BadEntityIdError

BadEntityIdError(uid: EntityId)

Bases: ExchangeError

Entity associated with the identifier is unknown.

Source code in academy/exception.py

def __init__(self, uid: EntityId) -> None:
    super().__init__(f'Unknown identifier {uid}.')
    self.uid = uid

ForbiddenError

Bases: ExchangeError

Exchange client does not have permission to access resources.

MessageTooLargeError

MessageTooLargeError(size: int, limit: int)

Bases: ExchangeError

Message payload is too large for exchange.

If encountering this error, consider using the ProxyStoreExchangeTransport class an way to bypass the exchange for large data.

Source code in academy/exception.py

def __init__(self, size: int, limit: int) -> None:
    self.size = size
    self.limit = limit

    super().__init__(
        f'Message of size {size} bytes is larger than limit {limit}.',
    )

MailboxTerminatedError

MailboxTerminatedError(uid: EntityId)

Bases: ExchangeError

Entity mailbox is terminated and cannot send or receive messages.

Constructing this error type implicitly returns one of the derived types, AgentTerminatedError or UserTerminatedError, based on the entity type.

Source code in academy/exception.py

def __init__(self, uid: EntityId) -> None:
    super().__init__(f'Mailbox for {uid} has been terminated.')
    self.uid = uid

AgentTerminatedError

AgentTerminatedError(uid: AgentId[Any])

Bases: MailboxTerminatedError

Agent mailbox is terminated and cannot send or receive messages.

Source code in academy/exception.py

def __init__(self, uid: AgentId[Any]) -> None:
    super().__init__(uid)

UserTerminatedError

UserTerminatedError(uid: UserId)

Bases: MailboxTerminatedError

User mailbox is terminated and cannot send or receive messages.

Source code in academy/exception.py

def __init__(self, uid: UserId) -> None:
    super().__init__(uid)

UnauthorizedError

Bases: ExchangeError

Exchange client has not provided valid authentication credentials.

ExchangeClientNotFoundError

ExchangeClientNotFoundError(aid: AgentId[Any])

Bases: Exception

Handle to agent can not find an exchange client to use.

A Handle is initialized with a target agent ID is not used in a context where an exchange client could be inferred. Typically this can be resolved by using a ExchangeClient or Manager as a context manager. If this error happens within an agent, it likely means the agent was not started.

Source code in academy/exception.py

def __init__(self, aid: AgentId[Any]) -> None:
    super().__init__(
        f'Handle to {aid} can not find an exchange client to use. See the '
        'exception docstring for troubleshooting.',
    )
    self.aid = aid

DeserializationMethodProhibitedError

Bases: Exception

Deserialization prohibited.

Request argument or results are serialized using a method that is prohibtted from being deserialized in the current context.

ExceptionSerializationError

ExceptionSerializationError(
    exception_name: str, serializer: str
)

Bases: Exception

Error when serializing an exception.

An action attempted to return an exception, but that exception could not be serialized using the method provided.

Source code in academy/exception.py

def __init__(self, exception_name: str, serializer: str) -> None:
    super().__init__(
        f'Exception {exception_name} could not be serialized using '
        f'method {serializer}. Either change `exception_serialization` in'
        'the action invocation, or ensure the exception can be '
        'serialized.',
    )
    self.exception_name = exception_name
    self.serializer = serializer

AcademyRemoteError

Bases: Exception

Generalized exception for serializing remote exceptions.

Any exception raised that is JSON serialized loses its type. To raise the original exception, change exception_serialization in the action invocation.

IncompatibleNetworkProtocolError

IncompatibleNetworkProtocolError(
    version: str | None = None,
    cur_version: str | None = None,
)

Bases: Exception

Received message incompatible with this version.

Source code in academy/exception.py

def __init__(
    self,
    version: str | None = None,
    cur_version: str | None = None,
) -> None:
    super().__init__(
        'Incompatible academy network protocol. The network protocol '
        'version needs to match between communicating agents and the '
        f'exchange. Remote version {version}, current version '
        f'{cur_version}',
    )
    self.version = version
    self.cur_version = cur_version

raise_exceptions

raise_exceptions(
    exceptions: Iterable[BaseException],
    *,
    message: str | None = None
) -> None

Raise exceptions as a group.

Raises a set of exceptions as an ExceptionGroup in Python 3.11 and later. If only one exception is provided, it is raised directly. In Python 3.10 and older, only one exception is raised.

This is a no-op if the size of exceptions is zero.

Parameters:

• exceptions (Iterable[BaseException]) –

  An iterable of exceptions to raise.

• message (str | None, default: None ) –

  Custom error message for the exception group.

Source code in academy/exception.py

def raise_exceptions(
    exceptions: Iterable[BaseException],
    *,
    message: str | None = None,
) -> None:
    """Raise exceptions as a group.

    Raises a set of exceptions as an [`ExceptionGroup`][ExceptionGroup]
    in Python 3.11 and later. If only one exception is provided, it is raised
    directly. In Python 3.10 and older, only one exception is raised.

    This is a no-op if the size of `exceptions` is zero.

    Args:
        exceptions: An iterable of exceptions to raise.
        message: Custom error message for the exception group.
    """
    excs = tuple(exceptions)
    if len(excs) == 0:
        return

    if sys.version_info >= (3, 11) and len(excs) > 1:  # pragma: >=3.11 cover
        message = (
            message if message is not None else 'Caught multiple exceptions!'
        )
        # Note that BaseExceptionGroup will return ExceptionGroup if all
        # of the errors are Exception, rather than BaseException, so that this
        # can be caught by "except Exception".
        raise BaseExceptionGroup(message, excs)  # noqa: F821
    else:  # pragma: <3.11 cover
        raise excs[0]