If you haven’t noticed, I like punchcard graphs.  I like them so much, I have a script that to generate them.  I’ve now released this script for everyone to use.

Punchcard.py is simple to use and I hope you find it useful.  It accepts a stream of unix timestamps and creates a punchcard graph. It can very useful if you’re trying to figure out days and times of activity.

How Do I Install punchcard.py?

The easiest way to install punchcard.py is with pip.  Just run

pip install punchcard.py

If you install it manually (by cloning the punchcard.py git repository and running python setup.py install), you’ll also need to install the dependency pygooglechart.

What options are available

The only option that is currently available is to change the filename. To do that, use the -f option like

punchcard.py -f tweets.png

How do I generate a stream of timestamps

For WordPress Posts, I Butchered the WordPress importer plugin. To use this, clone that repo and run

php punchcard.php export_file_name.xml | punchcard.py

For Twitter, I created a similar simple script. I have the script setup for retweets, original tweets and all tweets. I just change the echo line at the end depending on which I want to output. To use this script, I run

php twitter.php archive.csv | punchcard.py

What should I do if I find bugs

Please create a github issue with any bugs you might find. Please make sure to include steps to reproduce including a relevant data source file.


This script is largely just an abstraction of Bash History Punchcard by Matt Behrens. Without his work, this wouldn’t exist.

Final Notes

If you use punchcard.py to create any interesting graphs, tweet @aaronjorbin, I’d love to see that it’s being used.