docs update

docs/api.rst

@@ -18,16 +18,6 @@ They all return an instance of the :class:`Response <Response>` object.
 
 .. autofunction:: request
 
----------------------
-
-.. autoclass:: requests.Request
-   :inherited-members:
-
-.. autoclass:: Response
-   :inherited-members:
-
----------------------
-
 .. autofunction:: head
 .. autofunction:: get
 .. autofunction:: post
@@ -36,9 +26,17 @@ They all return an instance of the :class:`Response <Response>` object.
 .. autofunction:: delete
 
 
------------------
+Lower-Level Classes
+~~~~~~~~~~~~~~~~~~~
 
-.. autofunction:: session
+.. autoclass:: requests.Request
+   :inherited-members:
+
+.. autoclass:: Response
+   :inherited-members:
+
+Sessions
+--------
 
 .. autoclass:: Session
    :inherited-members:

requests/models.py

@@ -157,6 +157,14 @@ class Request(RequestHooksMixin):
     :param auth: Auth handler or (user, pass) tuple.
     :param cookies: dictionary or CookieJar of cookies to attach to this request.
     :param hooks: dictionary of callback hooks, for internal usage.
+
+    Usage::
+
+      >>> import requests
+      >>> req = requests.Request('GET', 'http://httpbin.org/get')
+      >>> req.prepare()
+      <PreparedRequest [GET]>
+
     """
     def __init__(self,
         method=None,
@@ -214,7 +222,19 @@ class PreparedRequest(RequestEncodingMixin, RequestHooksMixin):
     """The fully mutable :class:`PreparedRequest <PreparedRequest>` object,
     containing the exact bytes that will be sent to the server.
 
-    Generated from a :class:`Request <Request>` object or manually.
+    Generated from either a :class:`Request <Request>` object or manually.
+
+    Usage::
+
+      >>> import requests
+      >>> req = requests.Request('GET', 'http://httpbin.org/get')
+      >>> r = req.prepare()
+      <PreparedRequest [GET]>
+
+      >>> s = requests.Session()
+      >>> s.send(r)
+      <Response [200]>
+
     """
 
     def __init__(self):

requests/sessions.py

@@ -131,7 +131,17 @@ class SessionRedirectMixin(object):
 
 
 class Session(SessionRedirectMixin):
-    """A Requests session."""
+    """A Requests session.
+
+    Provides cookie persistience, connection-pooling, and configuration.
+
+    Basic Usage::
+
+      >>> import requests
+      >>> s = requests.Session()
+      >>> s.get('http://httpbin.org/get')
+      200
+    """
 
     def __init__(self):
 
@@ -140,7 +150,7 @@ class Session(SessionRedirectMixin):
         #: :class:`Session <Session>`.
         self.headers = default_headers()
 
-        #: Authentication tuple or object to attach to
+        #: Default Authentication tuple or object to attach to
         #: :class:`Request <Request>`.
         self.auth = None
 
@@ -157,19 +167,19 @@ class Session(SessionRedirectMixin):
         #: representing multivalued query parameters.
         self.params = {}
 
-        #: Stream response content.
+        #: Stream response content default.
         self.stream = False
 
-        #: SSL Verification.
+        #: SSL Verification default.
         self.verify = True
 
-        #: SSL certificate.
+        #: SSL certificate default.
         self.cert = None
 
         #: Maximum number of redirects to follow.
         self.max_redirects = DEFAULT_REDIRECT_LIMIT
 
-        #: Should we trust the environment
+        #: Should we trust the environment?
         self.trust_env = True
 
         # Set up a CookieJar to be used by default