Requests: The Simple (e.g. usable) HTTP Module
==============================================

::

    :::::::::  ::::::::::  ::::::::   :::    ::: ::::::::::  ::::::::  :::::::::::  ::::::::  
    :+:    :+: :+:        :+:    :+:  :+:    :+: :+:        :+:    :+:     :+:     :+:    :+: 
    +:+    +:+ +:+        +:+    +:+  +:+    +:+ +:+        +:+            +:+     +:+        
    +#++:++#:  +#++:++#   +#+    +:+  +#+    +:+ +#++:++#   +#++:++#++     +#+     +#++:++#++ 
    +#+    +#+ +#+        +#+  # +#+  +#+    +#+ +#+               +#+     +#+            +#+ 
    #+#    #+# #+#        #+#   +#+   #+#    #+# #+#        #+#    #+#     #+#     #+#    #+# 
    ###    ### ##########  ###### ###  ########  ##########  ########      ###      ########  

                                                              


Overview
--------

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 (yes, even worse than Logging) are a result of the various built-in HTTP libraries. 

But this one's different. This one's going to be awesome. And simple.

Really simple. 

Features
--------

- Extremely simple GET, HEAD, POST, PUT, DELETE Requests
    + Simple HTTP Header Request Attachment
    + Simple Data/Params Request Attachment
- Simple Basic HTTP Authentication
    + Simple URL + HTTP Auth Registry


Usage
-----

It couldn't be simpler. ::

    >>> import requests
    >>> r = requests.get('http://google.com')


HTTPS? Basic Authentication? ::
    
    >>> r = requests.get('https://convore.com/api/account/verify.json')
    >>> r.status_code
    401

    
Uh oh, we're not authorized! Let's add authentication. ::
    
    >>> conv_auth = requests.AuthObject('requeststest', 'requeststest')
    >>> r = requests.get('https://convore.com/api/account/verify.json', conv_auth=auth)
    
    >>> r.status_code
    200 
    
    >>> r.headers['content-type']
    application/json
    
    >>> r.content
    {"username": "requeststest", "url": "/users/requeststest/", "id": "9408", "img": "censored-long-url"}



API
---
    
**Requests:**
    
    >>> request.get(url, params={}, headers={} auth=None)
    <response object>

    >>> request.head(url, params={}, headers={} auth=None)
    <response object>

    >>> request.put(url, data='', headers={}, auth=None)
    <response object>

    >>> request.post(url, data={}, headers={}, auth=None)
    <response object>

    >>> request.delete(url, params={}, headers={}, auth=None)
    <response object>
    
**Responses:**
    
    Request.status_code:
         (Integer) Received HTTP Status Code Response

    Request.headers:
        (Dictionary) Received HTTP Response Headers

    Request.content:
        (Bytes) Received Content


Installation
------------

To install requests, simply: ::

    $ pip install requests
    
Or, if you absolutely must: ::

    $ easy_install requests

But, you really shouldn't do that.
   


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
-------

- Documentation
- Write it!
- Test it!
- Fo shizzle

.. _`the repository`: http://github.com/kennethreitz/requests
.. _AUTHORS: http://github.com/kennethreitz/requests/blob/master/AUTHORS