Big API update

docs/api.rst

@@ -1,14 +1,60 @@
+.. _api:
+
 API
 ===
 
+.. module:: requests
+
+This part of the documentation covers all the interfaces of Requests.  For
+parts where Requests depends on external libraries, we document the most
+important right here and provide links to the canonical documentation.
+
 
 Main Interface
 --------------
 
+.. autofunction:: get
+.. autofunction:: post
+.. autofunction:: put
+.. autofunction:: delete
+.. autofunction:: head
+
+.. autoclass:: requests.models.Response
+   :inherited-members:
+
 
 Exceptions
 ----------
 
+.. autoexception:: HTTPError
+
+.. autoexception:: RequestException
+
+.. autoexception:: requests.models.AuthenticationError
+.. autoexception:: requests.models.URLRequired
+.. autoexception:: requests.models.InvalidMethod
+
 
 Internals
----------
+---------
+
+These items are an internal component to Requests, and should never be
+seen by the end user (developer). This part of the API documentation
+exists for those who are extending the functionality of Requests.
+
+Functions
+~~~~~~~~~
+
+.. autofunction:: request
+
+Classes
+~~~~~~~
+
+.. autoclass:: requests.models.Request
+   :inherited-members:
+
+Structures
+~~~~~~~~~~
+
+.. autoclass:: requests.structures.CaseInsensitiveDict
+   :inherited-members:

docs/index.rst

@@ -11,7 +11,7 @@ Release v\ |version|. (:ref:`Installation <install>`)
 Requests is an :ref:`ISC Licensed <isc>` HTTP library, written in Python, for human beings.
 
 Most existing Python modules for sending HTTP requests are extremely verbose
-and cumbersome. Python's builtin :py:class:`urllib2 <library.urllib2>` module provides most of
+and cumbersome. Python's builtin :py:module::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.
 

requests/api.py

@@ -20,7 +20,7 @@ __all__ = ('request', 'get', 'head', 'post', 'put', 'delete')
 
 
 def request(method, url, **kwargs):
-    """Sends a `method` request. Returns :class:`Response` object.
+    """Sends a Constructs and sends a :class:`Request <models.Request>`. Returns :class:`Response <models.Response>` object.
 
     :param method: method for the new :class:`Request` object.
     :param url: URL for the new :class:`Request` object.

requests/models.py

@@ -23,7 +23,7 @@ from .packages.poster.streaminghttp import register_openers, get_handlers
 
 
 class Request(object):
-    """The :class:`Request` object. It carries out all functionality of
+    """The :class:`Request <models.Request>` object. It carries out all functionality of
     Requests. Recommended interface is with the Requests functions.
     """
 
@@ -34,11 +34,18 @@ class Request(object):
 
         socket.setdefaulttimeout(timeout)
 
+        #: Request URL.
         self.url = url
+        #: Dictonary of HTTP Headers to attach to the :class:`Request <models.Request>`.
         self.headers = headers
+        #: Dictionary of files to multipart upload (``{filename: content}``).
         self.files = files
+        #: HTTP Method to use. Available: GET, HEAD, PUT, POST, DELETE.
         self.method = method
+        #: Form or Byte data to attach to the :class:`Request <models.Request>`.
         self.data = dict()
+        #: True if :class:`Request <models.Request>` is part of a redirect chain (disables history
+        #: and HTTPError storage).
         self.redirect = redirect
 
         # self.data = {}
@@ -55,15 +62,19 @@ class Request(object):
         else:
             self._enc_data = data
 
-
+        #: :class:`Response <models.Response>` instance, containing
+        #: content and metadata of HTTP Response, once :attr:`sent <send>`.
         self.response = Response()
 
         if isinstance(auth, (list, tuple)):
             auth = AuthObject(*auth)
         if not auth:
             auth = auth_manager.get_auth(self.url)
+        #: :class:`AuthObject` to attach to :class:`Request <models.Request>`.
         self.auth = auth
+        #: CookieJar to attach to :class:`Request <models.Request>`.
         self.cookiejar = cookiejar
+        #: True if Request has been sent.
         self.sent = False
 
 
@@ -104,9 +115,6 @@ class Request(object):
 
 
         _handlers.append(HTTPRedirectHandler)
-        # print _handlers
-        # print '^^'
-        # print '!'
 
         if not _handlers:
             return urllib2.urlopen
@@ -128,7 +136,7 @@ class Request(object):
         return opener.open
 
     def _build_response(self, resp):
-        """Build internal Response object from given response."""
+        """Build internal :class:`Response <models.Response>` object from given response."""
 
         def build(resp):
 
@@ -253,19 +261,34 @@ class Request(object):
 
 
 class Response(object):
-    """The :class:`Request` object. All :class:`Request` objects contain a
-    :class:`Request.response <response>` attribute, which is an instance of
-    this class.
+    """The core :class:`Response <models.Response>` object. All
+    :class:`Request <models.Request>` objects contain a
+    :class:`response <models.Response>` attribute, which is an instance
+    of this class.
     """
 
     def __init__(self):
+        #: Raw content of the response, in bytes.
+        #: If ``content-encoding`` of response was set to ``gzip``, the
+        #: response data will be automatically deflated.
         self.content = None
+        #: Integer Code of responded HTTP Status.
         self.status_code = None
+        #: Case-insensitive Dictionary of Response Headers.
+        #: For example, ``headers['content-encoding']`` will return the
+        #: value of a ``'Content-Encoding'`` response header.
         self.headers = CaseInsensitiveDict()
+        #: Final URL location of Response.
         self.url = None
+        #: True if no :attr:`error` occured.
         self.ok = False
+        #: Resulting :class:`HTTPError` of request, if one occured.
         self.error = None
+        #: True, if the response :attr:`content` is cached locally.
         self.cached = False
+        #: A list of :class:`Response <models.Response>` objects from
+        #: the history of the Request. Any redirect responses will end
+        #: up here.
         self.history = []
 
 
@@ -274,22 +297,24 @@ class Response(object):
 
 
     def __nonzero__(self):
-        """Returns true if status_code is 'OK'."""
+        """Returns true if :attr:`status_code` is 'OK'."""
         return not self.error
 
 
     def raise_for_status(self):
-        """Raises stored HTTPError if one exists."""
+        """Raises stored :class:`HTTPError`, if one occured."""
         if self.error:
             raise self.error
 
     def read(self, *args):
+        """Returns :attr:`content`. Used for file-like object compatiblity."""
+
         return self.content
 
 
 
 class AuthManager(object):
-    """Authentication Manager."""
+    """Requests Authentication Manager."""
 
     def __new__(cls):
         singleton = cls.__dict__.get('__singleton__')
@@ -458,6 +483,12 @@ class AuthObject(object):
         else:
             self.handler = handler
 
+
+# ----------
+# Exceptions
+# ----------
+
+
 class RequestException(Exception):
     """There was an ambiguous exception that occured while handling your
     request."""

requests/structures.py

@@ -12,7 +12,10 @@ from UserDict import DictMixin
 
 
 class CaseInsensitiveDict(DictMixin):
-    """docstring for CaseInsensitiveDict"""
+    """Case-insensitive Dictionary for :class:`Response <models.Response>` Headers.
+
+    For example, ``headers['content-encoding']`` will return the
+    value of a ``'Content-Encoding'`` response header."""
 
     def __init__(self, *args, **kwargs):
         # super(CaseInsensitiveDict, self).__init__()