130

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.
  • Stalk Generate a detailed profile of a user's life Help 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.

  • "there is documentation too, if that's your style" - where can I find the docs? Is it just github.com/lucjon/Py-StackExchange/blob/master/README.md ? – LarsH May 16 '11 at 20:04
  • @LarsH: That, and the wiki (also on Github). Will clarify. – Lucas Jones May 18 '11 at 15:06
  • @Lucas: What would be really useful to me is a list of the methods exposed by py-SE, and a list of parameters for each, like the list at api.stackoverflow.com/1.1/usage for the SEAPI. (Bonus: a mapping between the SEAPI and py-SE's methods.) – LarsH May 18 '11 at 16:49
  • @LarsH: That's a good idea; it'll also encourage me to keep as close to 100% coverage as is humanly possible! – Lucas Jones May 18 '11 at 17:57
  • 1
    @Lucas great work, any plan to support also the V2.0 Api? – systempuntoout Apr 12 '12 at 10:27
  • @systempuntoot: Thanks for the comment; it arrived in my inbox and reminded me I've not finished updating it yet! There is a branch on Github I started a while ago with some basic things working... I'll try and get that finished as soon as I can. – Lucas Jones Apr 12 '12 at 11:20
  • May I just say that this was, by far, the best description of a library I have ever read! – Alex Chamberlain Aug 10 '12 at 12:44
  • @LucasJones I see there hasn't been any activity for a year or so. How complete is your 2.0 coverage, and do you have any plans for updating to 2.1? I just discovered the API, and love Python, so this library is an obvious choice, but I don't want to screw anything up with the wrong API calls and whatnot. Thanks! – MattDMo Oct 21 '13 at 16:16
  • @MattDMo: Regrettably, the 2.0 branch is not entirely stable, mainly due to differences in the way filters work, and the coverage is certainly not complete. As you have deduced, there has not been much meaningful effort dedicated to improving it for a significant period of time; I currently have no explicit plans to update it for v2.1. The existing v1.x code remains entirely functional if you don't require any of the new API calls. – Lucas Jones Oct 21 '13 at 20:01
  • @LucasJones I just got a notice that API v1.x will be shut down 3 months after the v2.2 release, but no earlier than April 1, 2014. Do you have any plans to support v2.x before the v1.x shutdown? – Eric Leichtenschlag Jan 31 '14 at 18:13
  • @Eric Leichtenschlag: While I'm sure I'm overlooking something obvious, I can't find a source for your exact date for a v1.x shutdown. The v2.x branch of the repository has improved somewhat since my last comment here, passing its (small) set of unit tests. The Python API remains almost identical. Certainly if there were such a date it would be a useful motivator; while I can't make any guarantees, I imagine the finishing touches could be put on before then. – Lucas Jones Feb 3 '14 at 22:56
  • I couldn't find it online anywhere either - I happened to get an advanced notification email about it. I suspect they'll announce it as part of their their v2.2 release announcement. Anyways, I'll stay tuned for an exact date and what the future plans of this library are. Thanks! – Eric Leichtenschlag Feb 3 '14 at 23:18
  • So the shutdown of v1.x is official now. I see you've made some changes to support v2.0. Has it moved completely to 2.0 yet? – Eric Leichtenschlag Apr 3 '14 at 18:36
  • 1
    @apnorton: I've added support for it just now; you'll need to use the latest version in the repository (github.com/lucjon/Py-StackExchange). If you call Site#question or Site#answer with the filter= optional parameter pointing to a filter set to return the body_markdown field, then the returned object will have a body_markdown attribute. – Lucas Jones Apr 25 '15 at 17:52
  • 1
    @Tim: It is indeed possible to get the Markdown; you can request the body_markdown attributes on questions and answers using an appropriate filter. See my responses to apnorton on Apr 25 for more detail. – Lucas Jones May 26 '15 at 16:07

31 Answers 31

0

I have been experiencing some throttle issues when trying to fetch timeline data for some users. I get a: stackexchange.core.StackExchangeError: 502 [throttle_violation]: Violation of backoff parameter exception after the api handles some requests...

The weird thing is I'm using:

so.impose_throttling = True
so.throttle_stop = False

So I really don't understand why py-stackexchange does not handle the overloading requests and make my application wait until it can make more requests... What am I doing wrong?

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .