Python HTTP for Humans.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Description: Requests: HTTP for Humans ========================= .. image:: https://travis-ci.org/kennethreitz/requests.png?branch=master :target: https://travis-ci.org/kennethreitz/requests Requests is an Apache2 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 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. Things shouldn't be this way. Not in Python. .. code-block:: pycon >>> r = requests.get('https://api.github.com', auth=('user', 'pass')) >>> r.status_code 204 >>> r.headers['content-type'] 'application/json' >>> r.text ... See `the same code, without Requests <https://gist.github.com/973705>`_. Requests allow you to send HTTP/1.1 requests. You can add headers, form data, multipart files, and parameters with simple Python dictionaries, and access the response data in the same way. It's powered by httplib and `urllib3 <https://github.com/shazow/urllib3>`_, but it does all the hard work and crazy hacks for you. Features -------- - International Domains and URLs - Keep-Alive & Connection Pooling - Sessions with Cookie Persistence - Browser-style SSL Verification - Basic/Digest Authentication - Elegant Key/Value Cookies - Automatic Decompression - Unicode Response Bodies - Multipart File Uploads - Connection Timeouts - Thread-safety Installation ------------ To install requests, simply: .. code-block:: bash $ pip install requests Or, if you absolutely must: .. code-block:: bash $ easy_install requests But, you really shouldn't do that. Contribute ---------- #. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug. There is a Contributor Friendly tag for issues that should be ideal for people who are not very familiar with the codebase yet. #. Fork `the repository`_ on Github to start making your changes to the **master** branch (or branch off of it). #. Write a test which shows that the bug was fixed or that the feature works as expected. #. Send a pull request and bug the maintainer until it gets merged and published. :) Make sure to add yourself to AUTHORS_. .. _`the repository`: http://github.com/kennethreitz/requests .. _AUTHORS: https://github.com/kennethreitz/requests/blob/master/AUTHORS.rst .. :changelog: History ------- 1.2.0 (2013-03-31) ++++++++++++++++++ - Fixed cookies on sessions and on requests - Significantly change how hooks are dispatched - hooks now receive all the arguments specified by the user when making a request so hooks can make a secondary request with the same parameters. This is especially necessary for authentication handler authors - certifi support was removed - Fixed bug where using OAuth 1 with body ``signature_type`` sent no data - Major proxy work thanks to @Lukasa including parsing of proxy authentication from the proxy url - Fix DigestAuth handling too many 401s - Update vendored urllib3 to include SSL bug fixes - Allow keyword arguments to be passed to ``json.loads()`` via the ``Response.json()`` method - Don't send ``Content-Length`` header by default on ``GET`` or ``HEAD`` requests - Add ``elapsed`` attribute to ``Response`` objects to time how long a request took. - Fix ``RequestsCookieJar`` - Sessions and Adapters are now picklable, i.e., can be used with the mutiprocessing library - Update charade to version 1.0.3 The change in how hooks are dispatched will likely cause a great deal of issues. 1.1.0 (2013-01-10) ++++++++++++++++++ - CHUNKED REQUESTS - Support for iterable response bodies - Assume servers persist redirect params - Allow explicit content types to be specified for file data - Make merge_kwargs case-insensitive when looking up keys 1.0.3 (2012-12-18) ++++++++++++++++++ - Fix file upload encoding bug - Fix cookie behavior 1.0.2 (2012-12-17) ++++++++++++++++++ - Proxy fix for HTTPAdapter. 1.0.1 (2012-12-17) ++++++++++++++++++ - Cert verification exception bug. - Proxy fix for HTTPAdapter. 1.0.0 (2012-12-17) ++++++++++++++++++ - Massive Refactor and Simplification - Switch to Apache 2.0 license - Swappable Connection Adapters - Mountable Connection Adapters - Mutable ProcessedRequest chain - /s/prefetch/stream - Removal of all configuration - Standard library logging - Make Response.json() callable, not property. - Usage of new charade project, which provides python 2 and 3 simultaneous chardet. - Removal of all hooks except 'response' - Removal of all authentication helpers (OAuth, Kerberos) This is not a backwards compatible change. 0.14.2 (2012-10-27) +++++++++++++++++++ - Improved mime-compatible JSON handling - Proxy fixes - Path hack fixes - Case-Insensistive Content-Encoding headers - Support for CJK parameters in form posts 0.14.1 (2012-10-01) +++++++++++++++++++ - Python 3.3 Compatibility - Simply default accept-encoding - Bugfixes 0.14.0 (2012-09-02) ++++++++++++++++++++ - No more iter_content errors if already downloaded. 0.13.9 (2012-08-25) +++++++++++++++++++ - Fix for OAuth + POSTs - Remove exception eating from dispatch_hook - General bugfixes 0.13.8 (2012-08-21) +++++++++++++++++++ - Incredible Link header support :) 0.13.7 (2012-08-19) +++++++++++++++++++ - Support for (key, value) lists everywhere. - Digest Authentication improvements. - Ensure proxy exclusions work properly. - Clearer UnicodeError exceptions. - Automatic casting of URLs to tsrings (fURL and such) - Bugfixes. 0.13.6 (2012-08-06) +++++++++++++++++++ - Long awaited fix for hanging connections! 0.13.5 (2012-07-27) +++++++++++++++++++ - Packaging fix 0.13.4 (2012-07-27) +++++++++++++++++++ - GSSAPI/Kerberos authentication! - App Engine 2.7 Fixes! - Fix leaking connections (from urllib3 update) - OAuthlib path hack fix - OAuthlib URL parameters fix. 0.13.3 (2012-07-12) +++++++++++++++++++ - Use simplejson if available. - Do not hide SSLErrors behind Timeouts. - Fixed param handling with urls containing fragments. - Significantly improved information in User Agent. - client certificates are ignored when verify=False 0.13.2 (2012-06-28) +++++++++++++++++++ - Zero dependencies (once again)! - New: Response.reason - Sign querystring parameters in OAuth 1.0 - Client certificates no longer ignored when verify=False - Add openSUSE certificate support 0.13.1 (2012-06-07) +++++++++++++++++++ - Allow passing a file or file-like object as data. - Allow hooks to return responses that indicate errors. - Fix Response.text and Response.json for body-less responses. 0.13.0 (2012-05-29) +++++++++++++++++++ - Removal of Requests.async in favor of `grequests <https://github.com/kennethreitz/grequests>`_ - Allow disabling of cookie persistiance. - New implimentation of safe_mode - cookies.get now supports default argument - Session cookies not saved when Session.request is called with return_response=False - Env: no_proxy support. - RequestsCookieJar improvements. - Various bug fixes. 0.12.1 (2012-05-08) +++++++++++++++++++ - New ``Response.json`` property. - Ability to add string file uploads. - Fix out-of-range issue with iter_lines. - Fix iter_content default size. - Fix POST redirects containing files. 0.12.0 (2012-05-02) +++++++++++++++++++ - EXPERIMENTAL OAUTH SUPPORT! - Proper CookieJar-backed cookies interface with awesome dict-like interface. - Speed fix for non-iterated content chunks. - Move ``pre_request`` to a more usable place. - New ``pre_send`` hook. - Lazily encode data, params, files. - Load system Certificate Bundle if ``certify`` isn't available. - Cleanups, fixes. 0.11.2 (2012-04-22) +++++++++++++++++++ - Attempt to use the OS's certificate bundle if ``certifi`` isn't available. - Infinite digest auth redirect fix. - Multi-part file upload improvements. - Fix decoding of invalid %encodings in URLs. - If there is no content in a response don't throw an error the second time that content is attempted to be read. - Upload data on redirects. 0.11.1 (2012-03-30) +++++++++++++++++++ * POST redirects now break RFC to do what browsers do: Follow up with a GET. * New ``strict_mode`` configuration to disable new redirect behavior. 0.11.0 (2012-03-14) +++++++++++++++++++ * Private SSL Certificate support * Remove select.poll from Gevent monkeypatching * Remove redundant generator for chunked transfer encoding * Fix: Response.ok raises Timeout Exception in safe_mode 0.10.8 (2012-03-09) +++++++++++++++++++ * Generate chunked ValueError fix * Proxy configuration by environment variables * Simplification of iter_lines. * New `trust_env` configuration for disabling system/environment hints. * Suppress cookie errors. 0.10.7 (2012-03-07) +++++++++++++++++++ * `encode_uri` = False 0.10.6 (2012-02-25) +++++++++++++++++++ * Allow '=' in cookies. 0.10.5 (2012-02-25) +++++++++++++++++++ * Response body with 0 content-length fix. * New async.imap.