From: Kenneth Reitz Date: Thu, 13 Oct 2011 18:54:36 +0000 (-0400) Subject: Migrate new docs over. X-Git-Tag: v0.6.3^2~7 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=4a7fdef3ea70b7acd7f883c6d08a8fee4a2b24f1;p=services%2Fpython-requests.git Migrate new docs over. --- diff --git a/docs/api.rst b/docs/api.rst index cbd24fd..328e9e8 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -13,34 +13,52 @@ 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 ` object. +All of Request's functionality can be accessed by these 7 methods. +They all return an instance of the :class:`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. + +.. module:: requests.utils + +Cookies +~~~~~~~ + +.. autofunction:: dict_from_cookiejar +.. autofunction:: cookiejar_from_dict +.. autofunction:: add_dict_to_cookiejar + +Curl +~~~~ +.. autofunction:: curl_from_request + +Encodings +~~~~~~~~~ -.. autoexception:: requests.models.AuthenticationError -.. autoexception:: requests.models.URLRequired -.. autoexception:: requests.models.InvalidMethod +.. autofunction:: get_encodings_from_content +.. autofunction:: get_encoding_from_headers +.. autofunction:: get_unicode_from_response +.. autofunction:: decode_gzip Internals @@ -50,8 +68,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/docs/community/faq.rst b/docs/community/faq.rst index b571764..91ca06b 100644 --- a/docs/community/faq.rst +++ b/docs/community/faq.rst @@ -3,7 +3,24 @@ Frequently Asked Questions ========================== -This part of the documentation covers common questions about Requests. +This part of the documentation answers common questions about Requests. + +Encoded Data? +------------- + +Requests automatically decompresses gzip-encoded responses, and does +its best to decodes response content to unicode when possible. + +You can get direct access to the raw response (and even the socket), +if needed as well. + + +Custom User-Agents? +------------------- + +Requests allows you to easily override User-Agent strings, along with +any other HTTP Header. + Why not Httplib2? ----------------- @@ -34,10 +51,33 @@ Chris Adams gave an excellent summary on Python 3 Support? ----------------- -It's on the way. Here's a list of `supported interpreters `_. +It's on the way. Here's a list of Python platforms that are officially +supported: + +* cPython 2.5 +* cPython 2.5.5 +* cPython 2.5.6 +* cPython 2.6 +* cPython 2.6.6 +* cPython 2.6.7 +* cPython 2.7 +* cPython 2.7.1 +* cPython 2.7.2 +* PyPy-c 1.4 +* PyPy-c 1.5 + + +Support for Python 3.x is coming *very* soon. Keep-alive Support? ------------------- -It's on the way. \ No newline at end of file +It's on the way. + + +Proxy Support? +-------------- + +You bet! + diff --git a/docs/community/updates.rst b/docs/community/updates.rst index 942ccac..e6e1559 100644 --- a/docs/community/updates.rst +++ b/docs/community/updates.rst @@ -20,7 +20,6 @@ I often tweet about new features and releases of Requests. Follow `@kennethreitz `_ for updates. - Mailing List ------------ diff --git a/docs/index.rst b/docs/index.rst index 8bef62b..d849ed5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -36,10 +36,18 @@ multipart files, and parameters with simple Python dictionaries, and access the response data in the same way. It's powered by :py:class:`urllib2`, but it does all the hard work and crazy hacks for you. -Testimonals ------------ +Testimonials +------------ -`Twitter, Inc `_ uses Requests internally. +`Twitter, Inc `_, +a U.S. Federal Institution, +`Readability `_, and +`Work for Pie `_ +use Requests internally. + +**Armin Ronacher** + Requests is the perfect example how beautiful an API can be with the + right level of abstraction. **Daniel Greenfeld** Nuked a 1200 LOC spaghetti code library with 10 lines of code thanks to @@ -52,10 +60,6 @@ Testimonals **Rich Leland** Requests is awesome. That is all. -**Steve Pike** - I can never remember how to do it the regular way. - ``import requests; requests.get()`` is just so easy! - User Guide ---------- diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index d145da2..ae7827c 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -66,7 +66,7 @@ Available hooks: You can assign a hook function on a per-request basis by passing a ``{hook_name: callback_function}`` dictionary to the ``hooks`` request -paramaeter:: +parameter:: hooks=dict(args=print_url) @@ -134,4 +134,4 @@ To do so, just configure Requests with a stream to write to:: >>> requests.settings.verbose = sys.stderr >>> requests.get('http://httpbin.org/headers') 2011-08-17T03:04:23.380175 GET http://httpbin.org/headers - \ No newline at end of file + diff --git a/docs/user/install.rst b/docs/user/install.rst index cdc6d86..dc4aa62 100644 --- a/docs/user/install.rst +++ b/docs/user/install.rst @@ -3,7 +3,8 @@ Installation ============ -This part of the documentation covers the installation of Requests. The first step to using any software package is getting it properly installed. +This part of the documentation covers the installation of Requests. +The first step to using any software package is getting it properly installed. Distribute & Pip @@ -24,7 +25,8 @@ But, you really `shouldn't do that `_:: +If the Cheeseshop is down, you can also install Requests from Kenneth Reitz's +personal `Cheeseshop mirror `_:: $ pip install -i http://pip.kreitz.co/simple requests @@ -48,6 +50,7 @@ Or, download the `zipball ` section. +Eager to get started? This page gives a good introduction in how to get started +with Requests. This assumes you already have Requests installed. If you do not, +head over to the :ref:`Installation ` section. First, make sure that: @@ -25,7 +27,8 @@ Let's get GitHub's public timeline :: r = requests.get('https://github.com/timeline.json') -Now, we have a :class:`Response` object called ``r``. We can get all the information we need from this. +Now, we have a :class:`Response` object called ``r``. We can get all the +information we need from this. Response Content @@ -90,7 +93,8 @@ interface:: 'content-type': 'application/json; charset=utf-8' } -The dictionary is special, though: it's made just for HTTP headers. According to `RFC 2616 `_, HTTP +The dictionary is special, though: it's made just for HTTP headers. According to +`RFC 2616 `_, HTTP Headers are case-insensitive. So, we can access the headers using any capitalization we want:: @@ -118,7 +122,7 @@ If a response contains some Cookies, you can get quick access to them:: >>> print r.cookies {'requests-is': 'awesome'} -The underlying CookieJar is also available for more advanced handing:: +The underlying CookieJar is also available for more advanced handling:: >>> r.request.cookiejar