basic FAQ

docs/index.rst

@@ -13,7 +13,8 @@ Requests is an :ref:`ISC Licensed <isc>` HTTP library, written in Python, for hu
 Most existing Python modules for sending HTTP requests are extremely verbose
 and cumbersome. Python's builtin **urllib2** module provides most of
 the HTTP capabilities you should need, but the api is thoroughly **broken**.
-It requires an *enormous* amount of work (even method overrides) to perform the simplest of tasks.
+It requires an *enormous* amount of work (even method overrides) to perform
+the simplest of tasks.
 
 Things shouldn’t be this way. Not in Python.
 
@@ -41,28 +42,34 @@ Testimonals
 `Twitter, Inc <http://twitter.com>`_ uses Requests internally.
 
 **Daniel Greenfeld**
-    Nuked a 1200 LOC spaghetti code library with 10 lines of code thanks to @kennethreitz's request library. Today has been AWESOME.
+    Nuked a 1200 LOC spaghetti code library with 10 lines of code thanks to
+    @kennethreitz's request library. Today has been AWESOME.
 
 **Kenny Meyers**
-    Python HTTP: When in doubt, or when not in doubt, use Requests. Beautiful, simple, Pythonic.
+    Python HTTP: When in doubt, or when not in doubt, use Requests. Beautiful,
+    simple, Pythonic.
 
 **Rich Leland**
    Requests is awesome. That is all.
 
 **Steve Pike**
-  I can never remember how to do it the regular way. ``import requests; requests.get()`` is just so easy!
+  I can never remember how to do it the regular way.
+  ``import requests; requests.get()`` is just so easy!
 
 
 User Guide
 ----------
 
-This part of the documentation, which is mostly prose, begins with some background information about Requests, then focuses on step-by-step instructions for getting the most out of Requests.
+This part of the documentation, which is mostly prose, begins with some
+background information about Requests, then focuses on step-by-step
+instructions for getting the most out of Requests.
 
 .. toctree::
    :maxdepth: 2
 
    user/intro
    user/install
+   user/faq
 ..   user/quickstart
    user/advanced
 

docs/user/faq.rst

@@ -0,0 +1,43 @@
+.. _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.