Skip to content
Browse files

Fixed egg constants stuff (hopefully) and NEW README!

  • Loading branch information...
1 parent 031b20e commit 1c232850b8ad48e831354ea6f7536e28e6f956ba @lucjon committed Feb 23, 2011
Showing with 81 additions and 1 deletion.
  1. +78 −0 README.md
  2. +1 −1 setup.py
  3. +2 −0 stackcore.py
View
78 README.md
@@ -0,0 +1,78 @@
+Py-StackExchange is a simple Python binding to the API of the StackExchange network of sites.
+
+**NOTE**: Py-StackExchange is not an official product of, and is not affiliated in any way, with Stack Overflow Internet Services, Inc.
+
+# Getting Started
+You can get Py-StackExchange in two ways:
+
+ 1. Clone the Git repository from Github.
+ If feasible, this is the recommended approach - you'll always get the latest code with the newest features.
+
+ git clone git://github.com/lucjon/Py-StackExchange.git
+
+ You'll need to set up paths, etc. on your own though.
+
+ 2. Install from the Python Package Index (PyPI)
+ It's easier to install the library with the easy_install command, but be warned: while major bug fixes will be deployed as soon as possible to PyPI, you might need to wait a while for new features.
+
+ easy_install Py-StackExchange
+
+# Using the Library
+
+Fire up your Python interpreter and import the stackexchange module. Yay, you're done!
+
+ import stackexchange
+
+The primary class in the bindings is the Site class; it is used for querying information from specific sites in the network.
+
+ so = stackexchange.Site(stackexchange.StackOverflow)
+
+A number of site URLs come predefined; the list is rebuilt every so often. A new site's URL may not be defined, in this case, simply use a string in the form `'api.joelfanclub.stackexchange.com'`. Don't put in `http://` or anything like that.
+
+Once you have your site object, you can start to get some data dumped:
+
+ my_favourite_guy = so.user(41981)
+ print my_favourite_guy.reputation.format()
+ print len(my_favourite_guy.answers), 'answers'
+
+## API Keys
+If you're planning to use the API in an application or web service, especially one which will be making a large number of requests, you'll want to sign up for an API key on [StackApps](http://stackapps.com).
+
+The API is rate-limited. The default rate limit, if no key is provided, is 300 requests per day. With an API key, however, this is bumped up to 10,000! You can also then use StackApps to publicise your app.
+
+To use an API key with the library. simply pass it in like so:
+
+ so = stackexchange.Site(stackexchange.StackOverflow, 'my_api_key')
+
+Be aware, though, that even with an API key, requests are limited to thirty per five seconds. By default, the library will return an error before even making an HTTP request if you'll go over this limit. Alternatively, you can configure it such that it will wait until it can make another request without returning an error. To enable this behaviour. set the `impose_throttling` property:
+
+ so.impose_throttling = True
+ so.throttle_stop = False
+
+## Lazy Lists
+Py-StackExchange tries to limit the number of HTTP requests it makes, to help you squeeze the most out of your allotment. To this end, accessing any property which would require another call to fulfil requires that this be made explicit.
+
+ me = so.user(41981)
+ qs = me.questions
+
+This will not return all the required data. You should instead use:
+
+ qs = me.questions.fetch()
+
+With the fetch call, the list contains the appropriate data. Note that after this, `me.questions` will contain the data; you only need to call `fetch()` once.
+
+### Navigating Lists
+The API uses a page-based system for navigating large datasets. This means that a set number (usually 30 or 60) of elements are fetched initially, with more available on-demand:
+
+ print qs.pagesize
+ # processing
+ # Get more
+ qs = qs.extend_next()
+ # We have more questions
+
+The `extend_next()` function returns a list with the extra data appended, `fetch_next()` returns just the new data.
+
+# Next Steps
+Read, and run, the example code. The programs are simple and cover most of the basic usage of the API. Many of the examples also have wiki pages on the Github site.
+
+If you encounter any problems at all, feel free to leave an answer on [StackApps](http://stackapps.com/question/198), or to e-mail me at `lucas @ lucasjones . co.uk`. Yay, vanity domains.
View
2 setup.py
@@ -2,7 +2,7 @@
setup(
name = 'py-stackexchange',
- py_modules = ['stackexchange', 'stackcore', 'stackauth', 'stackweb'],
+ py_modules = ['stackexchange', 'stackcore', 'stackauth', 'stackweb', 'stacksites'],
version = '1.1-1',
description = 'A Python binding to the StackExchange (Stack Overflow, Server Fault, etc.) website APIs.',
author = 'Lucas Jones',
View
2 stackcore.py
@@ -125,6 +125,8 @@ def extend_next(self):
def fetch(self):
# Do nothing, but allow multiple fetch calls
return self
+
+ done = property(lambda s: len(s) == s.total)
class NeedsAwokenError(Exception):
"""An error raised when an attempt is made to access a property of a lazy collection that requires the data to have been fetched,

0 comments on commit 1c23285

Please sign in to comment.
Something went wrong with that request. Please try again.