Requests: HTTP for Humans¶

Release v1.1.0. (Installation)

Requests is an Apache2 Licensed HTTP library, written in Python, for human beings.

Python’s standard urllib2 module provides most of the HTTP capabilities you need, but the API is thoroughly broken. It was built for a different time — and a different web. 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/user', auth=('user', 'pass'))
>>> r.status_code
200
>>> r.headers['content-type']
'application/json; charset=utf8'
>>> r.encoding
'utf-8'
>>> r.text
u'{"type":"User"...'
>>> r.json()
{u'private_gists': 419, u'total_private_repos': 77, ...}

See similar code, without Requests.

Requests takes all of the work out of Python HTTP/1.1 — making your integration with web services seamless. There’s no need to manually add query strings to your URLs, or to form-encode your POST data. Keep-alive and HTTP connection pooling are 100% automatic, powered by urllib3, which is embedded within Requests.

Testimonials¶

Her Majesty’s Government, Amazon, Google, Twilio, Mozilla, Heroku, PayPal, NPR, Obama for America, Transifex, Native Instruments, The Washington Post, Twitter, SoundCloud, Kippt, Readability, and Federal US Institutions use Requests internally. It has been downloaded over 2,000,000 times from PyPI.

Armin Ronacher: Requests is the perfect example how beautiful an API can be with the right level of abstraction.
Matt DeBoard: I’m going to get @kennethreitz’s Python requests module tattooed on my body, somehow. The whole thing.
Daniel Greenfeld: Nuked a 1200 LOC spaghetti code library with 10 lines of code thanks to @kennethreitz’s request library. Today has been AWESOME.
Kenny Meyers: Python HTTP: When in doubt, or when not in doubt, use Requests. Beautiful, simple, Pythonic.

Feature Support¶

Requests is ready for today’s web.

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
.netrc support
Python 2.6—3.3
Thread-safe.

User Guide¶

This part of the documentation, which is mostly prose, begins with some background information about Requests, then focuses on step-by-step instructions for getting the most out of Requests.

Introduction
- Philosophy
- Apache2 License
- Requests License
Installation
- Distribute & Pip
- Cheeseshop Mirror
- Get the Code
Quickstart
- Make a Request
- Passing Parameters In URLs
- Response Content
- Binary Response Content
- JSON Response Content
- Raw Response Content
- Custom Headers
- More complicated POST requests
- POST a Multipart-Encoded File
- Response Status Codes
- Response Headers
- Cookies
- Redirection and History
- Timeouts
- Errors and Exceptions
Advanced Usage
- Session Objects
- Request and Response Objects
- SSL Cert Verification
- Body Content Workflow
- Keep-Alive
- Streaming Uploads
- Chunk-Encoded Requests
- Event Hooks
- Custom Authentication
- Streaming Requests
- Proxies
- Compliance
- HTTP Verbs
- Link Headers
Authentication
- Basic Authentication
- Digest Authentication
- Other Authentication
- New Forms of Authentication

Community Guide¶

This part of the documentation, which is mostly prose, details the Requests ecosystem and community.

Frequently Asked Questions
Integrations
Articles & Talks
Support
Updates

API Documentation¶

If you are looking for information on a specific function, class or method, this part of the documentation is for you.

Developer Interface
- Main Interface
- Request Sessions

Contributor Guide¶

If you want to contribute to the project, this part of the documentation is for you.

Development Philosophy
How to Help
Authors

Requests is an elegant and simple HTTP library for Python, built for human beings. You are currently looking at the documentation of the development release.

Donate

If you love Requests, consider supporting the author on Gittip:

If your organization uses Requests, consider financial support:

Requests Pro

Feedback

Feedback is greatly appreciated. If you have any questions, comments, random praise, or anonymous threats, shoot me an email.

Useful Links

Requests @ PyPI
Requests @ GitHub
Requests @ Flattr
Issue Tracker

Navigation