From 0f393d00b51bc54c5075447e4a8b21f0bed6acd8 Mon Sep 17 00:00:00 2001 From: SVN-Git Migration Date: Thu, 8 Oct 2015 13:19:39 -0700 Subject: Imported Upstream version 1.9 --- README.rst | 46 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 35 insertions(+), 11 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index e76c261..6a81759 100644 --- a/README.rst +++ b/README.rst @@ -17,16 +17,18 @@ Highlights - 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+, 100% unit test coverage. +- Tested on Python 2.6+, Python 3.2+, and PyPy, with 100% unit test coverage. - Small and easy to understand codebase perfect for extending and building upon. For a more comprehensive solution, have a look at `Requests `_ which is also powered by ``urllib3``. - + + You might already be using urllib3! =================================== -``urllib3`` powers `many great Python libraries `_, -including ``pip`` and ``requests``. +``urllib3`` powers `many great Python libraries +`_, including ``pip`` and +``requests``. What's wrong with urllib and urllib2? @@ -42,6 +44,7 @@ with each other. They were designed to be independent and standalone, each solving a different scope of problems, and ``urllib3`` follows in a similar vein. + Why do I want to reuse connections? =================================== @@ -63,6 +66,7 @@ This library is perfect for: retrying is useful. It's relatively lightweight, so it can be used for anything! + Examples ======== @@ -81,26 +85,39 @@ But, long story short:: The ``PoolManager`` will take care of reusing connections for you whenever you request the same host. For more fine-grained control of your connection -pools, you should look at -`ConnectionPool `_. +pools, you should look at `ConnectionPool +`_. Run the tests ============= We use some external dependencies, multiple interpreters and code coverage -analysis while running test suite. Easiest way to run the tests is thusly the -``tox`` utility: :: +analysis while running test suite. Our ``Makefile`` handles much of this for +you as long as you're running it `inside of a virtualenv +`_:: + + $ make test + [... magically installs dependencies and runs tests on your virtualenv] + Ran 182 tests in 1.633s - $ tox - # [..] + OK (SKIP=6) + +Note that code coverage less than 100% is regarded as a failing run. Some +platform-specific tests are skipped unless run in that platform. To make sure +the code works in all of urllib3's supported platforms, you can run our ``tox`` +suite:: + + $ make test-all + [... tox creates a virtualenv for every platform and runs tests inside of each] py26: commands succeeded py27: commands succeeded py32: commands succeeded py33: commands succeeded py34: commands succeeded -Note that code coverage less than 100% is regarded as a failing run. +Our test suite `runs continuously on Travis CI +`_ with every pull request. Contributing @@ -116,3 +133,10 @@ Contributing as expected. #. Send a pull request and bug the maintainer until it gets merged and published. :) Make sure to add yourself to ``CONTRIBUTORS.txt``. + + +Sponsorship +=========== + +If your company benefits from this library, please consider `sponsoring its +development `_. -- cgit v1.2.3