+.. _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
----------
\ No newline at end of file
+---------
+
+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:
\ No newline at end of file
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.
"""
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 = {}
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
_handlers.append(HTTPRedirectHandler)
- # print _handlers
- # print '^^'
- # print '!'
if not _handlers:
return urllib2.urlopen
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):
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 = []
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__')
else:
self.handler = handler
+
+# ----------
+# Exceptions
+# ----------
+
+
class RequestException(Exception):
"""There was an ambiguous exception that occured while handling your
request."""