I had the opportunity, at work (and a bit outside of work), to learn the GitHub API, as wrapped by Python’s github3 module. I found the documentation really hard to follow, maybe because I don’t have a lot of experience reading API docs, or because it wasn’t organized in the way I think about things, or maybe just because my work on this API was part of a larger, much more harrowing project, and I was already discouraged* … who knows?
I made a thing! Maybe it’s helpful!
Ultimately, I ended up documenting the parts of it I needed to understand in an IPython notebook; if you’d like to play with the GitHub API, then, please, feel free to download and run it, after filling in your own username, your chosen repository name, and your API token for GitHub (which you will want to keep secret, of course).
I’m not sure the format I used is going to be helpful to others, but I kept referring back to this notebook over and over as I worked, so, at the very least, I’ve found a format that’s helpful for me! Since I was trying to mock GitHub objects, I was very interested in return types. I hope it’s useful for others who want to understand github3…
I made a funnier thing! Maybe you’ll want play with it?
Now, because I had a funny idea (and I wanted to remind myself that I like programming), I also spent most of a Sunday building a tool to help make GitHub feel less like a game I have to win**. In short, it makes one commit per day on my GitHub account—actually, to the repository in which it is housed, because I was feeling puckish—so that I maintain a perfect streak. See? Perfection, since the day I wrote the script!
The code itself is pretty short; look at do_the_thing.py. You can tell I had fun writing it, though. :)
The trickier (read: way more time-consuming) part ended up being the “make it run daily” bit. I had to learn about launchd, which Mac seems to prefer to cron. That’s too bad, since I already understood cron, but launchd has some nice features, like running when the machine wakes up if it was sleeping at the appointed time.
Anyway, once I gave in and took the advice of the launchd tutorial linked above and installed LaunchPad, it went better for me.
I’ve included my plist file in the repository, so nobody else has to write their own; I also gave the directory to put it in and listed the one necessary change, in the README. It shouldn’t be too hard to get running if you’ve got a Mac on hand.
I’d like to deploy this on Heroku at some point, rather than having to keep my laptop on all the time; maybe if I find that doable I’ll write a follow-up post, or just edit this one. :)
*We have this big code base, which is built on Flask (which I don’t know) and MongoDB (which I don’t know) and which has a RESTful API (which I haven’t learned yet; that’s my current project, happily!), which requires some internal routing to build and resolve URLs (which I don’t really understand, though I can trace through it with PyCharm). My job was to use mock (which I didn’t know at the time and still have trouble keeping my head wrapped around) to write tests (which I have only minimal experience with) on some internal API routes and permissions stuff for the GitHub addon (which was written in a fairly complicated way, in part by necessity, and which I didn’t understand at all at the outset of this project). This was supposed to be a good learning project, and I don’t doubt the intentions of anyone involved with assigning it, but … it was a pretty terrible, demoralizing experience, made worse because I was instructed not to ask the more-senior devs any questions, and the time estimate I was given was not realistic. (I did finish, pretty much. I have to redo my pull request in the morning.)
** “GitHub displays a lot of useless stats about how many followers you have, and some completely psychologically manipulative stats about how often you commit and how many days it is since you had a day off” – Why GitHub is not your CV, by James Coglan