(Proposal) Error explanations

[ZeroIntensity]

Content:

Marking this as "Good First Issue" to allow people new to the project to weigh in on this. This is a discussion, not a decided feature yet! For those coming from outside of view.py, this could be a chance to learn about feature proposals for any project, not just view.py.

Rationale

Errors can be pretty ambiguous, especially in libraries. view.py does its best to provide descriptive errors, but it just might not make any sense to someone totally new to the project, and since view.py's codebase is so large already, there are a lot of different errors you can get. This library is still relatively new, so googling errors doesn't really work either (which might cause some to be driven away from view.py)

For example, imagine you see InvalidTemplateError: unknown key "foo" in <view> tag. In context, that might make perfect sense, but to a user, that could be pretty cryptic. Perhaps view.py could integrate an error and explanation system (similar to what rustc --explain does). This would take quite a bit of work, so I'm making this discussion first to see if that would make things easier on users.

Proposal

All classes derived from ViewError (which is every exception in view.py) will take a required code parameter. For example, VE1000. Then, similar to the hint system (see #120), an explanation of what to do could follow the error message (or alternatively, give a command that would explain it). This could make debugging much nicer to especially new users. Following the example above, this would look something like:

$ python myapp.py
... output
InvalidTemplateError: [error code VE1000] unknown key "foo" in <view> tag
 * Use `view explain VE1000` for more information

Followed by:

$ view explain VE1000
VE1000 (InvalidTemplateError) - Invalid <view> attribute
A VE1000 occurs when an invalid attribute name is used on a <view> tag (through view.py's template engine).
For example, trying to use the attribute name `foo` (`<view foo=...>`) would cause a VE1000:

... example code

The downside of this is that each explanation would have to be more or less hardcoded into view.py, which could drastically increase the size of the package (we're talking several extra mB, and thousands of lines of just error explanations).

Talking Points

• For those coming from outside of view.py, how might this feature make view.py look from a distance? Is it a nice thing to have, or is the large bundle size too much of a deal breaker?
• For those that have used view.py before, how might this feature affect your experience with it?
• For those looking to contribute to view.py, would writing an error code and explanation be too much extra work?