### About

A lightweight Python wrapper for [the Stack Exchange API](http://api.stackexchange.com/) v2.1.
Built with [Requests](http://docs.python-requests.org/).

Why yet another SE API Python wrapper? (I'm aware of https://stackapps.com/questions/3417/stack-py-a-python-module-for-accessing-the-stack-exchange-2-1-api and https://stackapps.com/questions/198/py-stackexchange-an-api-wrapper-for-python.)

For me there were two key things:

 * make commands as straightforward as possible,
 * make easy to harvest a lot of pages.

First, because I wanted to use commands directly from [the documentation](http://api.stackexchange.com/docs), e.g.:

    se = SEAPI.SEAPI()
    se.fetch("users/{ids}/comments/{toid}", ids=[29407, 23354], toid=22656,
              sort="creation", order="desc", site="stackoverflow") 

Second arose from practical reason - I wanted to plot [Map of all SE sites (except the 3 biggest)](https://meta.stackoverflow.com/questions/157976/map-of-all-se-sites-except-the-3-biggest), see also [Tag Graph Map of Stack Exchange wiki at GitHub](https://github.com/stared/tag-graph-map-of-stackexchange/wiki), using e.g.:

    se.fetch("users", site="cogsci")

to easily get `user_id`, `account_id` and `reputation`.

### License

An open license [CC BY 3.0](http://creativecommons.org/licenses/by/3.0/).
No warranty etc.

### Download

From GitHub: https://github.com/stared/se-api-py.

Do you want to raise an issue or contribute? Great! 

### Contact

`[email protected]`

### General philosophy of usage

* se.fetch\[_one\](command, **parameters)
* parameters as in the documentation
* in the command, "{something}" and "{somethings}" are treated as placeholders for an int/str or a list of int/str, respectively

### Examples

    import SEAPI
    se = SEAPI.SEAPI()
    
    some_users = se.fetch_one("users/{ids}", ids=[1,3,7,9,13], site="stackoverflow") 

    all_user = se.fetch("users", site="academia")

Now, `some_users` and `all_user` are lists with the respective response from each query.

Alternatively, you can initialize SEAPI with default options, typically - site name, e.g.

	so = SEAPI.SEAPI(site="stackoverflow")

	some_questions = so.fetch("questions", page_limit=10)
	# except for very small sites, you want to set page limit

	some_sorted_posts = so.fetch_one("posts", order="desc", sort="votes")
	# for sorting sometimes asking for more that one results in "throttle violation"

If you want to diagnose a problem, or avoid it:

	so.last_call
	# lookup at the last command sent

	so.last_status
	# check the last response status

	slow_food = so.fetch("tags", min_delay=0.5)
	# or set delay (by default it's 0.05)

### Feedback

I'm a beginner, so all remarks with respect to the code quality, good practices, etc are welcome!