Skip to content

xnano.errors

xnano.errors

xnano.errors

Errors a canvas raises about itself, each one a labelled report.

Classes:

  • TerminalError –

    An error a canvas raises about itself: one or more problems, each with a label.

  • TerminalClosedError –

    Raised by a canvas that has been closed, or when no canvas is running.

  • TerminalAlreadyOpenError –

    Raised when a second canvas is opened on the screen while one is already there.

Attributes:

TerminalErrorCode module-attribute

TerminalErrorCode: TypeAlias = Literal['validation.type', 'validation.value', 'validation.bounds', 'validation.keyword', 'canvas.closed', 'canvas.state', 'canvas.composition', 'canvas.thread', 'canvas.timeout', 'canvas.callback', 'canvas.loop', 'screen.already_open', 'screen.unavailable', 'ai.model', 'ai.generation', 'ai.event_loop', 'ai.asset']

The label of a TerminalError: what kind of problem it is.

  • 'validation.type': a value of the wrong type, such as text where a number belongs.
  • 'validation.value': a value of the right type that is not one of the accepted ones.
  • 'validation.bounds': a number outside the range it must be in, such as a size larger than a canvas can be.
  • 'validation.keyword': a keyword the call does not take.
  • 'canvas.closed': the canvas has been closed, or no canvas is running.
  • 'canvas.state': the canvas cannot do this in the state it is in.
  • 'canvas.composition': something cannot be written where it was asked to go.
  • 'canvas.thread': the canvas was used from a thread it does not belong to.
  • 'canvas.timeout': the canvas's loop did not answer in time.
  • 'canvas.callback': a hook or another callback raised on the canvas's loop.
  • 'canvas.loop': an async def hook has no event loop to run on.
  • 'screen.already_open': another canvas is already on the screen.
  • 'screen.unavailable': there is no terminal to draw on.
  • 'ai.model': a language or decision model could not be reached or did not answer.
  • 'ai.generation': a model answered, but its answer could not be made into what was asked for, even after the retries.
  • 'ai.event_loop': a blocking model call was made where waiting would freeze an event loop or the screen.
  • 'ai.asset': a library of examples is not installed, or could not be downloaded or installed.

TerminalError

TerminalError(message: str | ErrorReport, *, code: TerminalErrorCode | None = None, location: str | int | Sequence[str | int] | None = None, hint: str | None = None, title: str = '', **input_value: object)

Bases: ReportedError, RuntimeError

An error a canvas raises about itself: one or more problems, each with a label.

The text of the error is a report in the style of a pydantic ValidationError: how many problems there are, then for each one where it is, what went wrong with its [code=...] and the value it is about, and what to do next. An uncaught TerminalError is printed with colors when the output is a terminal. Every TerminalError is also a RuntimeError; one whose code is 'validation.type' or 'validation.keyword' is also a TypeError, and one whose code is 'validation.value' or 'validation.bounds' is also a ValueError, so except TypeError and except ValueError catch them as well.

Parameters:

  • message (str | ErrorReport) –

    What went wrong, in a sentence, or a whole ErrorReport.

  • code (TerminalErrorCode | None, default: None ) –

    The label of the problem; see TerminalErrorCode. Left out, it is the error class's own: 'canvas.state' for a TerminalError.

  • location (str | int | Sequence[str | int] | None, default: None ) –

    Where the value is, such as 'height' or ('settings', 'height').

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

    What to do next.

  • title (str, default: '' ) –

    What the report is about, such as 'canvas.screen.write()'.

  • input_value (object, default: {} ) –

    The value the problem is about, when there is one.

Attributes:

Examples:

import pytest
from xnano.errors import TerminalError

with pytest.raises(TypeError) as caught:
    raise TerminalError(
        'layer must be a whole number.',
        code='validation.type',
        location='layer',
        input_value='top',
    )
error = caught.value
assert isinstance(error, TerminalError) and error.code == 'validation.type'
assert str(error).splitlines()[1:] == [
    'layer',
    "  layer must be a whole number. [code=validation.type, input_value='top', input_type=str]",
]
assert TerminalError('The canvas cannot step now.').code == 'canvas.state'

Make the report of the error.

Parameters:

  • message (str | ErrorReport) –

    What went wrong, in a sentence, or a whole ErrorReport.

  • code (TerminalErrorCode | None, default: None ) –

    The label of the problem; the class's default_code when left out.

  • location (str | int | Sequence[str | int] | None, default: None ) –

    Where the value is, such as 'height' or ('settings', 'height').

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

    What to do next.

  • title (str, default: '' ) –

    What the report is about, such as 'canvas.screen.write()'.

  • input_value (object, default: {} ) –

    The value the problem is about, given as input_value=....

Methods:

  • __new__ –

    Pick the class that is also TypeError or ValueError for the code.

  • __reduce__ –

    Pickle through the public class, which picks the one for the code again.

Source code in xnano/errors.py
def __init__(
    self,
    message: str | _ErrorReport,
    *,
    code: TerminalErrorCode | None = None,
    location: str | int | Sequence[str | int] | None = None,
    hint: str | None = None,
    title: str = '',
    **input_value: object,
) -> None:
    """
    Make the report of the error.

    Args:
        message: What went wrong, in a sentence, or a whole ``ErrorReport``.
        code: The label of the problem; the class's ``default_code`` when left out.
        location: Where the value is, such as ``'height'`` or ``('settings', 'height')``.
        hint: What to do next.
        title: What the report is about, such as ``'canvas.screen.write()'``.
        input_value: The value the problem is about, given as ``input_value=...``.
    """
    if isinstance(message, _ErrorReport):
        report = message
    else:
        detail = _ErrorDetail(
            code or type(self).default_code,
            message,
            location=location,
            hint=hint,
            **input_value,
        )
        report = _ErrorReport(title, [detail])
    super().__init__(report)

default_code class-attribute

default_code: TerminalErrorCode = 'canvas.state'

The code of an error of this class that is raised without one.

report property

report: ErrorReport

The whole report: its title and every problem.

details property

details: tuple[ErrorDetail, ...]

The problems, each an ErrorDetail.

code property

The label of the first problem; see TerminalErrorCode.

__new__

__new__(message: str | ErrorReport, *arguments: object, code: TerminalErrorCode | None = None, **keywords: object) -> Self

Pick the class that is also TypeError or ValueError for the code.

Source code in xnano/errors.py
def __new__(
    cls,
    message: str | _ErrorReport,
    *arguments: object,
    code: TerminalErrorCode | None = None,
    **keywords: object,
) -> Self:
    """Pick the class that is also ``TypeError`` or ``ValueError`` for the code."""
    chosen: type[TerminalError] = cls
    if cls is TerminalError:
        first_code = (
            message.details[0].code if isinstance(message, _ErrorReport) else code
        )
        if first_code in _TYPE_CODES:
            chosen = _TerminalTypeError
        elif first_code in _VALUE_CODES:
            chosen = _TerminalValueError
    return cast('Self', _ReportedError.__new__(chosen))

__reduce__

__reduce__() -> tuple[type[TerminalError], tuple[object, ...]]

Pickle through the public class, which picks the one for the code again.

Source code in xnano/errors.py
def __reduce__(self) -> tuple[type[TerminalError], tuple[object, ...]]:
    """Pickle through the public class, which picks the one for the code again."""
    public = TerminalError if type(self) in _HIDDEN_CLASSES else type(self)
    return (public, self.args)

TerminalClosedError

TerminalClosedError(message: str | ErrorReport, *, code: TerminalErrorCode | None = None, location: str | int | Sequence[str | int] | None = None, hint: str | None = None, title: str = '', **input_value: object)

Bases: TerminalError

Raised by a canvas that has been closed, or when no canvas is running.

Make the report of the error.

Parameters:

  • message (str | ErrorReport) –

    What went wrong, in a sentence, or a whole ErrorReport.

  • code (TerminalErrorCode | None, default: None ) –

    The label of the problem; the class's default_code when left out.

  • location (str | int | Sequence[str | int] | None, default: None ) –

    Where the value is, such as 'height' or ('settings', 'height').

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

    What to do next.

  • title (str, default: '' ) –

    What the report is about, such as 'canvas.screen.write()'.

  • input_value (object, default: {} ) –

    The value the problem is about, given as input_value=....

Methods:

  • __new__ –

    Pick the class that is also TypeError or ValueError for the code.

  • __reduce__ –

    Pickle through the public class, which picks the one for the code again.

Attributes:

Source code in xnano/errors.py
def __init__(
    self,
    message: str | _ErrorReport,
    *,
    code: TerminalErrorCode | None = None,
    location: str | int | Sequence[str | int] | None = None,
    hint: str | None = None,
    title: str = '',
    **input_value: object,
) -> None:
    """
    Make the report of the error.

    Args:
        message: What went wrong, in a sentence, or a whole ``ErrorReport``.
        code: The label of the problem; the class's ``default_code`` when left out.
        location: Where the value is, such as ``'height'`` or ``('settings', 'height')``.
        hint: What to do next.
        title: What the report is about, such as ``'canvas.screen.write()'``.
        input_value: The value the problem is about, given as ``input_value=...``.
    """
    if isinstance(message, _ErrorReport):
        report = message
    else:
        detail = _ErrorDetail(
            code or type(self).default_code,
            message,
            location=location,
            hint=hint,
            **input_value,
        )
        report = _ErrorReport(title, [detail])
    super().__init__(report)

default_code class-attribute

default_code: TerminalErrorCode = 'canvas.closed'

The code of an error of this class that is raised without one.

report property

report: ErrorReport

The whole report: its title and every problem.

details property

details: tuple[ErrorDetail, ...]

The problems, each an ErrorDetail.

code property

The label of the first problem; see TerminalErrorCode.

__new__

__new__(message: str | ErrorReport, *arguments: object, code: TerminalErrorCode | None = None, **keywords: object) -> Self

Pick the class that is also TypeError or ValueError for the code.

Source code in xnano/errors.py
def __new__(
    cls,
    message: str | _ErrorReport,
    *arguments: object,
    code: TerminalErrorCode | None = None,
    **keywords: object,
) -> Self:
    """Pick the class that is also ``TypeError`` or ``ValueError`` for the code."""
    chosen: type[TerminalError] = cls
    if cls is TerminalError:
        first_code = (
            message.details[0].code if isinstance(message, _ErrorReport) else code
        )
        if first_code in _TYPE_CODES:
            chosen = _TerminalTypeError
        elif first_code in _VALUE_CODES:
            chosen = _TerminalValueError
    return cast('Self', _ReportedError.__new__(chosen))

__reduce__

__reduce__() -> tuple[type[TerminalError], tuple[object, ...]]

Pickle through the public class, which picks the one for the code again.

Source code in xnano/errors.py
def __reduce__(self) -> tuple[type[TerminalError], tuple[object, ...]]:
    """Pickle through the public class, which picks the one for the code again."""
    public = TerminalError if type(self) in _HIDDEN_CLASSES else type(self)
    return (public, self.args)

TerminalAlreadyOpenError

TerminalAlreadyOpenError(message: str | ErrorReport, *, code: TerminalErrorCode | None = None, location: str | int | Sequence[str | int] | None = None, hint: str | None = None, title: str = '', **input_value: object)

Bases: TerminalError

Raised when a second canvas is opened on the screen while one is already there.

Make the report of the error.

Parameters:

  • message (str | ErrorReport) –

    What went wrong, in a sentence, or a whole ErrorReport.

  • code (TerminalErrorCode | None, default: None ) –

    The label of the problem; the class's default_code when left out.

  • location (str | int | Sequence[str | int] | None, default: None ) –

    Where the value is, such as 'height' or ('settings', 'height').

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

    What to do next.

  • title (str, default: '' ) –

    What the report is about, such as 'canvas.screen.write()'.

  • input_value (object, default: {} ) –

    The value the problem is about, given as input_value=....

Methods:

  • __new__ –

    Pick the class that is also TypeError or ValueError for the code.

  • __reduce__ –

    Pickle through the public class, which picks the one for the code again.

Attributes:

Source code in xnano/errors.py
def __init__(
    self,
    message: str | _ErrorReport,
    *,
    code: TerminalErrorCode | None = None,
    location: str | int | Sequence[str | int] | None = None,
    hint: str | None = None,
    title: str = '',
    **input_value: object,
) -> None:
    """
    Make the report of the error.

    Args:
        message: What went wrong, in a sentence, or a whole ``ErrorReport``.
        code: The label of the problem; the class's ``default_code`` when left out.
        location: Where the value is, such as ``'height'`` or ``('settings', 'height')``.
        hint: What to do next.
        title: What the report is about, such as ``'canvas.screen.write()'``.
        input_value: The value the problem is about, given as ``input_value=...``.
    """
    if isinstance(message, _ErrorReport):
        report = message
    else:
        detail = _ErrorDetail(
            code or type(self).default_code,
            message,
            location=location,
            hint=hint,
            **input_value,
        )
        report = _ErrorReport(title, [detail])
    super().__init__(report)

default_code class-attribute

default_code: TerminalErrorCode = 'screen.already_open'

The code of an error of this class that is raised without one.

report property

report: ErrorReport

The whole report: its title and every problem.

details property

details: tuple[ErrorDetail, ...]

The problems, each an ErrorDetail.

code property

The label of the first problem; see TerminalErrorCode.

__new__

__new__(message: str | ErrorReport, *arguments: object, code: TerminalErrorCode | None = None, **keywords: object) -> Self

Pick the class that is also TypeError or ValueError for the code.

Source code in xnano/errors.py
def __new__(
    cls,
    message: str | _ErrorReport,
    *arguments: object,
    code: TerminalErrorCode | None = None,
    **keywords: object,
) -> Self:
    """Pick the class that is also ``TypeError`` or ``ValueError`` for the code."""
    chosen: type[TerminalError] = cls
    if cls is TerminalError:
        first_code = (
            message.details[0].code if isinstance(message, _ErrorReport) else code
        )
        if first_code in _TYPE_CODES:
            chosen = _TerminalTypeError
        elif first_code in _VALUE_CODES:
            chosen = _TerminalValueError
    return cast('Self', _ReportedError.__new__(chosen))

__reduce__

__reduce__() -> tuple[type[TerminalError], tuple[object, ...]]

Pickle through the public class, which picks the one for the code again.

Source code in xnano/errors.py
def __reduce__(self) -> tuple[type[TerminalError], tuple[object, ...]]:
    """Pickle through the public class, which picks the one for the code again."""
    public = TerminalError if type(self) in _HIDDEN_CLASSES else type(self)
    return (public, self.args)