Document the handling of error in do_execute

[BoPeng]

My customized kernel does something like the following to handle errors

    def _do_execute(self,
                    code,
                    silent,
                    store_history=True,
                    user_expressions=None,
                    allow_stdin=True):
        try:
            # do stuff
        except Exception as e:
            return {
                'status': 'error',
                'ename': e.__class__.__name__,
                'evalue': str(e),
                'traceback': [],
                'execution_count': self._execution_count,
            }

which works fine during interactive data analysis or through Run all cells. However, papermill does not recognizes the error and returns 0 when it converts notebooks with my kernel. It turns out that a message of type error should be sent through self.send_response in addition to returning execute_reply with status of error. Although I believe the caller of this do_execute function should automatically do this, this PR documents the proper way of handling errors in this function, namely

    def _do_execute(self,
                    code,
                    silent,
                    store_history=True,
                    user_expressions=None,
                    allow_stdin=True):
        try:
            # do stuff
        except Exception as e:
            msg = {
                'status': 'error',
                'ename': e.__class__.__name__,
                'evalue': str(e),
                'traceback': [],
                'execution_count': self._execution_count,
            }
            self.send_response(self.iopub_channel, 'error', msg)
            return msg

[jasongrout]

I agree that it would be convenient if the caller of this method sent the execute_results iopub message, as documented in https://jupyter-client.readthedocs.io/en/stable/messaging.html#id6

[BoPeng]

This is the relevant papermill dicussion nteract/papermill#337

[meeseeksmachine]

This pull request has been mentioned on Jupyter Community Forum. There might be relevant details there:

https://discourse.jupyter.org/t/jupyter-client-6-0-0/3414/1