Macros and APIs for Python code

[Byvire]

We need simple macros that the user can use to tell us what to draw and how. It should be straightforward to hide all the visualization code from the reader of the textbook. There are really two tasks here: processing the python code itself, and writing APIs to help us print JSON descriptions of people's data structures. If you can lay the foundations for both those things, that'd be great. Maybe just make the API for linked lists this time.

Something like this seems good to me, but you can reconsider it: (This is copied from an email I sent to Eyal earlier.)

import foo
from bar import buzz
#algviz header

#algviz begin hidden
print("Output from hidden code!")
class APIForThoseUConnKids(algviz.GraphAPI):
    """user implements stuff for us here"""
    ...
#algviz end hidden

class MyGraph(foo.MyConvenientOtherGraph):
    pass

G = MyGraph(*foo.hand_wave_args, **foo.hand_wave_kwargs)
#algviz show graph G APIForThoseUConnKids
# We can probably make something like the following work for languages
# like Python, but it doesn't matter too much:
#algviz autoshow G

# Misaligned algviz macros in Python code should result in SyntaxErrors
# after we do the replacement:
 #algviz show graph G APIForThoseUConnKids

[Byvire]

Actually, this is harder than I thought, since the graph/list/etc might store data of arbitrary types, and we probably want to include that data in the JSON. A few requests. Some of them should probably be separate Issues.

• algviz has the concept of a snapshot, i.e. a recording of a bunch of data structures at the same (or effectively the same) moment in time.
• algviz should keep track of UIDs of objects printed so far in the current snapshot. This will make it easy to avoid traversing the same data structure twice.
• As part of the API that the user provides to help us print their Thing, they may tell us how they want the data attribute to be printed. For example, they can tell us to display it as list of trees, even though they know perfectly well it's a list of lists of lists. (By default, we can choose a procedure to print x by looking up type(x) in a dictionary.)

[Byvire]

I made some progress on this in the python-apis branch. It's missing some higher-level features that would make it more usable without macros. Also I need to document/test it better than I have yet, and so of course there's a chance it doesn't work at all. (I didn't write any parsing/macro code. I didn't want to step on your toes.)