UPDATE: 2.x support is now mainline! Please read the wiki page for important information about the update.
A warm welcome to you, traveller. You have arrived at the home of Py-StackExchange, the library definitively proven† to be the best library for using the SE API from Python. If you are still interested (and by golly, you should be) after glancing at the masterpiece below, please check the wiki on Github.
† Ahem.
About
So, what is Py-StackExchange? Well, I'm glad you asked.
It is a Python library for querying the StackExchange API from your Python applications. Integration, ahoy!
So why should you use it? After all, the SE API is sooo simple that you might think it'd be quicker to just write your own, and that it'd be faster and you wouldn't have to look at all that documentation and do all that thinking... well:
Let's start with the API coverage - what can the API do? And, more importantly, what can the library do?
- Access any StackExchange site, with just its URL! Even those that aren't online yet!
- If you just can't decide which one to use, you can use StackAuth to look up the full list of sites.
- Once you're online, you can view everything about users, questions, answers, badges, comments and tags.
- You can even go back in time by playing with post revisions.
StalkGenerate a detailed profile of a user's lifeHelp users by looking up every StackExchange account they have. Every single one.- And, on any of those sites, peruse a detailed history of everything they've ever done - every edit, every comment, every time they were awarded a badge... Watch StackOverflow become the new Facebook overnight with the timeline feature.
- See how well an SE site is doing; obsessively check its site statistics.
- Search the questions of StackExchange sites.
So, why not write your own classes to consume said pure, concentrated brilliance?
- Let someone else deal with all that laborious HTTP request business... you know you want to...
- All the little idiosyncratic potholes on your road to API happiness have been filled in for you. We have little elves which jump into your code and parse your JSON and your dates and your lists until every response is itself a little baby python.
- URLs change 99.9% more often than the interface of this module. Fact.
- It's faster than Michael Palin on a broken bicycle. It also knows about request throttling, so when it gets too fast for its own good, it applies the brakes just enough to restore order.
- It loads lazily information that would take another request to fetch, meaning you never use more of your limit than you need to.
- It caches requests automatically, so you need to care slightly less about writing efficient code! (new in 1.1)
Now, onto the religious advantages:
- Documentation? Bah, we have naming conventions. (This feature was inspired by Rails.)
Pssst - don't tell anyone, but there is documentation too, if that's your style. (README/Wiki) - Naming conventions? Who needs them? We have an interactive program that writes your code for you while you look around the StackExchange site of your choice. (This feature was inspired by Jon Skeet.)
- Almost-sentient, artificially intelligent programming programs? Ugh, how 20th century. There are metric heaps of example code available in the source repo, a small excerpt of which is presented below for your viewing pleasure.
Please note: This is not an official product of Stack Overflow Internet Services, Inc.
Code Snippet
The wiki has details of all the example code in the code repository. In fact, here's a small taster from the Narcissism demo.
#!/usr/bin/env python
# a hack so you can run it 'python demo/stats.py'
import sys
from stackauth import StackAuth
from stackexchange import Site, StackOverflow
user_id = 41981 if len(sys.argv) < 2 else int(sys.argv[1])
print 'StackOverflow user %d\'s accounts:' % user_id
stack_auth = StackAuth()
so = Site(StackOverflow)
accounts = stack_auth.associated(so, user_id)
reputation = {}
for account in accounts:
print ' %s: %s / %d reputation' % (account.display_name, account.on_site.name, account.reputation)
reputation[account.reputation] = account.on_site.name
print 'Most reputation on: %s' % reputation[max(reputation)]
Or how about a scrolling list of questions?
import stackexchange
so = stackexchange.StackOverflow()
for q in so.questions(pagesize=50):
print q.title
About
This is a Python library/wrapper around the StackExchange and StackAuth APIs. It provides a clean, object-oriented API for accessing the various sites.
License
The script is licensed under the Simplified BSD license. You can find the full text of the license here, but the gist of it is that:
- You need to give attribution when you distribute (compiled or in source form) the library - not your application unless you include the library files `in the box'.
- The standard "NO WARRANTY" (in caps!) is provided.
Other than that you can more or less do what you like!
Download
In the bad old days (i.e. about 2 hours before I wrote this), you had to manually install Py-StackExchange after cloning the Git repository.
You can still do this: http://github.com/lucjon/Py-StackExchange. You can also download a ZIP or TGZ file from there.
However, there is a new and improved way to get Py-StackExchange: you can install it straight from the PyPI! Just type:
~$ easy_install py-stackexchange
Also, distutils
gives me fantastical benefits on the side, such as a completely original Windows installer with an all-new design. You can also find a stable source distribution on the downloads page @ Github.
Platform
The library is written in standard Python 2.6, with, as far as I am aware, no specific platform dependency. As long as your Python install has the full standard library available, it should work fine.
Python 2.6 is required for the json
module. (EDIT: @ADB in the comments has noted that the SimpleJson library can be used instead. This means it works on Python 2.5 and also on the Google App Engine.)
Python 3.x is also supported.
Contact
The library is being written by Lucas Jones (lucasjones.co.uk / SO). If you want to contact me, send me some mail at lucas @ lucasjones.co.uk
.
Site#question
orSite#answer
with thefilter=
optional parameter pointing to a filter set to return thebody_markdown
field, then the returned object will have abody_markdown
attribute.body_markdown
attributes on questions and answers using an appropriate filter. See my responses to apnorton on Apr 25 for more detail.