Feature #3034

Python gmxapi exception hierarchy

Added by Eric Irrgang 11 days ago. Updated 11 days ago.

Target version:


libgmxapi can throw exceptions derived from gmxapi::Exception, defined in the gmxapi/exceptions.h installed header. These exceptions should have bindings in the gmxapi Python package (in the _gmxapi C++ extension module) so that they are easily catchable from Python.

Exceptions defined in the _gmxapi module should derive from gmxapi::Exception.

Users of the Python package should be able to use gmxapi.exceptions.Error as a catch-all base exception.

Developer documentation should describe how exceptions propagate and how they are catchable in both directions between Python and C++, with explanations of caveats for exceptions originating in different binaries or Python packages.

Also reference prior discussion at

Related issues

Related to GROMACS - Task #701: Add symbol visibility macrosNew
Related to GROMACS - Task #988: Definition of "public API"New
Related to GROMACS - Task #2045: API design and language bindingsNew


#1 Updated by Eric Irrgang 11 days ago

  • Related to Task #701: Add symbol visibility macros added

#2 Updated by Eric Irrgang 11 days ago

  • Related to Task #988: Definition of "public API" added

#3 Updated by Eric Irrgang 11 days ago

  • Related to Task #2045: API design and language bindings added

#4 Updated by Eric Irrgang 11 days ago

  • Description updated (diff)

#5 Updated by Eric Irrgang 11 days ago

  • Subject changed from Python bindings for gmxapi exceptions to Python gmxapi exception hierarchy
  • Description updated (diff)

We may not want an actual inheritance relationship between the base exception in gmxapi._gmxapi and the base exception in gmxapi.exceptions because that would mean either we have a potentially troublesome circular dependency (if gmxapi._gmxapi depends on gmxapi.exceptions) or we can't raise gmxapi.exceptions.Error until gmxapi._gmxapi is imported successfully. Unfortunately, the exception matching in try: ... except expressions doesn't seem to use the Python virtual inheritance hooks.

We could try to catch exceptions from gmxapi._gmxapi.Exception and wrap them in gmxapi.exception.X exceptions wherever possible in the Python package, but that would mean that all gmxapi._gmxapi objects would need to be wrapped in pure Python objects, and I don't think we want to do that.

We can also try minimizing the exceptions that can escape from gmxapi._gmxapi and instead develop the data model to embed the error reporting in return values, but we need to be cautious to be sure that errors can't go unnoticed and that failures occur as early as possible.

Also available in: Atom PDF