From 56fe2e2e44b89f15a0ea3322aab6202cdd6e8bf5 Mon Sep 17 00:00:00 2001 From: SVN-Git Migration Date: Thu, 8 Oct 2015 13:41:17 -0700 Subject: Imported Upstream version 0.6.1 --- README.rst | 114 ++++++++++++++++--------------------------------------------- 1 file changed, 29 insertions(+), 85 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index d73a48f..3f6455e 100644 --- a/README.rst +++ b/README.rst @@ -1,11 +1,35 @@ Requests: HTTP for Humans ========================= -Most existing Python modules for dealing HTTP requests are insane. I have to look up *everything* that I want to do. Most of my worst Python experiences are a result of the various built-in HTTP libraries (yes, even worse than Logging). +Requests is an ISC Licensed HTTP library, written in Python, for human +beings. -But this one's different. This one's going to be awesome. And simple. +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. + +:: + + >>> r = requests.get('https://api.github.com', auth=('user', 'pass')) + >>> r.status_code + 204 + >>> r.headers['content-type'] + 'application/json' + >>> r.content + ... + +See `the same code, without Requests `_. + +Requests allow you to send **HEAD**, **GET**, **POST**, **PUT**, +**PATCH**, and **DELETE** HTTP 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 urllib2, but it does +all the hard work and crazy hacks for you. -Really simple. Features -------- @@ -36,14 +60,14 @@ It couldn't be simpler. :: HTTPS? Basic Authentication? :: - >>> r = requests.get('https://httpbin.ep.ip/basic-auth/user/pass') + >>> r = requests.get('https://httpbin.ep.io/basic-auth/user/pass') >>> r.status_code 401 Uh oh, we're not authorized! Let's add authentication. :: - >>> r = requests.get(https://httpbin.ep.ip/basic-auth/user/pass', auth=('user', 'pass')) + >>> r = requests.get('https://httpbin.ep.io/basic-auth/user/pass', auth=('user', 'pass')) >>> r.status_code 200 @@ -55,80 +79,6 @@ Uh oh, we're not authorized! Let's add authentication. :: '{"authenticated": true, "user": "user"}' - -API ---- - -**Requests:** - -All request functions return a Response object (see below). - -If a {filename: fileobject} dictionary is passed in (files=...), a multipart_encode upload will be performed. -If CookieJar object is is passed in (cookies=...), the cookies will be sent with the request. - - HEAD Requests - >>> requests.head(url, params={}, headers={}, cookies=None, auth=None, timeout=None, proxies={}) - - - GET Requests - >>> requests.get(url, params={}, headers={}, cookies=None, auth=None, timeout=None, proxies={}) - - - POST Requests - >>> requests.post(url, data={}, headers={}, files={}, cookies=None, auth=None, timeout=None, allow_redirects=False, params{}, proxies={}) - - - PUT Requests - >>> requests.put(url, data={}, headers={}, files={}, cookies=None, auth=None, timeout=None, allow_redirects=False, params{}, proxies={}) - - - PATCH Requests - >>> requests.post(url, data={}, headers={}, files={}, cookies=None, auth=None, timeout=None, allow_redirects=False, params{}, proxies={}) - - - DELETE Requests - >>> requests.delete(url, params={}, headers={}, cookies=None, auth=None, timeout=None, allow_redirects=False, params{}, proxies={}) - - - -**Responses:** - - Response.status_code - (Integer) Received HTTP Status Code Response - - Response.headers - ((CaseInsensitive) Dictionary) Received HTTP Response Headers. - - Response.content - (Bytes) Received Content. - - Response.history - (List of Responses) Redirection History. - - Response.url - (String) URL of response. Useful for detecting redirects. - - Response.ok - (Bool) True if no errors occurred during the request, and the status_code is kosher. - - Response.cached - (Bool) True if Response.content is stored within the object. - - Response.error - (HTTPError) If an HTTPError occurred (e.g. status of 404), Otherwise this is None. - - Response.raise_for_status() - Raises HTTPError if a request is not kosher. - - -**HTTP Authentication Registry:** - - You can register AuthObjects to automatically enable HTTP Authentication on requests that contain a registered base URL string. - - >>> requests.auth_manager.add_auth(url, authobject) - - - Installation ------------ @@ -150,11 +100,5 @@ Contribute If you'd like to contribute, simply fork `the repository`_, commit your changes to the **develop** branch (or branch off of it), and send a pull request. Make sure you add yourself to AUTHORS_. - -Roadmap -------- - -- Sphinx Documentation - .. _`the repository`: http://github.com/kennethreitz/requests .. _AUTHORS: http://github.com/kennethreitz/requests/blob/master/AUTHORS -- cgit v1.2.3