diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 8 | ||||
| -rw-r--r-- | docs/collections.rst | 4 | ||||
| -rw-r--r-- | docs/conf.py | 14 | ||||
| -rw-r--r-- | docs/contrib.rst | 2 | ||||
| -rw-r--r-- | docs/exceptions.rst | 4 | ||||
| -rw-r--r-- | docs/helpers.rst | 20 | ||||
| -rw-r--r-- | docs/index.rst | 106 | ||||
| -rw-r--r-- | docs/make.bat | 4 | ||||
| -rw-r--r-- | docs/managers.rst | 12 | ||||
| -rw-r--r-- | docs/pools.rst | 16 | ||||
| -rw-r--r-- | docs/security.rst | 46 |
11 files changed, 118 insertions, 118 deletions
diff --git a/docs/Makefile b/docs/Makefile index 135c543e..b3453458 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -72,17 +72,17 @@ qthelp: @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/urllib3.qhcp" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/urllib4.qhcp" @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/urllib3.qhc" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/urllib4.qhc" devhelp: $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @echo "Build finished." @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/urllib3" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/urllib3" + @echo "# mkdir -p $$HOME/.local/share/devhelp/urllib4" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/urllib4" @echo "# devhelp" epub: diff --git a/docs/collections.rst b/docs/collections.rst index b3481402..8386e700 100644 --- a/docs/collections.rst +++ b/docs/collections.rst @@ -1,10 +1,10 @@ Collections =========== -These datastructures are used to implement the behaviour of various urllib3 +These datastructures are used to implement the behaviour of various urllib4 components in a decoupled and application-agnostic design. -.. automodule:: urllib3._collections +.. automodule:: urllib4._collections .. autoclass:: RecentlyUsedContainer :members: diff --git a/docs/conf.py b/docs/conf.py index 7ac8393d..35825103 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# urllib3 documentation build configuration file, created by +# urllib4 documentation build configuration file, created by # sphinx-quickstart on Wed Oct 5 13:15:40 2011. # # This file is execfile()d with the current directory set to its containing dir. @@ -22,7 +22,7 @@ import sys root_path = os.path.abspath(os.path.join(os.path.dirname(__file__), '..')) sys.path.insert(0, root_path) -import urllib3 +import urllib4 # -- General configuration ----------------------------------------------------- @@ -54,7 +54,7 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'urllib3' +project = u'urllib4' copyright = u'{year}, Andrey Petrov'.format(year=date.today().year) # The version info for the project you're documenting, acts as replacement for @@ -62,7 +62,7 @@ copyright = u'{year}, Andrey Petrov'.format(year=date.today().year) # built documents. # # The short X.Y version. -version = urllib3.__version__ +version = urllib4.__version__ # The full version, including alpha/beta/rc tags. release = version @@ -178,7 +178,7 @@ html_theme = 'nature' #html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = 'urllib3doc' +htmlhelp_basename = 'urllib4doc' # -- Options for LaTeX output -------------------------------------------------- @@ -192,7 +192,7 @@ htmlhelp_basename = 'urllib3doc' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'urllib3.tex', u'urllib3 Documentation', + ('index', 'urllib4.tex', u'urllib4 Documentation', u'Andrey Petrov', 'manual'), ] @@ -225,7 +225,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'urllib3', u'urllib3 Documentation', + ('index', 'urllib4', u'urllib4 Documentation', [u'Andrey Petrov'], 1) ] diff --git a/docs/contrib.rst b/docs/contrib.rst index 99c54921..59d046c8 100644 --- a/docs/contrib.rst +++ b/docs/contrib.rst @@ -11,4 +11,4 @@ prime time. SNI-support for Python 2 ------------------------ -.. automodule:: urllib3.contrib.pyopenssl +.. automodule:: urllib4.contrib.pyopenssl diff --git a/docs/exceptions.rst b/docs/exceptions.rst index f9e05533..81ea2d54 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -1,7 +1,7 @@ Exceptions ========== -Custom exceptions defined by urllib3 +Custom exceptions defined by urllib4 -.. automodule:: urllib3.exceptions +.. automodule:: urllib4.exceptions :members: diff --git a/docs/helpers.rst b/docs/helpers.rst index 79f268ba..7913aca3 100644 --- a/docs/helpers.rst +++ b/docs/helpers.rst @@ -2,54 +2,54 @@ Helpers ======= Useful methods for working with :mod:`httplib`, completely decoupled from -code specific to **urllib3**. +code specific to **urllib4**. Timeouts -------- -.. automodule:: urllib3.util.timeout +.. automodule:: urllib4.util.timeout :members: Retries ------- -.. automodule:: urllib3.util.retry +.. automodule:: urllib4.util.retry :members: URL Helpers ----------- -.. automodule:: urllib3.util.url +.. automodule:: urllib4.util.url :members: Filepost -------- -.. automodule:: urllib3.filepost +.. automodule:: urllib4.filepost :members: -.. automodule:: urllib3.fields +.. automodule:: urllib4.fields :members: Request ------- -.. automodule:: urllib3.request +.. automodule:: urllib4.request :members: -.. automodule:: urllib3.util.request +.. automodule:: urllib4.util.request :members: Response -------- -.. automodule:: urllib3.response +.. automodule:: urllib4.response :members: :undoc-members: SSL/TLS Helpers --------------- -.. automodule:: urllib3.util.ssl_ +.. automodule:: urllib4.util.ssl_ :members: diff --git a/docs/index.rst b/docs/index.rst index 81ac2d8c..47bf39bd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,5 @@ ===================== -urllib3 Documentation +urllib4 Documentation ===================== .. toctree:: @@ -19,17 +19,17 @@ Highlights - Re-use the same socket connection for multiple requests, with optional client-side certificate verification. See: - :class:`~urllib3.connectionpool.HTTPConnectionPool` and - :class:`~urllib3.connectionpool.HTTPSConnectionPool` + :class:`~urllib4.connectionpool.HTTPConnectionPool` and + :class:`~urllib4.connectionpool.HTTPSConnectionPool` - File posting. See: - :func:`~urllib3.filepost.encode_multipart_formdata` + :func:`~urllib4.filepost.encode_multipart_formdata` - Built-in redirection and retries (optional). - Supports gzip and deflate decoding. See: - :func:`~urllib3.response.decode_gzip` and - :func:`~urllib3.response.decode_deflate` + :func:`~urllib4.response.decode_gzip` and + :func:`~urllib4.response.decode_deflate` - Thread-safe and sanity-safe. @@ -39,7 +39,7 @@ Highlights - Small and easy to understand codebase perfect for extending and building upon. For a more comprehensive solution, have a look at - `Requests <http://python-requests.org/>`_ which is also powered by urllib3. + `Requests <http://python-requests.org/>`_ which is also powered by urllib4. Getting Started @@ -48,16 +48,16 @@ Getting Started Installing ---------- -``pip install urllib3`` or fetch the latest source from -`github.com/shazow/urllib3 <https://github.com/shazow/urllib3>`_. +``pip install urllib4`` or fetch the latest source from +`github.com/shazow/urllib4 <https://github.com/shazow/urllib4>`_. Usage ----- .. doctest :: - >>> import urllib3 - >>> http = urllib3.PoolManager() + >>> import urllib4 + >>> http = urllib4.PoolManager() >>> r = http.request('GET', 'http://example.com/') >>> r.status 200 @@ -67,14 +67,14 @@ Usage 'data: ...' -**By default, urllib3 does not verify your HTTPS requests**. +**By default, urllib4 does not verify your HTTPS requests**. You'll need to supply a root certificate bundle, or use `certifi <https://certifi.io/>`_ .. doctest :: - >>> import urllib3, certifi - >>> http = urllib3.PoolManager(cert_reqs='CERT_REQUIRED', ca_certs=certifi.where()) + >>> import urllib4, certifi + >>> http = urllib4.PoolManager(cert_reqs='CERT_REQUIRED', ca_certs=certifi.where()) >>> r = http.request('GET', 'https://insecure.com/') Traceback (most recent call last): ... @@ -84,13 +84,13 @@ For more on making secure SSL/TLS HTTPS requests, read the :ref:`Security section <security>`. -urllib3's responses respect the :mod:`io` framework from Python's +urllib4's responses respect the :mod:`io` framework from Python's standard library, allowing use of these standard objects for purposes like buffering: .. doctest :: - >>> http = urllib3.PoolManager() + >>> http = urllib4.PoolManager() >>> r = http.urlopen('GET','http://example.com/', preload_content=False) >>> b = io.BufferedReader(r, 2048) >>> firstpart = b.read(100) @@ -101,7 +101,7 @@ like buffering: Components ========== -:mod:`urllib3` tries to strike a fine balance between power, extendability, and +:mod:`urllib4` tries to strike a fine balance between power, extendability, and sanity. To achieve this, the codebase is a collection of small reusable utilities and abstractions composed together in a few helpful layers. @@ -111,40 +111,40 @@ PoolManager The highest level is the :doc:`PoolManager(...) <managers>`. -The :class:`~urllib3.poolmanagers.PoolManager` will take care of reusing +The :class:`~urllib4.poolmanagers.PoolManager` will take care of reusing connections for you whenever you request the same host. This should cover most scenarios without significant loss of efficiency, but you can always drop down to a lower level component for more granular control. .. doctest :: - >>> import urllib3 - >>> http = urllib3.PoolManager(10) + >>> import urllib4 + >>> http = urllib4.PoolManager(10) >>> r1 = http.request('GET', 'http://example.com/') >>> r2 = http.request('GET', 'http://httpbin.org/') >>> r3 = http.request('GET', 'http://httpbin.org/get') >>> len(http.pools) 2 -A :class:`~urllib3.poolmanagers.PoolManager` is a proxy for a collection of +A :class:`~urllib4.poolmanagers.PoolManager` is a proxy for a collection of :class:`ConnectionPool` objects. They both inherit from -:class:`~urllib3.request.RequestMethods` to make sure that their API is +:class:`~urllib4.request.RequestMethods` to make sure that their API is similar, so that instances of either can be passed around interchangeably. ProxyManager ------------ -The :class:`~urllib3.poolmanagers.ProxyManager` is an HTTP proxy-aware -subclass of :class:`~urllib3.poolmanagers.PoolManager`. It produces a single -:class:`~urllib3.connectionpool.HTTPConnectionPool` instance for all HTTP +The :class:`~urllib4.poolmanagers.ProxyManager` is an HTTP proxy-aware +subclass of :class:`~urllib4.poolmanagers.PoolManager`. It produces a single +:class:`~urllib4.connectionpool.HTTPConnectionPool` instance for all HTTP connections and individual per-server:port -:class:`~urllib3.connectionpool.HTTPSConnectionPool` instances for tunnelled +:class:`~urllib4.connectionpool.HTTPSConnectionPool` instances for tunnelled HTTPS connections: :: - >>> proxy = urllib3.ProxyManager('http://localhost:3128/') + >>> proxy = urllib4.ProxyManager('http://localhost:3128/') >>> r1 = proxy.request('GET', 'http://google.com/') >>> r2 = proxy.request('GET', 'http://httpbin.org/') >>> len(proxy.pools) @@ -160,25 +160,25 @@ ConnectionPool The next layer is the :doc:`ConnectionPool(...) <pools>`. -The :class:`~urllib3.connectionpool.HTTPConnectionPool` and -:class:`~urllib3.connectionpool.HTTPSConnectionPool` classes allow you to +The :class:`~urllib4.connectionpool.HTTPConnectionPool` and +:class:`~urllib4.connectionpool.HTTPSConnectionPool` classes allow you to define a pool of connections to a single host and make requests against this pool with automatic **connection reusing** and **thread safety**. When the :mod:`ssl` module is available, then -:class:`~urllib3.connectionpool.HTTPSConnectionPool` objects can be configured +:class:`~urllib4.connectionpool.HTTPSConnectionPool` objects can be configured to check SSL certificates against specific provided certificate authorities. .. doctest :: - >>> import urllib3 - >>> conn = urllib3.connection_from_url('http://httpbin.org/') + >>> import urllib4 + >>> conn = urllib4.connection_from_url('http://httpbin.org/') >>> r1 = conn.request('GET', 'http://httpbin.org/') >>> r2 = conn.request('GET', '/user-agent') >>> r3 = conn.request('GET', 'http://example.com') Traceback (most recent call last): ... - urllib3.exceptions.HostChangedError: HTTPConnectionPool(host='httpbin.org', port=None): Tried to open a foreign host with url: http://example.com + urllib4.exceptions.HostChangedError: HTTPConnectionPool(host='httpbin.org', port=None): Tried to open a foreign host with url: http://example.com Again, a ConnectionPool is a pool of connections to a specific host. Trying to access a different host through the same pool will raise a ``HostChangedError`` @@ -186,10 +186,10 @@ exception unless you specify ``assert_same_host=False``. Do this at your own risk as the outcome is completely dependent on the behaviour of the host server. If you need to access multiple hosts and don't want to manage your own -collection of :class:`~urllib3.connectionpool.ConnectionPool` objects, then you -should use a :class:`~urllib3.poolmanager.PoolManager`. +collection of :class:`~urllib4.connectionpool.ConnectionPool` objects, then you +should use a :class:`~urllib4.poolmanager.PoolManager`. -A :class:`~urllib3.connectionpool.ConnectionPool` is composed of a collection +A :class:`~urllib4.connectionpool.ConnectionPool` is composed of a collection of :class:`httplib.HTTPConnection` objects. @@ -198,13 +198,13 @@ Timeout A timeout can be set to abort socket operations on individual connections after the specified duration. The timeout can be defined as a float or an instance of -:class:`~urllib3.util.timeout.Timeout` which gives more granular configuration +:class:`~urllib4.util.timeout.Timeout` which gives more granular configuration over how much time is allowed for different stages of the request. This can be set for the entire pool or per-request. .. doctest :: - >>> from urllib3 import PoolManager, Timeout + >>> from urllib4 import PoolManager, Timeout >>> # Manager with 3 seconds combined timeout. >>> http = PoolManager(timeout=3.0) @@ -222,14 +222,14 @@ set for the entire pool or per-request. >>> # Same Manager but request with a 5 second total timeout. >>> r = http.request('GET', 'http://httpbin.org/delay/1', timeout=Timeout(total=5.0)) -See the :class:`~urllib3.util.timeout.Timeout` definition for more details. +See the :class:`~urllib4.util.timeout.Timeout` definition for more details. Retry ----- Retries can be configured by passing an instance of -:class:`~urllib3.util.retry.Retry`, or disabled by passing ``False``, to the +:class:`~urllib4.util.retry.Retry`, or disabled by passing ``False``, to the ``retries`` parameter. Redirects are also considered to be a subset of retries but can be configured or @@ -237,7 +237,7 @@ disabled individually. :: - >>> from urllib3 import PoolManager, Retry + >>> from urllib4 import PoolManager, Retry >>> # Allow 3 retries total for all requests in this pool. These are the same: >>> http = PoolManager(retries=3) @@ -255,7 +255,7 @@ disabled individually. >>> r = http.request('GET', 'http://httpbin.org/', retries=Retry(connect=5)) -See the :class:`~urllib3.util.retry.Retry` definition for more details. +See the :class:`~urllib4.util.retry.Retry` definition for more details. Stream @@ -263,12 +263,12 @@ Stream You may also stream your response and get data as they come (e.g. when using ``transfer-encoding: chunked``). In this case, method -:func:`~urllib3.response.HTTPResponse.stream` will return generator. +:func:`~urllib4.response.HTTPResponse.stream` will return generator. :: - >>> from urllib3 import PoolManager - >>> http = urllib3.PoolManager() + >>> from urllib4 import PoolManager + >>> http = urllib4.PoolManager() >>> r = http.request("GET", "http://httpbin.org/stream/3") >>> r.getheader("transfer-encoding") @@ -290,11 +290,11 @@ response. Foundation ---------- -At the very core, just like its predecessors, :mod:`urllib3` is built on top of +At the very core, just like its predecessors, :mod:`urllib4` is built on top of :mod:`httplib` -- the lowest level HTTP library included in the Python standard library. -To aid the limited functionality of the :mod:`httplib` module, :mod:`urllib3` +To aid the limited functionality of the :mod:`httplib` module, :mod:`urllib4` provides various helper methods which are used with the higher level components but can also be used independently. @@ -318,11 +318,11 @@ prime time. Contributing ============ -#. `Check for open issues <https://github.com/shazow/urllib3/issues>`_ or open +#. `Check for open issues <https://github.com/shazow/urllib4/issues>`_ or open a fresh issue to start a discussion around a feature idea or a bug. There is a *Contributor Friendly* tag for issues that should be ideal for people who are not very familiar with the codebase yet. -#. Fork the `urllib3 repository on Github <https://github.com/shazow/urllib3>`_ +#. Fork the `urllib4 repository on Github <https://github.com/shazow/urllib4>`_ to start making your changes. #. Write a test which shows that the bug was fixed or that the feature works as expected. @@ -333,7 +333,7 @@ Contributing Sponsorship =========== -Please consider sponsoring urllib3 development, especially if your company +Please consider sponsoring urllib4 development, especially if your company benefits from this library. * **Project Grant**: A grant for contiguous full-time development has the @@ -346,11 +346,11 @@ benefits from this library. * **One-off**: Development will continue regardless of funding, but donations help move things further along quicker as the maintainer can allocate more time off to - work on urllib3 specifically. + work on urllib4 specifically. .. raw:: html - <a href="https://donorbox.org/personal-sponsor-urllib3" style="background-color:#1275ff;color:#fff;text-decoration:none;font-family:Verdana,sans-serif;display:inline-block;font-size:14px;padding:7px 16px;border-radius:5px;margin-right:2em;vertical-align:top;border:1px solid rgba(160,160,160,0.5);background-image:linear-gradient(#7dc5ee,#008cdd 85%,#30a2e4);box-shadow:inset 0 1px 0 rgba(255,255,255,0.25);">Sponsor with Credit Card</a> + <a href="https://donorbox.org/personal-sponsor-urllib4" style="background-color:#1275ff;color:#fff;text-decoration:none;font-family:Verdana,sans-serif;display:inline-block;font-size:14px;padding:7px 16px;border-radius:5px;margin-right:2em;vertical-align:top;border:1px solid rgba(160,160,160,0.5);background-image:linear-gradient(#7dc5ee,#008cdd 85%,#30a2e4);box-shadow:inset 0 1px 0 rgba(255,255,255,0.25);">Sponsor with Credit Card</a> <a class="coinbase-button" data-code="137087702cf2e77ce400d53867b164e6" href="https://coinbase.com/checkouts/137087702cf2e77ce400d53867b164e6">Sponsor with Bitcoin</a><script src="https://coinbase.com/assets/button.js" type="text/javascript"></script> @@ -362,7 +362,7 @@ Recent Sponsors --------------- Huge thanks to all the companies and individuals who financially contributed to -the development of urllib3. Please send a PR if you've donated and would like +the development of urllib4. Please send a PR if you've donated and would like to be listed. * `Stripe <https://stripe.com/>`_ (June 23, 2014) diff --git a/docs/make.bat b/docs/make.bat index 41aa35b9..39061b84 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -95,9 +95,9 @@ if "%1" == "qthelp" ( echo. echo.Build finished; now you can run "qcollectiongenerator" with the ^ .qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\urllib3.qhcp + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\urllib4.qhcp echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\urllib3.ghc + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\urllib4.ghc goto end ) diff --git a/docs/managers.rst b/docs/managers.rst index 6c841b75..cf4d8014 100644 --- a/docs/managers.rst +++ b/docs/managers.rst @@ -1,7 +1,7 @@ PoolManager =========== -.. automodule:: urllib3.poolmanager +.. automodule:: urllib4.poolmanager A pool manager is an abstraction for a collection of :doc:`ConnectionPools <pools>`. @@ -12,7 +12,7 @@ so you don't have to. .. doctest :: - >>> from urllib3 import PoolManager + >>> from urllib4 import PoolManager >>> manager = PoolManager(10) >>> r = manager.request('GET', 'http://example.com') >>> r.headers['server'] @@ -41,7 +41,7 @@ as a context manager. .. doctest :: - >>> from urllib3 import PoolManager + >>> from urllib4 import PoolManager >>> with PoolManager(10) as manager: ... r = manager.request('GET', 'http://example.com') ... r = manager.request('GET', 'http://httpbin.org/') @@ -52,7 +52,7 @@ as a context manager. 0 You can read more about the implementation and the various adjustable variables -within :class:`~urllib3._collections.RecentlyUsedContainer`. +within :class:`~urllib4._collections.RecentlyUsedContainer`. API --- @@ -65,9 +65,9 @@ ProxyManager :class:`.ProxyManager` is an HTTP proxy-aware subclass of :class:`.PoolManager`. It produces a single -:class:`~urllib3.connectionpool.HTTPConnectionPool` instance for all HTTP +:class:`~urllib4.connectionpool.HTTPConnectionPool` instance for all HTTP connections and individual per-server:port -:class:`~urllib3.connectionpool.HTTPSConnectionPool` instances for tunnelled +:class:`~urllib4.connectionpool.HTTPSConnectionPool` instances for tunnelled HTTPS connections. API diff --git a/docs/pools.rst b/docs/pools.rst index 9cc2be9a..cbf46604 100644 --- a/docs/pools.rst +++ b/docs/pools.rst @@ -1,7 +1,7 @@ ConnectionPools =============== -.. automodule:: urllib3.connectionpool +.. automodule:: urllib4.connectionpool A connection pool is a container for a collection of connections to a specific host. @@ -11,10 +11,10 @@ If you need to make requests to the same host repeatedly, then you should use a .. doctest :: - >>> from urllib3 import HTTPConnectionPool + >>> from urllib4 import HTTPConnectionPool >>> pool = HTTPConnectionPool('ajax.googleapis.com', maxsize=1) >>> r = pool.request('GET', '/ajax/services/search/web', - ... fields={'q': 'urllib3', 'v': '1.0'}) + ... fields={'q': 'urllib4', 'v': '1.0'}) >>> r.status 200 >>> r.headers['content-type'] @@ -40,10 +40,10 @@ pool after usage. .. doctest :: - >>> from urllib3 import HTTPConnectionPool + >>> from urllib4 import HTTPConnectionPool >>> with HTTPConnectionPool('ajax.googleapis.com', maxsize=1) as pool: ... r = pool.request('GET', '/ajax/services/search/web', - ... fields={'q': 'urllib3', 'v': '1.0'}) + ... fields={'q': 'urllib4', 'v': '1.0'}) ... print(pool.pool) ... <queue.LifoQueue object at 0x7f67367dfcf8> @@ -61,7 +61,7 @@ ConnectionPools more easily: API --- -:mod:`urllib3.connectionpool` comes with two connection pools: +:mod:`urllib4.connectionpool` comes with two connection pools: .. autoclass:: HTTPConnectionPool :members: @@ -74,12 +74,12 @@ All of these pools inherit from a common base class: .. autoclass:: ConnectionPool -.. module:: urllib3.connection +.. module:: urllib4.connection Related Classes --------------- -urllib3 implements its own :class:`HTTPConnection` object to allow for more +urllib4 implements its own :class:`HTTPConnection` object to allow for more flexibility than the standard library's implementation. .. autoclass:: HTTPConnection diff --git a/docs/security.rst b/docs/security.rst index 881730e7..52bf68d9 100644 --- a/docs/security.rst +++ b/docs/security.rst @@ -3,7 +3,7 @@ Security: Verified HTTPS with SSL/TLS ===================================== -Very important fact: **By default, urllib3 does not verify HTTPS requests.** +Very important fact: **By default, urllib4 does not verify HTTPS requests.** The historic reason for this is that we rely on ``httplib`` for some of the HTTP protocol implementation, and ``httplib`` does not verify requests out of @@ -30,7 +30,7 @@ and you'll need to re-install it. Read for details. Otherwise, if ``ssl`` imported cleanly, then we're ready to setup our certificates: -:ref:`certifi-with-urllib3`. +:ref:`certifi-with-urllib4`. Enabling SSL on Google AppEngine @@ -48,9 +48,9 @@ to `enable using sockets <https://developers.google.com/appengine/docs/python/sockets/>`_. -.. _certifi-with-urllib3: +.. _certifi-with-urllib4: -Using Certifi with urllib3 +Using Certifi with urllib4 -------------------------- `Certifi <http://certifi.io/>`_ is a package which ships with Mozilla's root @@ -62,10 +62,10 @@ certificates for easy programmatic access. 2. Setup your pool to require a certificate and provide the certifi bundle:: - import urllib3 + import urllib4 import certifi - http = urllib3.PoolManager( + http = urllib4.PoolManager( cert_reqs='CERT_REQUIRED', # Force certificate check. ca_certs=certifi.where(), # Path to the Certifi bundle. ) @@ -73,7 +73,7 @@ certificates for easy programmatic access. # You're ready to make verified HTTPS requests. try: r = http.request('GET', 'https://example.com/') - except urllib3.exceptions.SSLError as e: + except urllib4.exceptions.SSLError as e: # Handle incorrect certificate error. ... @@ -94,11 +94,11 @@ For example, on most Linux distributions they're at Once you find your root certificate file:: - import urllib3 + import urllib4 ca_certs = "/etc/ssl/certs/ca-certificates.crt" # Or wherever it lives. - http = urllib3.PoolManager( + http = urllib4.PoolManager( cert_reqs='CERT_REQUIRED', # Force certificate check. ca_certs=ca_certs, # Path to your certificate bundle. ) @@ -106,7 +106,7 @@ Once you find your root certificate file:: # You're ready to make verified HTTPS requests. try: r = http.request('GET', 'https://example.com/') - except urllib3.exceptions.SSLError as e: + except urllib4.exceptions.SSLError as e: # Handle incorrect certificate error. ... @@ -128,15 +128,15 @@ packages:: $ pip install pyopenssl ndg-httpsclient pyasn1 -Once the packages are installed, you can tell urllib3 to switch the ssl backend -to PyOpenSSL with :func:`~urllib3.contrib.pyopenssl.inject_into_urllib3`:: +Once the packages are installed, you can tell urllib4 to switch the ssl backend +to PyOpenSSL with :func:`~urllib4.contrib.pyopenssl.inject_into_urllib4`:: - import urllib3.contrib.pyopenssl - urllib3.contrib.pyopenssl.inject_into_urllib3() + import urllib4.contrib.pyopenssl + urllib4.contrib.pyopenssl.inject_into_urllib4() -Now you can continue using urllib3 as you normally would. +Now you can continue using urllib4 as you normally would. -For more details, check the :mod:`~urllib3.contrib.pyopenssl` module. +For more details, check the :mod:`~urllib4.contrib.pyopenssl` module. .. _insecurerequestwarning: @@ -148,18 +148,18 @@ InsecureRequestWarning Unverified HTTPS requests will trigger a warning via Python's ``warnings`` module:: - urllib3/connectionpool.py:736: InsecureRequestWarning: Unverified HTTPS + urllib4/connectionpool.py:736: InsecureRequestWarning: Unverified HTTPS request is being made. Adding certificate verification is strongly advised. - See: https://urllib3.readthedocs.org/en/latest/security.html + See: https://urllib4.readthedocs.org/en/latest/security.html This would be a great time to enable HTTPS verification: -:ref:`certifi-with-urllib3`. +:ref:`certifi-with-urllib4`. If you know what you're doing and would like to disable this and other warnings, -you can use :func:`~urllib3.disable_warnings`:: +you can use :func:`~urllib4.disable_warnings`:: - import urllib3 - urllib3.disable_warnings() + import urllib4 + urllib4.disable_warnings() Making unverified HTTPS requests is strongly discouraged. ˙ ͜ʟ˙ @@ -178,7 +178,7 @@ InsecurePlatformWarning Certain Python platforms (specifically, versions of Python earlier than 2.7.9) have restrictions in their ``ssl`` module that limit the configuration that -``urllib3`` can apply. In particular, this can cause HTTPS requests that would +``urllib4`` can apply. In particular, this can cause HTTPS requests that would succeed on more featureful platforms to fail, and can cause certain security features to be unavailable. |