Clarify `session` in `history_request`

[gibiansky]

What is a session in a history_reply? From here.

Is this related to the session in the message header? (To my best understanding the answer is "no".)

If I had to guess, a session corresponds to a notebook cell, and there are many lines in one session; or perhaps sessions are only applicable to console frontends in which case a session is one invocation of the console (but in that case, what happens if there are two open console sessions at once...? are they ordered by whichever one starts first, or finishes first?)

It'd be great to add some explanation about what a session is in the context of the history request/reply –– it's definitely not obvious although I have some guesses.

[gibiansky]

Also, it's somewhat confusing as to the output parameter in history_request.

Specifically, the output is clearly just text, not a display_data, whereas all kernel outputs are not display_data (only via iopub display_data and execute_result). So there's no longer a real notion of a "text" output of a cell or line.

So, does that mean that the output for a cell (in the context of history) should be only the plain text representation (text/plain) of the display_data and execute_result for that execution? And, is that only the execute_result, or also all associated display_data? (For example, for print_and_return_input("Hello"), would output be just "Hello" or would it be something like Hello\n"Hello"?)

[takluyver]

You're right that this session is a separate concept from the session in the message header. A history session generally corresponds to the lifetime of a kernel process, though in IPython I think it's possible to get a new session without restarting the kernel. The idea is that a session contains the sequence of commands that operated on the same namespace. The references to 'lines' was written when we were only thinking about console interfaces; one notebook cell is one 'line' for this purpose.

'Output' is only the plain text representation of the execute_result.

The history messaging was designed by exposing the entire IPython API for history access, and as far as I know, nothing uses most of the possibilities. I believe the only history_request that our own frontends make is a 'tail' request with output=False, for the console interfaces to fill their local history buffer. We may well simplify it in the next major revision of the message protocol.

[takluyver]

Also, while IPython implements the output part, it doesn't by default write output to its history database to record it after the current kernel dies. I don't know of any other kernel that implements the output part (maybe Julia does?), so it's probably of almost no use.

[gibiansky]

Sounds good. It'd be great if some of that eventually made it into the docs.

Thanks for all the clarifications -- I'm working on rewriting the lower level of the IHaskell libraries to support arbitrary kernels with a type-safe version of the entire messaging protocol, so since I'm trying to get all the details totally clear and conformant to the spec and type-safe, these little things become important.

Thanks!