heros.exceptions
================

.. py:module:: heros.exceptions

.. autoapi-nested-parse::

   Exceptions raised by HEROS, in particular those transported from a remote HERO.



Attributes
----------

.. autoapisummary::

   heros.exceptions.ERROR_MARKER
   heros.exceptions._error_classes
   heros.exceptions._mapping_blacklist


Exceptions
----------

.. autoapisummary::

   heros.exceptions.HEROSError
   heros.exceptions.RemoteHEROError
   heros.exceptions.RemoteTransportError


Functions
---------

.. autoapisummary::

   heros.exceptions._error_class


Module Contents
---------------

.. py:data:: ERROR_MARKER
   :value: '__heros_error__'


.. py:exception:: HEROSError

   Bases: :py:obj:`Exception`


   Base class of all HEROS errors.


.. py:exception:: RemoteHEROError(message: str, remote_type: str | None = None, remote_module: str | None = None, remote_traceback: str | None = None, endpoint: str | None = None)

   Bases: :py:obj:`HEROSError`


   An exception that was raised inside a remote HERO while serving a request.

   :param message: the ``str`` of the remote exception.
   :param remote_type: class name of the remote exception, if the remote sent one.
   :param remote_traceback: formatted traceback from the remote process.
   :param endpoint: the endpoint that was queried.


   .. py:attribute:: message


   .. py:attribute:: remote_type
      :value: None



   .. py:attribute:: remote_module
      :value: None



   .. py:attribute:: remote_traceback
      :value: None



   .. py:attribute:: endpoint
      :value: None



   .. py:method:: from_exception(exc: BaseException, endpoint: str | None = None)
      :classmethod:



   .. py:method:: from_payload(payload: Any, endpoint: str | None = None)
      :classmethod:


      Rebuild a remote exception from a serialized payload.

      All payloads that do not have the correct format (dict with error marker) are
      wrapped in a bare :class:`RemoteHEROError` so that old HEROs keep working.



   .. py:method:: __str__() -> str

      Return str(self).



   .. py:method:: serialize() -> dict[str, Any]

      Turn an exception into a payload that :func:`exception_from_payload` can rebuild.



.. py:exception:: RemoteTransportError

   Bases: :py:obj:`HEROSError`


   The query to a remote HERO failed at transport level (interrupted stream, ...).


.. py:data:: _error_classes
   :type:  dict[str, type]

.. py:data:: _mapping_blacklist

.. py:function:: _error_class(remote_type: str | None) -> type

   Build (and cache) an exception class that is both a ``RemoteHEROError`` and, where
   the remote exception is a builtin, that builtin.

   This lets user code keep writing ``except ValueError:`` around a remote call while the
   HEROS-specific information stays available on the exception object.