--- /dev/null
+.. _faq:
+
+Frequently Asked Questions
+==========================
+
+This part of the documentation covers common questions about Requests.
+
+Why not Httplib2?
+-----------------
+
+Chris Adams gave an excellent summary on
+`Hacker News <http://news.ycombinator.com/item?id=2884406>`_:
+
+ httplib2 is part of why you should use requests: it's far more respectable
+ as a client but not as well documented and it still takes way too much code
+ for basic operations. I appreciate what httplib2 is trying to do, that
+ there's a ton of hard low-level annoyances in building a modern HTTP
+ client, but really, just use requests instead. Kenneth Reitz is very
+ motivated and he gets the degree to which simple things should be simple
+ whereas httplib2 feels more like an academic exercise than something
+ people should use to build production systems[1].
+
+ Disclosure: I'm listed in the requests AUTHORS file but can claim credit
+ for, oh, about 0.0001% of the awesomeness.
+
+ 1. http://code.google.com/p/httplib2/issues/detail?id=96 is a good example:
+ an annoying bug which affect many people, there was a fix available for
+ months, which worked great when I applied it in a fork and pounded a couple
+ TB of data through it, but it took over a year to make it into trunk and
+ even longer to make it onto PyPI where any other project which required "
+ httplib2" would get the working version.
+
+
+Python 3 Support?
+-----------------
+
+It's on the way.
+
+
+Keep-alive Support?
+-------------------
+
+It's on the way.
\ No newline at end of file
--- /dev/null
+.. _support:
+
+Support
+=======
+
+If you have a questions or issues about Requests, there are serveral options:
+
+Send a Tweet
+------------
+
+If your question is less than 140 characters, feel free to send a tweet to
+`@kennethreitz <http://twitter.com/kennethreitz>`_.
+
+
+File an Issue
+-------------
+
+If you notice some unexpected behavior in Requests, or want to see support
+for a new feature,
+`file an issue on GitHub <https://github.com/kennethreitz/requests/issues>`_.
+
+
+E-mail
+------
+
+I'm more than happy to answer any personal or in-depth questions about
+Requests. Feel free to email
+`requests@kennethreitz.com <mailto:requests@kennethreitz.com>`_.
+
+
+IRC
+---
+
+The official Freenode channel for Requests is
+`#python-requests <irc://irc.freenode.net/python-requests>`_
+
+I'm also available as **kennethreitz** on Freenode.
\ No newline at end of file
--- /dev/null
+.. _updates:
+
+Updates
+=======
+
+If you'd like to stay up to date on the community and development of Requests,
+there are serveral options:
+
+GitHub
+------
+
+The best way to track the development of Requests is through
+`the GitHub repo <https://github.com/kennethreitz/requests>`_.
+
+Twitter
+-------
+
+I often tweet about new features and releases of Requests.
+
+Follow `@kennethreitz <https://twitter.com/kennethreitz>`_ for updates.
+
+
+
+Mailing List
+------------
+
+There's a low-volume mailing list for Requests. To subscribe to the
+mailing list, send an email to
+`requests@librelist.org <mailto:requests@librelist.org>`_.
+
+
--- /dev/null
+Authors
+=======
+
+
+.. include:: ../../AUTHORS
\ No newline at end of file
user/intro
user/install
- user/faq
-.. user/quickstart
+ user/quickstart
user/advanced
+Community Guide
+-----------------
+
+This part of the documentation, which is mostly prose, details the
+Requests ecosystem and community.
+
+.. toctree::
+ :maxdepth: 2
+
+ community/faq
+ community/support
+ community/updates
+
API Documentation
-----------------
dev/internals
dev/todo
+ dev/authors
+++ /dev/null
-.. _faq:
-
-Frequently Asked Questions
-==========================
-
-This part of the documentation covers common questions about Requests.
-
-Why not Httplib2?
------------------
-
-Chris Adams gave an excellent summary on
-`Hacker News <http://news.ycombinator.com/item?id=2884406>`_:
-
- httplib2 is part of why you should use requests: it's far more respectable
- as a client but not as well documented and it still takes way too much code
- for basic operations. I appreciate what httplib2 is trying to do, that
- there's a ton of hard low-level annoyances in building a modern HTTP
- client, but really, just use requests instead. Kenneth Reitz is very
- motivated and he gets the degree to which simple things should be simple
- whereas httplib2 feels more like an academic exercise than something
- people should use to build production systems[1].
-
- Disclosure: I'm listed in the requests AUTHORS file but can claim credit
- for, oh, about 0.0001% of the awesomeness.
-
- 1. http://code.google.com/p/httplib2/issues/detail?id=96 is a good example:
- an annoying bug which affect many people, there was a fix available for
- months, which worked great when I applied it in a fork and pounded a couple
- TB of data through it, but it took over a year to make it into trunk and
- even longer to make it onto PyPI where any other project which required "
- httplib2" would get the working version.
-
-
-Python 3 Support?
------------------
-
-It's on the way.
-
-
-Keep-alive Support?
--------------------
-
-It's on the way.
\ No newline at end of file
-Feature Overview
-================
-
-Requests is designed to solve a 90% use case — making simple requests. While most
-HTTP libraries are extremely extensible, they often attempt to support the entire HTTP Spec.
-This often leads to extremely messy and cumbersome APIs, as is the case with urllib2. Requests abandons support for edge-cases, and focuses on the essentials.
-
-
-.. _features:
-
-Requests Can:
--------------
-
-- Make **GET**, **POST**, **PUT**, **DELETE**, and **HEAD** requests.
-- Handle HTTP and HTTPS Requests
-- Add Request headers (with a simple dictionary)
-- URLEncode your Form Data (with a simple dictionary)
-- Add Multi-part File Uploads (with a simple dictionary)
-- Handle CookieJars (with a single parameter)
-- Add HTTP Authentication (with a single parameter)
-- Handle redirects (with history)
-- Automatically decompress GZip'd responses
-- Support Unicode URLs
-- Gracefully timeout
-- Interface with Eventlet & Gevent
-
-
-Requests Can't:
----------------
-
-- Handle Caching
-- Handle Keep-Alives
-
+.. _quickstart:
Quickstart
==========
+.. module:: requests
-GET Request
------------
-
-
-Adding Parameters
------------------
-
+Eager to get started? This page gives a good introduction in how to get started with Requests. This assumes you already have Tablib installed. If you do not, head over to the :ref:`Installation <install>` section.
+First, make sure that:
-Adding Headers
---------------
+* Tablib is :ref:`installed <install>`
+* Tablib is :ref:`up-to-date <updates>`
+Lets gets started with some simple use cases and examples.
-HTTP Basic Auth
----------------
-
-Tracking Redirects
+Make a GET Request
------------------
+Making a standard request with Requests is very simple.
+Let's get GitHub's public timeline ::
+ r = requests.get('https://github.com/timeline.json')
-HTTP POST (Form Data)
----------------------
+Now, we have a :class:`Response` object. We can get all the information
+we need from this.
-HTTP POST (Binary Data)
------------------------
+Response Content
+----------------
+We can read the content of the server's response::
-HTTP POST (Multipart Files)
----------------------------
+ >>> r.content
+ '[{"repository":{"open_issues":0,"url":"https://github.com/...
-HTTP PUT
---------
+Response Status Codes
+---------------------
+
+We can check the response status code::
-HTTP DELETE
------------
+ >>> r.status_code
+ 200
+Requests also comes with a built-in status code lookup object for easy
+reference::
-HTTP HEAD
----------
+ >>> r.status_code == requests.codes.ok
+ True
\ No newline at end of file
projects / services / python-requests.git / commitdiff