Feature #3134

gmxapi Python exception names may need improvement

Added by Eric Irrgang about 1 month ago.

Feedback wanted
Target version:


In Python, we may prefer to avoid name collisions with built-in exceptions. Even though we use a separate namespace (gmxapi.exceptions), using the fully qualified exception name can be cumbersome, and seeing KeyError or TypeError can be confusing, even with name qualification to reduce ambiguity.

In particular, TypeError and ValueError tend to have somewhat non-traditional meanings in gmxapi, and renaming could help to keep semantics clear. Currently, gmxapi.excpetions.TypeError means something like "gmxapi data compatibility could not be resolved" while the built-in Python exception means something more like "an expression does not have the expected interface or protocol". Currently, gmxapi.exceptions.ValueError means something like "I don't know what to do with that object" in a way that may more closely resemble the built-in TypeError case that ValueError case.

Note that we try to make sure that exceptions thrown in gmxapi are derived from gmxapi.exceptions.Error to allow client code to more easily filter the sources of exceptions in their own code. Ideally, the exception names should provide a good hint as to what went wrong, so an argument can be made that reusing common exception names improves readability.

Another alternative is to prefix exception names with "Gmx" or something, either in the module itself or as an aliasing convention when importing specific exceptions.

Personally, I think I prefer trying to make the names more unique and less ambiguous, and not discourage importing gmxapi.exceptions class names directly into the client namespace (e.g. from gmxapi.exceptions import DataShapeError)

There are some discussions about exception naming philosophy in Python that I can't find right now, but which should be considered before taking action on this issue.

Also available in: Atom PDF