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(TypeAlias) –The label of a
TerminalError: what kind of problem it is.
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': anasync defhook 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 aTerminalError. -
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:
-
code(TerminalErrorCode) –The label of the first problem.
-
report(ErrorReport) –The whole
ErrorReport. -
details(tuple[ErrorDetail, ...]) –The problems, each an
ErrorDetail.
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_codewhen 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=....
-
API Reference
xnano
-
xnano -
xnano.ai
ai -
xnano.ai.assets
assets -
xnano.ai.models
models -
xnano.ai.models.art
artArtModelgenerate_async -
xnano.ai.models.decisions
decisions -
xnano.ai.models.state
stateStateModelupdate_async -
xnano.ai.models.text
textTextModel -
xnano.canvas
canvas -
xnano.components
components -
xnano.layout
layout -
xnano.state
stateStateNamespaceset -
xnano.styles
stylesColorSlot -
xnano.terminal
terminalTerminal
-
Methods:
-
__new__–Pick the class that is also
TypeErrororValueErrorfor 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.
__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))
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_codewhen 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
TypeErrororValueErrorfor the code. -
__reduce__–Pickle through the public class, which picks the one for the code again.
Attributes:
-
default_code(TerminalErrorCode) –The code of an error of this class that is raised without one.
-
report(ErrorReport) –The whole report: its title and every problem.
-
details(tuple[ErrorDetail, ...]) –The problems, each an
ErrorDetail. -
code(TerminalErrorCode) –The label of the first problem; see
TerminalErrorCode.
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.
__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))
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_codewhen 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
TypeErrororValueErrorfor the code. -
__reduce__–Pickle through the public class, which picks the one for the code again.
Attributes:
-
default_code(TerminalErrorCode) –The code of an error of this class that is raised without one.
-
report(ErrorReport) –The whole report: its title and every problem.
-
details(tuple[ErrorDetail, ...]) –The problems, each an
ErrorDetail. -
code(TerminalErrorCode) –The label of the first problem; see
TerminalErrorCode.
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.
__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))