From: Kenneth Reitz Date: Mon, 16 May 2011 05:13:05 +0000 (-0400) Subject: Big API update X-Git-Tag: v0.4.1^2~34 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=6e13e7343d2d1a37fe61365c7658984bcf4d9194;p=services%2Fpython-requests.git Big API update --- diff --git a/docs/api.rst b/docs/api.rst index a7d4285..cabc0e7 100644 --- a/docs/api.rst +++ b/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 ---------- \ 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 diff --git a/docs/index.rst b/docs/index.rst index 16e83f2..792bcf7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,7 +11,7 @@ Release v\ |version|. (:ref:`Installation `) Requests is an :ref:`ISC Licensed ` 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 ` 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. diff --git a/requests/api.py b/requests/api.py index 26335e5..b4b9319 100644 --- a/requests/api.py +++ b/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 `. Returns :class:`Response ` object. :param method: method for the new :class:`Request` object. :param url: URL for the new :class:`Request` object. diff --git a/requests/models.py b/requests/models.py index e1a2da5..b6650b0 100644 --- a/requests/models.py +++ b/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 ` 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 `. 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 `. self.data = dict() + #: True if :class:`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 ` instance, containing + #: content and metadata of HTTP Response, once :attr:`sent `. 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 `. self.auth = auth + #: CookieJar to attach to :class:`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 ` 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 ` attribute, which is an instance of - this class. + """The core :class:`Response ` object. All + :class:`Request ` objects contain a + :class:`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 ` 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.""" diff --git a/requests/structures.py b/requests/structures.py index 391ddb1..0c82c7b 100644 --- a/requests/structures.py +++ b/requests/structures.py @@ -12,7 +12,10 @@ from UserDict import DictMixin class CaseInsensitiveDict(DictMixin): - """docstring for CaseInsensitiveDict""" + """Case-insensitive Dictionary for :class:`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__()