Document oinspect format of object info

[techtonik]

oinspect has a chance to become a de-facto standard for exporing information about an object inside of Python process - https://github.com/spyder-ide/docrepr

It will help to build up the tools that use it if oinspect format is sufficiently documented to avoid surprises and future breakage. Right now it is not clear what is the format of data that oinspect works with https://ipython.readthedocs.org/en/stable/api/generated/IPython.core.oinspect.html

[minrk]

oinspect hasn't been formalized, so it is considered free to change across versions (and has done), since its only application so far is computing representations of inspection, rather than preserving the inspection info itself. Coming up with some more formalism, and cleaning up the API would be a good project, though.

[techtonik]

Are there any good practices for backward compatible and extensible data formats in IPython?

I'd like to have a format that will reflect the current structure of Python state at a given moment, but the one that could be inspected by future tools as well. The purpose if to build a player like https://github.com/pgbovine/OnlinePythonTutor/ which will be able to catch state of additional system components using human readable format compatible across different tools.

[ccordoba12]

@minrk, what about creating an external library based on oinspect that IPython would depend on?

[minrk]

I think that's a reasonable project, if there are sufficient uses outside IPython.

[techtonik]

As long as it is inside IPython, it is accessible only to IPython hackers, so it is a catch22 problem. But I personally think that any debugger would use that, not only Spyder. It would be also nice to be able to extract some of oinfo structure from bdb frames in JSON so that it could be immediately usable for https://github.com/pgbovine/OnlinePythonTutor/