2982.elegantly handle known errors

[oliver-sanders]

For Discussion

I've made a quick start at #2982, raising as a PR now to discuss approach before committing to it.

WIP

I've got the tests/validate tests to pass, these changes should give a flavour for what this would look like if fully implemented.

closes #2982

Highlights:

• Cylc / Parsec exceptions inherit from CylcError and ParsecError respectively.
• Jinja2 becomes an optional extra to Parsec (like EmPy).
• Add UserImputError for CLI input.
• Merge GraphNodeError in with GraphParseError
• CLI commands catch CylcError, ParsecError errors elegantly but allow anything else to materialise in traceback.
• Use (minimal) inheritance for exceptions:
  • Excessive nesting causes performance and maintenance issues.
  • Don't catch CylcError exceptions in order to re-raise as a more generic type e.g. GraphParseError being re-raised as a SuiteConfigError
• Simplify & standardise exceptions.
  • No more def __str__(self): return repr(self.msg).
• Move exceptions into their own module.
• Replace inconsistent ERROR prefix with the more informative error class name.
• Remove redundant information (stuff like this: ItemError: ERROR: error in item).

Example:

before: catch specific exception and re-raise as a generic exception

FileParseError:
Include-file not found: bar.rc via foo.rc from $PWD/suite.rc

after: remove un-necessary Include-file not found text, exception title should suffice

IncludeFileNotFoundError: bar.rc via foo.rc from $PWD/suite.rc

TODO:

• Isodatetime exceptions should inherit from ISODateTimeError.

Questions

@cylc/core Are we happy with this approach?

Should exceptions multiple-inherit for context (see lib/parsec/exceptions.py for example):

class ItemNotFoundError(ParsecError, KeyError):

[oliver-sanders]

One example of catching a specific exception then raising a generic one in its place.

[oliver-sanders]

Is this a sensible way to provide more context to the exception or a potential hazard?

[kinow]

I think so, knowing it's due/related to KeyError looks simple and useful.

[oliver-sanders]

Do we need super-specialised exceptions like this?

[hjoliver]

Presumably a good reason for a "super-specialised exception" is if the calling code needs to catch and respond specifically to that specific exception; otherwise it's pointless.

[hjoliver]

@cylc/core Are we happy with this approach?

Sounds pretty sensible to me, although I wouldn't say I have a deep understanding of exception handling best practice (if there is such a thing).

[matthewrmshin]

Happy with approach. Key points:

• So we are able to easily catch known errors and present them to users as intended.
• So we don't catch unexpected errors that are likely to be bugs in our system.
• So we don't need extra code for each exception class unless there is a special requirement.

[kinow]

I like the classes design too! In Java and PHP, normally you have one base exception class, and the children classes are designed per application feature/issue/section/etc. So +1 🎉

As for the decorator cli_function, +1 as well, but not too sure if it won't change later.

From #2972, some libraries that handle command line parsing/arguments also provide ways to intercept and display exceptions, which could be used with or replace the decorator (I think?)

• click: Exception Handling
• plac: their Interpreter has some exception handling, and also when you write your own runner
• clize: offers some API that can be used to display messages or tracebacks
• python-fire: seems to be the only one that does not get involved in error handling

Another possibility, is that in #2802 the current Cylc commands could be re-designed in some simple object structure. Depending on the outcome of that task, we could instead of having each command with a try-catch, or with a decorator, have an entry point that uses the new Python code. aws-cli has an entry point where exception is handled. But not sure if we will go in the same direction.

One benefit of having this approach, is that if we had the logic of cylc run in some class like CylcRun that was fully independent of the command line (no imports related to command line parsing, no exceptions related to that), it would be easier to re-use it from the Web, without having to worry about sending the right parameters to avoid the errors being accidentally suppressed (I think we may need the full traceback in the web and then log to some FileAppender, etc).

[oliver-sanders]

OK, based on this response I'll finish work on this PR, lots of tests to fix!

Note, the parsec tests were pretty easy to fix as they are unittests which only check the exception raised not the full text. Test the interface not the implementation is a good motto.

[hjoliver]

(@kinow - in your comment above, I guess you were suggesting possible ways to do even better in future, not changes to this PR?)

[kinow]

@hjoliver yup, but that would depend on the decision for #2972

[oliver-sanders]

• Deconflicted
• Tidied Jinja2 & EmPy exceptions

[oliver-sanders]

@kinow resolved codacy niggles, unified IllegalValueError, ListValueError and IllegalItemError in the process.

[oliver-sanders]

Deconflicted.

[matthewrmshin]

All looks good via 👀 with 👓 .

[hjoliver]

LGTM so far, but still going through the code. I like the CLI function decorator 😁

[oliver-sanders]

I like the CLI function decorator 😁

Good! This could pick up other functionality like colour settings/parsing.

[hjoliver]

Approve pending minor deconfliction.

Note also #3056 adds more SuiteConfigError.

[hjoliver]

@oliver-sanders you've rebased onto some recently-merged old-style use of SuiteConfigError (with redundant "ERROR" strings) that need to be made (aesthetically) consistent with your changes here.

$ git status                                                                                                                                                                 
HEAD detached at oliver/2982.elegantly-handle-known-errors

 $ grep -A 1 -B 1 ERROR lib/cylc/config.py                                                                                                                                     

                        raise SuiteConfigError(
                            f"ERROR, "
                            f"xtrigger function not callable: "

                        raise SuiteConfigError(
                            f"ERROR, "
                            f"xtrigger function not found: {xtrig.func_name}")

[kinow]

Re-approving!

[hjoliver]

🎉

[oliver-sanders]

🎉