Realize: A Python app for understanding a program’s code structure.
By: Justin Walker
Tags: Python Programming, First Post, Programming, Python, Open Source

A few months ago, as part of my programming education, I was tasked with two final projects. Participating in the open source community, and designing my own OSS project. A very daunting task considering I was only moderately experienced with git, and had never collaborated on a project with more than two people before. I spent a couple days researching how to contribute, how to find projects, how to submit a Pull Request, and anything else I could. It was time, I had to jump in feet first.

The Jungle

I knew I had to start somewhere, so I figured working on other peoples’ projects first would make it more clear how to start one of my own. Thus began several more days of researching dozens of projects to find one that felt approachable. I began searching for projects across multiple websites, would find one that seemed to be in my wheelhouse, read all the instructions, and still feel completely lost and out of my depth when I tried to understand the code. I could look at a file, read some code, but only ever half understand it. Most of its functionality came from classes and methods imported from elsewhere, but what they did was unclear, further obfuscating the process. I’d follow the import trail to the next file only to find that it contained resources imported from several files, and I wouldn’t able to tell which class came from which file. This process overwhelmed me. I kept trying to understand just one part, so I could expand outward, but the more I looked the more confused I got. I decided to make my own program to help clear up the confusion, and hopefully help others who are navigating similar code jungles.

The Machete

Enter Realize. A completely Python program designed to scan through a project and all its non standard lib imports to find class names, locations, and methods. The goal was to create a resource to assist you in reading a program you were completely unfamiliar with. As you read through lines and find a method or class you aren’t familiar with, you can enter its name in the search bar and turn up all relevant information, including where to find it so you can look directly at how it functions. As each different language would have different rules for interpretation, it’s only designed for analyzing Python code. In the future, if the project is useful enough, it would be worth refactoring to allow for other language modules like C++ or Java.

Teaching a program how to read Python

Python is designed around indented code blocks instead of {} code. The inside of a function is indented one level in, and is finished when the indent back to its original level.

class Classy:

def method_man():

print('Woot!')

Classy.method_man()

This required a function that could look at each line of code and find out its indent level relative the line before it.

Using that as the basis for a function that looks at the first line of a classes definition, it can be used to iterate through all the lines of code until it finds the end of the class definition, and stores all of it into a class object. Now all info on that class can be saved and accessed by the GUI.

Realize iterates through every line in a file storing the lines that begin with import statements or class definitions. It then creates a Class_obj for each class and does the same scans to any imported files. The Class_obj when formed scans all the lines within the class to find out all of its methods

The Current Product

Realize is currently functional, but not fully developed. A program which tries to interpret a programming language can scale up much bigger. Additional languages could be added in as modules, more rules could be added to interpret doc strings, and it needs to be more adept at dealing with fringe styling cases. Being new to open source, I’m not as intimately familiar with the multitude of formats and styles used by bigger, more well produced projects.

The Takeaway

I eventually was able to find an open source project I could contribute to. It was a smaller project, a bot for IRC chat, made by other people who wanted practice in open source and in Python. Using Realize I was able to read through the project’s code much faster than I would have on my own. Pretty soon I became a contributor and began working on core functionality. Realize is something I will continue to work on and expand so it can help more and more people get past one of the most daunting aspects of joining an OSS project. I hope you will use, contribute or provide any feedback to help make Realize the best it can be.