big docs update

diff --git a/docs/api.rst b/docs/api.rst
index cbd24fd..e3338b6 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -13,34 +13,48 @@ important right here and provide links to the canonical documentation.
 Main Interface
 --------------
 
-All of Request's functionality can be accessed by these 6 methods. They
-all return a :class:`Response <models.Response>` object.
+All of Request's functionality can be accessed by these 7 methods.
+They all return an instance of the :class:`Response <Response>` object.
 
+.. autofunction:: request
 .. autofunction:: head
 .. autofunction:: get
 .. autofunction:: post
 .. autofunction:: put
 .. autofunction:: patch
 .. autofunction:: delete
-.. autofunction:: request
+
 
 -----------
 
 
-.. autoclass:: requests.models.Response
+.. autoclass:: Response
    :inherited-members:
 
 
-Exceptions
-----------
 
-.. autoexception:: HTTPError
+Utilities
+---------
 
-.. autoexception:: RequestException
+These functions are used internally, but may be useful outside of
+Requests.
 
-.. autoexception:: requests.models.AuthenticationError
-.. autoexception:: requests.models.URLRequired
-.. autoexception:: requests.models.InvalidMethod
+.. module:: requests.utils
+
+Cookies
+~~~~~~~
+
+.. autofunction:: dict_from_cookiejar
+.. autofunction:: cookiejar_from_dict
+.. autofunction:: add_dict_to_cookiejar
+
+Encodings
+~~~~~~~~~
+
+.. autofunction:: get_encodings_from_content
+.. autofunction:: get_encoding_from_headers
+.. autofunction:: get_unicode_from_response
+.. autofunction:: decode_gzip
 
 
 Internals
@@ -50,8 +64,26 @@ 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.
 
+Exceptions
+~~~~~~~~~~
+
+.. module:: requests
+
+.. autoexception:: HTTPError
+
+.. autoexception:: RequestException
+
+.. autoexception:: AuthenticationError
+.. autoexception:: URLRequired
+.. autoexception:: InvalidMethod
+.. autoexception:: TooManyRedirects
+
+
+
 Classes
 ~~~~~~~
 
-.. autoclass:: requests.models.Request
+.. autoclass:: requests.Request
    :inherited-members:
+
+

diff --git a/requests/api.py b/requests/api.py
index 0cea63d..5ded386 100644 (file)
--- a/requests/api.py
+++ b/requests/api.py
@@ -25,8 +25,8 @@ def request(method, url,
     params=None, data=None, headers=None, cookies=None, files=None, auth=None,
     timeout=None, allow_redirects=False, proxies=None, hooks=None):
 
-    """Constructs and sends a :class:`Request <models.Request>`.
-    Returns :class:`Response <models.Response>` object.
+    """Constructs and sends a :class:`Request <Request>`.
+    Returns :class:`Response <Response>` object.
 
     :param method: method for the new :class:`Request` object.
     :param url: URL for the new :class:`Request` object.
@@ -41,6 +41,8 @@ def request(method, url,
     :param proxies: (optional) Dictionary mapping protocol to the URL of the proxy.
     """
 
+    method = method.upper()
+
     if cookies is None:
         cookies = {}
 
@@ -85,50 +87,31 @@ def get(url, **kwargs):
     """Sends a GET request. Returns :class:`Response` object.
 
     :param url: URL for the new :class:`Request` object.
-    :param params: (optional) Dictionary of parameters, or bytes, to be sent in the query string for the :class:`Request`.
-    :param headers: (optional) Dictionary of HTTP Headers to send with the :class:`Request`.
-    :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`.
-    :param auth: (optional) AuthObject to enable Basic HTTP Auth.
-    :param timeout: (optional) Float describing the timeout of the request.
-    :param proxies: (optional) Dictionary mapping protocol to the URL of the proxy.
+    :param **kwargs: Optional arguments that ``request`` takes.
     """
 
-    return request('GET', url, **kwargs)
+    return request('get', url, **kwargs)
 
 
 def head(url, **kwargs):
-
     """Sends a HEAD request. Returns :class:`Response` object.
 
     :param url: URL for the new :class:`Request` object.
-    :param params: (optional) Dictionary of parameters, or bytes, to be sent in the query string for the :class:`Request`.
-    :param headers: (optional) Dictionary of HTTP Headers to sent with the :class:`Request`.
-    :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`.
-    :param auth: (optional) AuthObject to enable Basic HTTP Auth.
-    :param timeout: (optional) Float describing the timeout of the request.
-    :param proxies: (optional) Dictionary mapping protocol to the URL of the proxy.
+    :param **kwargs: Optional arguments that ``request`` takes.
     """
 
-    return request('HEAD', url, **kwargs)
+    return request('head', url, **kwargs)
 
 
 def post(url, data='', **kwargs):
-
     """Sends a POST request. Returns :class:`Response` object.
 
     :param url: URL for the new :class:`Request` object.
     :param data: (optional) Dictionary or bytes to send in the body of the :class:`Request`.
-    :param headers: (optional) Dictionary of HTTP Headers to sent with the :class:`Request`.
-    :param files: (optional) Dictionary of 'filename': file-like-objects for multipart encoding upload.
-    :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`.
-    :param auth: (optional) AuthObject to enable Basic HTTP Auth.
-    :param timeout: (optional) Float describing the timeout of the request.
-    :param allow_redirects: (optional) Boolean. Set to True if redirect following is allowed.
-    :param params: (optional) Dictionary of parameters, or bytes, to be sent in the query string for the :class:`Request`.
-    :param proxies: (optional) Dictionary mapping protocol to the URL of the proxy.
+    :param **kwargs: Optional arguments that ``request`` takes.
     """
 
-    return request('POST', url, data=data, **kwargs)
+    return request('post', url, data=data, **kwargs)
 
 
 def put(url, data='', **kwargs):
@@ -136,17 +119,10 @@ def put(url, data='', **kwargs):
 
     :param url: URL for the new :class:`Request` object.
     :param data: (optional) Dictionary or bytes to send in the body of the :class:`Request`.
-    :param headers: (optional) Dictionary of HTTP Headers to sent with the :class:`Request`.
-    :param files: (optional) Dictionary of 'filename': file-like-objects for multipart encoding upload.
-    :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`.
-    :param auth: (optional) AuthObject to enable Basic HTTP Auth.
-    :param timeout: (optional) Float describing the timeout of the request.
-    :param allow_redirects: (optional) Boolean. Set to True if redirect following is allowed.
-    :param params: (optional) Dictionary of parameters, or bytes, to be sent in the query string for the :class:`Request`.
-    :param proxies: (optional) Dictionary mapping protocol to the URL of the proxy.
+    :param **kwargs: Optional arguments that ``request`` takes.
     """
 
-    return request('PUT', url, data=data, **kwargs)
+    return request('put', url, data=data, **kwargs)
 
 
 def patch(url, data='', **kwargs):
@@ -154,31 +130,17 @@ def patch(url, data='', **kwargs):
 
     :param url: URL for the new :class:`Request` object.
     :param data: (optional) Dictionary or bytes to send in the body of the :class:`Request`.
-    :param headers: (optional) Dictionary of HTTP Headers to sent with the :class:`Request`.
-    :param files: (optional) Dictionary of 'filename': file-like-objects for multipart encoding upload.
-    :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`.
-    :param auth: (optional) AuthObject to enable Basic HTTP Auth.
-    :param timeout: (optional) Float describing the timeout of the request.
-    :param allow_redirects: (optional) Boolean. Set to True if redirect following is allowed.
-    :param params: (optional) Dictionary of parameters, or bytes, to be sent in the query string for the :class:`Request`.
-    :param proxies: (optional) Dictionary mapping protocol to the URL of the proxy.
+    :param **kwargs: Optional arguments that ``request`` takes.
     """
 
-    return request('PATCH', url, **kwargs)
+    return request('patch', url, **kwargs)
 
 
 def delete(url, **kwargs):
-
     """Sends a DELETE request. Returns :class:`Response` object.
 
     :param url: URL for the new :class:`Request` object.
-    :param params: (optional) Dictionary of parameters, or bytes, to be sent in the query string for the :class:`Request`.
-    :param headers: (optional) Dictionary of HTTP Headers to sent with the :class:`Request`.
-    :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`.
-    :param auth: (optional) AuthObject to enable Basic HTTP Auth.
-    :param timeout: (optional) Float describing the timeout of the request.
-    :param allow_redirects: (optional) Boolean. Set to True if redirect following is allowed.
-    :param proxies: (optional) Dictionary mapping protocol to the URL of the proxy.
+    :param **kwargs: Optional arguments that ``request`` takes.
     """
 
-    return request('DELETE', url, **kwargs)
+    return request('delete', url, **kwargs)

diff --git a/requests/core.py b/requests/core.py
index 8ba34a2..c436664 100644 (file)
--- a/requests/core.py
+++ b/requests/core.py
@@ -19,9 +19,11 @@ __license__ = 'ISC'
 __copyright__ = 'Copyright 2011 Kenneth Reitz'
 
 
-from models import HTTPError
+from models import HTTPError, Request, Response
 from api import *
 from exceptions import *
 from sessions import session
 from status_codes import codes
-from config import settings
\ No newline at end of file
+from config import settings
+
+import utils
\ No newline at end of file

diff --git a/requests/models.py b/requests/models.py
index 2ca2c75..9233518 100644 (file)
--- a/requests/models.py
+++ b/requests/models.py
@@ -31,7 +31,7 @@ REDIRECT_STATI = (codes.moved, codes.found, codes.other, codes.temporary_moved)
 
 
 class Request(object):
-    """The :class:`Request <models.Request>` object. It carries out all functionality of
+    """The :class:`Request <Request>` object. It carries out all functionality of
     Requests. Recommended interface is with the Requests functions.
     """
 
@@ -47,7 +47,7 @@ class Request(object):
         #: Request URL.
         self.url = url
 
-        #: Dictonary of HTTP Headers to attach to the :class:`Request <models.Request>`.
+        #: Dictonary of HTTP Headers to attach to the :class:`Request <Request>`.
         self.headers = headers
 
         #: Dictionary of files to multipart upload (``{filename: content}``).
@@ -57,14 +57,14 @@ class Request(object):
         self.method = method
 
         #: Dictionary or byte of request body data to attach to the
-        #: :class:`Request <models.Request>`.
+        #: :class:`Request <Request>`.
         self.data = None
 
         #: Dictionary or byte of querystring data to attach to the
-        #: :class:`Request <models.Request>`.
+        #: :class:`Request <Request>`.
         self.params = None
 
-        #: True if :class:`Request <models.Request>` is part of a redirect chain (disables history
+        #: True if :class:`Request <Request>` is part of a redirect chain (disables history
         #: and HTTPError storage).
         self.redirect = redirect
 
@@ -77,7 +77,7 @@ class Request(object):
         self.data, self._enc_data = self._encode_params(data)
         self.params, self._enc_params = self._encode_params(params)
 
-        #: :class:`Response <models.Response>` instance, containing
+        #: :class:`Response <Response>` instance, containing
         #: content and metadata of HTTP Response, once :attr:`sent <send>`.
         self.response = Response()
 
@@ -86,10 +86,10 @@ class Request(object):
         if not auth:
             auth = auth_manager.get_auth(self.url)
 
-        #: :class:`AuthObject` to attach to :class:`Request <models.Request>`.
+        #: :class:`AuthObject` to attach to :class:`Request <Request>`.
         self.auth = auth
 
-        #: CookieJar to attach to :class:`Request <models.Request>`.
+        #: CookieJar to attach to :class:`Request <Request>`.
         self.cookiejar = cookiejar
 
         #: True if Request has been sent.
@@ -174,7 +174,7 @@ class Request(object):
 
 
     def _build_response(self, resp, is_error=False):
-        """Build internal :class:`Response <models.Response>` object
+        """Build internal :class:`Response <Response>` object
         from given response.
         """
 
@@ -386,9 +386,9 @@ class Request(object):
 
 
 class Response(object):
-    """The core :class:`Response <models.Response>` object. All
-    :class:`Request <models.Request>` objects contain a
-    :class:`response <models.Response>` attribute, which is an instance
+    """The core :class:`Response <Response>` object. All
+    :class:`Request <Request>` objects contain a
+    :class:`response <Response>` attribute, which is an instance
     of this class.
     """
 
@@ -419,7 +419,7 @@ class Response(object):
         #: Resulting :class:`HTTPError` of request, if one occured.
         self.error = None
 
-        #: A list of :class:`Response <models.Response>` objects from
+        #: A list of :class:`Response <Response>` objects from
         #: the history of the Request. Any redirect responses will end
         #: up here.
         self.history = []

diff --git a/requests/utils.py b/requests/utils.py
index 0f6e842..d96310b 100644 (file)
--- a/requests/utils.py
+++ b/requests/utils.py
@@ -116,9 +116,13 @@ def get_unicode_from_response(r):
     :param r: Reponse object to get unicode content from.
 
     Tried:
+
     1. charset from content-type
-    2. every encodings from <meta ... charset=XXX>
+
+    2. every encodings from ``<meta ... charset=XXX>``
+
     3. fall back and replace all unicode characters
+
     """
 
     tried_encodings = []