xtr_serializer.exception ¶
Every error this package raises, each deriving from :class:SerializerError.
One except SerializerError catches them all; a narrower one handles a single
cause. The errors that describe a value — :class:NotNormalizableValueError and
its subclasses, :class:PartialDenormalizationError and :class:UnsupportedFormatError
— keep what went wrong as typed attributes and compose their messages from those,
so the message never repeats the value. The others take a plain message from the
code that raises them, and are only as safe as that code. None of them takes the
value itself, but a traceback renders the chained exception too: raise these
errors without from on an exception that carries the value.
CircularReferenceError ¶
Bases: SerializerError, RuntimeError
A value contains itself, so it has no plain form to write.
Plain data is a tree: an object reachable from itself — an order holding a line that points back at the order — would never finish being written. It is refused rather than cut short, because a value written with a gap in it reads back as a different value.
Also a :class:RuntimeError: the cycle is in the objects the application
built, a mistake to fix in the code, not data from outside to refuse.
ExtraAttributesError ¶
ExtraAttributesError(extra_attributes: tuple[str, ...], *, path: str | None = None, expected_types: tuple[str, ...] = (), current_type: str | None = None, error_type: str | None = None)
Bases: NotNormalizableValueError
Data for an object carried attributes its type does not declare.
Raised when the reading side is set to refuse what it does not know rather than drop it — for data from a client that should hear about a misspelled field instead of having it silently ignored. It is one more value that did not fit, so it is collected with the others when every error is wanted.
The message names the attributes, quoted as the path is, and leaves out what they held.
Attributes:
Record the attributes the type does not declare, and where the data had them.
Raises:
-
InvalidArgumentError–If
extra_attributesis empty. No attribute is extra, so there is nothing to refuse; raising this error anyway is a mistake in the code that raises it.
InvalidArgumentError ¶
Bases: SerializerError, ValueError
An argument the serializer was given cannot be used, whatever data comes next.
It is about how the serializer is called or configured, not about what it
converts: data that does not fit is an
:class:UnexpectedValueError <xtr_serializer.exception.UnexpectedValueError>.
Also a :class:ValueError, so code that already guards what it passes with
except ValueError catches it without learning a new exception.
LogicError ¶
Bases: SerializerError, RuntimeError
The serializer was put together or used in a way no input could make right.
A serializer with nothing able to convert the objects it is handed, a class hierarchy registered inconsistently: the data is not to blame, the code is, and the fix belongs in the application rather than in what it was sent.
Also a :class:RuntimeError, because that is what a worker's own error
handling already catches.
MappingError ¶
Bases: LogicError
A class hierarchy was registered for serialization in a way that cannot work.
The names registered for the classes of a hierarchy are what lets written data say which class it came from, so they must be unambiguous: one name for two classes, a name on a class outside the hierarchy it is registered in, or a name written under a key that a field also uses would each make some value read back as the wrong class. Raised when the classes are registered, so the mistake shows when the module is imported rather than when the first value fails to come back.
NotEncodableValueError ¶
Bases: UnexpectedValueError
Plain data has no form in the requested format, or text is not valid in it.
The encoder's error, on either side of it: writing a float JSON has no form for, such as infinity, or reading text that is not valid JSON. Raised rather than written approximately, because text that does not say exactly what was meant is read back as something else.
NotNormalizableValueError ¶
NotNormalizableValueError(message: str, *, path: str | None = None, expected_types: tuple[str, ...] = (), current_type: str | None = None, error_type: str | None = None)
Bases: UnexpectedValueError
A value cannot be turned into plain data, or plain data into the type asked for.
Raised on both sides of the conversion: writing a value that has no exact plain form, or reading data that does not fit the declared type — a string where a number belongs, a required field missing. What is read mostly comes from someone else and may hold a password or a token, so the message is put together from the attributes below and nothing else: where the value sits and which types were involved, never the value. The path and the type names are quoted, so a key taken from the data cannot break the message across lines.
Attributes:
-
message(str) –What is wrong with the value, in words that do not quote it.
-
path(str | None) –Where the value sits in what was being converted, such as
"items[0].price";Nonefor the value as a whole. -
expected_types(tuple[str, ...]) –The names of the types the value could have had.
-
current_type(str | None) –The name of the type it had, when known.
-
error_type(str | None) –A short code for the kind of problem, such as
"missing", for a program to act on; the message leaves it out.
Record what is wrong with the value and where, without the value itself.
PartialDenormalizationError ¶
Bases: UnexpectedValueError
Data was read to the end, and some of its values did not fit their types.
Raised in place of the first error when the reading side is asked to collect every error, so a form or an API request can be answered with everything that is wrong at once rather than one field per attempt.
The message lists the errors, each by its path and types. The data is never part of it: it is what someone sent, and may hold a secret.
Attributes:
-
data(object) –What was being denormalized — for the code handling the error to use, never for the message.
-
errors(tuple[NotNormalizableValueError, ...]) –One error for each value that did not fit, each naming its path.
Record the data that was read and every error found in it.
Raises:
-
InvalidArgumentError–If
errorsis empty. Nothing was found, so there is nothing to report; raising this error anyway is a mistake in the code that raises it.
SerializerError ¶
Bases: Exception
Something the serializer could not do — catch this to catch them all.
Serialization happens at the edges of an application: a request body read
in, a message written to a queue. One except there has to answer for
anything that went wrong, and this is that one; a subclass tells one cause
from another — data that does not fit its type, a format nothing reads, a
class hierarchy registered wrongly.
No error of this package repeats a value it was handed. What goes through a serializer is often what an application must keep out of its logs — a password, a token, a customer's address — so a message says where the problem is and which types were involved, never what the value was.
That holds only while callers keep the value out of the chain: an error
raised from an exception that carries the value puts that value into the
traceback, which is rendered whatever the message says. Raise these errors
without chaining the input-bearing exception — catch it and raise the error
with its typed fields, and no from clause.
UnexpectedValueError ¶
Bases: SerializerError, ValueError
A value, or the data read for one, cannot become what the serializer was asked for.
The family of errors about the data itself, as opposed to how the serializer was set up: text that is not valid in its format, a value with no exact plain form, data that does not fit the type it is read into. Catch it to tell whoever sent the data that it was refused; the subclasses say at which step.
Also a :class:ValueError, the error Python raises for a value of the right
type with the wrong content.
UnsupportedFormatError ¶
Bases: NotEncodableValueError
No encoder or decoder of the serializer handles the requested format.
A value nothing can encode, since nothing encodes that format at all, and typed separately because the fix differs: the data is fine, but the application asked for a format it never set the serializer up for, or misspelled one it did.
The format is quoted in the message, so one taken from a request cannot break the message across lines.
Attributes:
-
format(str) –The format that was asked for, such as
"json".
Record the format that was asked for.