[GT4Py] Enhancements to error reporting

# [GT4Py] Enhancements to error reporting (moved from cycle 17) - Shaped by: @egparedes - Appetite (FTEs, weeks): 2 devs, 2 weeks - Developers: ## Problem The creation and handling of user errors has been improved in the previous project ["Exception hierarchy & error handling"](https://hackmd.io/9_3Jha4MTGiGpHKAp3zb3g) (implemented [here](https://github.com/GridTools/gt4py/pull/1275)), where a new hierarchy of Exception classes was introduced together with a more user-friendly mechanism to print the errors. Although that project built the foundations to improve the feedback given to users, **GT4Py** still lacks a consistent style for reporting errors and creating exceptions, which means that every developer has to take the same desig decisions on his own when implementing new features that can create new errors. ## Appetite Limited appetite because it's not a huge task, but it's important to homogenize the code base ASAP and avoid large refactorings in the future. ## Solution This project should be done in two steps: 1. Design, document and implement a coherent and clear set of conventions for creating and raising new `Exception` classes and writing error messages 2. Implement the conventions in the actual codebase. ### 1. Design and documentation Document the guidelines for creating exceptions either using either an [ADR](https://github.com/GridTools/gt4py/blob/main/docs/development/ADRs/Index.md) or expanding the [Coding Guidelines](https://github.com/GridTools/gt4py/blob/main/CODING_GUIDELINES.md) document. #### Exceptions The previous project document already compiled a collection from different sources of [good practices in Python](https://hackmd.io/9_3Jha4MTGiGpHKAp3zb3g#References) and [good practices in general](https://hackmd.io/9_3Jha4MTGiGpHKAp3zb3g#Rationale) for creating and using exceptions. A rough starting point for writing the guidelines to create new exceptions summarizing those sources could be something like: - Design exception hierarchies based on the distinctions that code catching the exceptions is likely to need, rather than the locations where the exceptions are raised. - All GT4Py exceptions should (directly or indirectly) inherit from a single GT4Py base exceptions and should be defined in modules close to where they are intended to be used. - Exceptions classes should contain enough information to answer the question “What went wrong?” programmatically, rather than only stating that "“"A problem occurred" - Exceptions classes should contain a meaningful error message,ideally templatized in some form (e.g. in the class constructor). #### Error messages Error messages are texts meant to be read by users, which means they should be written according to the spelling, grammar and punctuation rules in English. Currently, many parts of the code informally use the following format for messages: - First word is capitalized - Sentences are ended with a dot `.` - backticks (`` ` ``) instead of quotes (`"` or `'`) Example: ``The provided data contains invalid part `foo`.`` Open questions: - Standard error messages from the Python standard library don't contain the final dot as mentioned in [issue#1292](https://github.com/GridTools/gt4py/issues/1292) - The use of backticks `` ` `` was probably caused by markdown/slack formatting rules, but this doesn't seem a valid reason to keep it instead of regular single quotes. ### 2. Implementation - Look for all the places in gt4py where custom exceptions are raised and adapt them to the new guidelines. This might also involve the creation of new `Exception` classes and/or new modules inside subpackages to collect the exception classes related to that subpackage. - (Optional) If there is time-left, wrap all codepaths where python or external library exceptions could be raised due to internal gt4py bugs with custom exception, so gt4py users will always get a GT4Py exception with meaningful error messages. In case of exceptions due to gt4py bugs, some kind of `InternalError` should be raised from the actual exception error. ## Rabbit holes - Adapting the codebase to the new conventions could involve larger refactorings than initially expected and be really time-consuming. Before starting refactoring any part of the code, try to make sure you understand and minimize the changes which will be needed. ## No-gos - Heavy refactoring of the code is completely out of the picture. All the changes should be related to make the codebase coherent with the error creation and handling conventions. ## Progress - [x] Answered Questions: - There is no reason whatsoever on record for why Python standard library error messages do not end in a dot. So there is no good reason to stick to that other than being consistent at the cost of readability. - Indeed, backticks are no help when reading error messages on the cmdline. Neither can they be said to be conventional in this context. Let's favor double quotes (despite possibly having to escape them in python strings). - [x] Guidelines merged - [x] Error messages within `gt4py.next` have been updated and authors of pending PRs notified wherever conflicts might arise or non-compliant error messages would have been introduced. - [ ] Multiple (~ 20) very similar instances were found of ad-hoc list formatting in error reporting code. A helper could reduce complexity in those bits of code locally and increase consistency in output. - [ ] Multiple instances (~ 50) of AssertionErrors being manually raised were found. In some cases they might be used to validate function parameters. This would be in violation of the Google style guide. Even in the other cases, it would probably be better to replace those usages with a more specific exception type.