Error Reporting

Not every fit goes smoothly and especially when you’re building your model you will get misfits. If the system just told you blindly “there’s an error” it would not be very convenient, that’s why typefit was built around the idea of providing great error feedback.

Note

This feature is still experimental because it needs to be in the wild for a while before making any definitive decisions.

Default behavior

By default, errors will be reported using the logging module and will be output with True Colors ANSI codes.

This is the output of the default fitter:

Fitter(
    error_reporter=LogErrorReporter(
        formatter=PrettyJson5Formatter(colors='terminal16m')
    )
)

This means that if you call typefit() directly and a parsing error occurs, right before the ValueError exception is raised, the logger will receive a message explaining the error.

Rationale

The main goal of error reporting is that humans are able to understand the error.

Errors might occur in simple structures but they are more likely to happen in complicated recursive structures.

Suppose that you have a list of a thousand items and hidden in that list there is just one or two items that don’t match. Or the opposite, all items have an error. Or even worse, you have a recursive structure with unions which generate an exponentially high number of matching errors.

How do you display these errors without flooding the user’s console?

The main idea behind the error reporting in typefit is that errors should be displayed on top of the data, this way you can’t have more error than fields in your data.

On top of that, errors are abbreviated as much as possible. Objects that don’t contain errors are not expanded. Lists that have a thousand times the same error will only display the error once. Strings that are too long will get truncated.

Those constraints lead to develop the PrettyJson5Formatter formatter, which will generate colored and annotated output, easy to grasp when looking for an error.

Note

For now, everything is very oriented towards a developer that sees some output in a terminal to help them debug things. This explains the very opinionated nature of default configuration. Feel free to open tickets to make default more sane for other configurations!

Custom behavior

Maybe that you are not happy with the default behavior and you wish to change it with custom reporting/formatting. This is possible through the fact that you can configure what you want when creating the Fitter instance.

Reporter

By creating an implementation of ErrorReporter that you then pass to the constructor of Fitter, you can then get notified of every error and report it.

The default reporter reports to the logging however feel free to report to whichever tool you want, be it a live front-end or an IDE plugin.

If your reporter reports text, you might be interested in using the standard formatter interface, as explained right below.

Formatter

While you don’t have to use the formatter when doing a reporter, if the reporter is going to report text then you can use this interface.

That formatter will take in the node that has an error and will output a legible text that can be understood by the user.

Formatters must implement the ErrorFormatter interface.

The default formatter, PrettyJson5Formatter, is very opinionated and will generate shortened JSON5 outputs that are easy to read and potentially colored using Pygments (AINSI codes, HTML, IRC, …).

Reference

For more information about the implementations, you can have a look at the reference documentation.

Reporting

The reporting module has all the reporting logic.

Nodes

The full output of a parsing, including error messages, is held by the Node models. If you are making a custom formatter or reporter, you might have to work with this API.