Repository files navigation

• Re-use the same socket connection for multiple requests(HTTPConnectionPool andHTTPSConnectionPool)(with optional client-side certificate verification).
• File posting (encode_multipart_formdata).
• Built-in redirection and retries (optional).
• Supports gzip and deflate decoding.
• Thread-safe and sanity-safe.
• Works with AppEngine, gevent, and eventlib.
• Tested on Python 2.6+ and Python 3.2+, 99% unit test coverage.
• Small and easy to understand codebase perfect for extending and building upon.For a more comprehensive solution, have a look atRequests which is also powered by urllib3.

There are two critical features missing from the Python standard library:Connection re-using/pooling and file posting. It's not terribly hard toimplement these yourself, but it's much easier to use a module that alreadydid the work for you.

The Python standard librariesurllib andurllib2 have little to dowith each other. They were designed to be independent and standalone, eachsolving a different scope of problems, andurllib3 follows in a similarvein.

Performance. When you normally do a urllib call, a separate socketconnection is created with each request. By reusing existing sockets(supported since HTTP 1.1), the requests will take up less resources on theserver's end, and also provide a faster response time at the client's end.With some simple benchmarks (seetest/benchmark.py), downloading 15 URLs from google.com is about twice as fast when usingHTTPConnectionPool (which uses 1 connection) than using plain urllib (whichuses 15 connections).

This library is perfect for:

• Talking to an API
• Crawling a website
• Any situation where being able to post files, handle redirection, andretrying is useful. It's relatively lightweight, so it can be used foranything!

Go tourllib3.readthedocs.orgfor more nice syntax-highlighted examples.

But, long story short:

import urllib3http = urllib3.PoolManager()r = http.request('GET', 'http://google.com/')print r.status, r.data

ThePoolManager will take care of reusing connections for you wheneveryou request the same host. For more fine-grained control of your connectionpools, you should look atConnectionPool.

We use some external dependencies to run the urllib3 test suite. Easiest way torun the tests is thusly from the urllib3 source root:

$ pip install -r test-requirements.txt$ nosetests.....................................................

Success! You could alsopip install coverage to get code coverage reporting.

1. Check for open issues or opena fresh issue to start a discussion around a feature idea or a bug. There isaContributor Friendly tag for issues that should be ideal for people whoare not very familiar with the codebase yet.
2. Fork theurllib3 repository on Githubto start making your changes.
3. Write a test which shows that the bug was fixed or that the feature worksas expected.
4. Send a pull request and bug the maintainer until it gets merged and published.:) Make sure to add yourself toCONTRIBUTORS.txt.