I've been a teacher at UC Berkeley for 3 years. I've written textbooks, designed entire curricula, trained hundreds of budding teachers, and taught thousands of students.

Ironically, in all my experience, the hardest things to teach are also the most fundamental: variable assignment, if and while statements, namespaces, higher-order functions ... and of course, recursion.

Programming is highly unintuitive for beginners. That's not just an educational concern, but an ethical one.

When newbies go head-to-head in a class with seasoned hackers, it's intimidating. Worse, it's heartbreaking, because this is the #1 reason that CS hopefuls at the university level -- many of them women and underrepresented minorities -- switch into other fields.


Introducing pyagram: breaking down the basics for programming newbies, in an intuitive visual way, to help them break into CS.

A pyagram shows you the state of a Python program as it evolves over time -- including not only the structure of frame dependencies and variable bindings, but also the structure of nested and partially-applied function calls, and the nuanced interplay of the objects in memory.

But ... are pyagrams effective?

Well, I've actually been teaching my students for years how to draw pyagrams. (I simply procrastinated making the actual software, until now.) Those students -- the ones who could use pyagrams to reason about code intuitively and visually -- achieved statistically significantly higher code comprehension scores than their peers in UC Berkeley's 2000-student CS 61A. Moreover, bolstered by their good scores on the first midterm, these students tend to stay enrolled in the class even when many of their peers drop it or switch to a Pass / No-Pass grading option.

So in a word, the data seems promising. Beyond improving students' understanding of fundamental CS principles, pyagrams may also decrease grades-based attrition in beginner-level CS classes and make the field more accessible to a broader demographic.


There were a lot ... but that's why it's fun!

The main hurdle was that Python's built-in debugging framework doesn't make available the information that gets incorporated into a pyagram. How, then, do I get said information?

  1. First, I convert the student's code into an abstract syntax tree (AST). This is a programatically malleable representation of their high-level directives to the Python interpreter.
  2. Then, I mutate the AST -- adding my own directives to the student's code, and injecting additional annotations wherever useful.
  3. I compile the mutated AST, and execute each directive line by line. As I do this, I flag important places in their code, based on the annotations that I injected earlier.
  4. Once I have finished executing the student's code, and I have all the information that only becomes available upon its termination, I propagate useful data back to these flagged locations.
  5. Finally, I undo the mutations that I introduced to the student's code in Step 2.

Then it's just a matter of serializing the pyagram to a JSON object, sending it to the front-end, and writing an uncomfortable amount of HTML, CSS, and JavaScript. The result? A fast, flexible Python visualization engine.

And even if Python radically changes its syntax or adds new features in a future update, my code base will be able to handle it with no modification.

Future work

Once pyagram is up and running online I hope to roll it out to UC Berkeley's CS 61A -- which is the largest introductory CS class in the nation, if not the world. I'm aiming for an alpha test in the Summer, a beta test in the Autumn, and full integration next Spring.

This is a class that I've spent years teaching and contributing to, so it's really important to me on a personal level and I'm super excited to see how it goes!


Pyagram is protected by a CC BY-NC 4.0 license.

Built With

Share this project: