give urllib.urlopen a context parameter (closes #22927)

1 files changed, 14 insertions, 4 deletions

diff --git a/Doc/library/urllib.rst b/Doc/library/urllib.rst
index 62f198f..b2a817d 100644
--- a/Doc/library/urllib.rst
+++ b/Doc/library/urllib.rst
@@ -31,7 +31,7 @@ reading, and no seek operations are available.
 High-level interface
 --------------------
 
-.. function:: urlopen(url[, data[, proxies]])
+.. function:: urlopen(url[, data[, proxies[, context]]])
 
    Open a network object denoted by a URL for reading.  If the URL does not
    have a scheme identifier, or if it has :file:`file:` as its scheme
@@ -122,8 +122,12 @@ High-level interface
       filehandle = urllib.urlopen(some_url, proxies=None)
       filehandle = urllib.urlopen(some_url)
 
-   Proxies which require authentication for use are not currently supported; this
-   is considered an implementation limitation.
+   Proxies which require authentication for use are not currently supported;
+   this is considered an implementation limitation.
+
+   The *context* parameter may be set to a :class:`ssl.SSLContext` instance to
+   configure the SSL settings that are used if :func:`urlopen` makes a HTTPS
+   connection.
 
    .. versionchanged:: 2.3
       Added the *proxies* support.
@@ -132,6 +136,9 @@ High-level interface
       Added :meth:`getcode` to returned object and support for the
       :envvar:`no_proxy` environment variable.
 
+   .. versionchanged:: 2.7.9
+      The *context* parameter was added.
+
    .. deprecated:: 2.6
       The :func:`urlopen` function has been removed in Python 3 in favor
       of :func:`urllib2.urlopen`.
@@ -292,7 +299,7 @@ Utility functions
 URL Opener objects
 ------------------
 
-.. class:: URLopener([proxies[, **x509]])
+.. class:: URLopener([proxies[, context[, **x509]]])
 
    Base class for opening and reading URLs.  Unless you need to support opening
    objects using schemes other than :file:`http:`, :file:`ftp:`, or :file:`file:`,
@@ -309,6 +316,9 @@ URL Opener objects
    value is ``None``, in which case environmental proxy settings will be used if
    present, as discussed in the definition of :func:`urlopen`, above.
 
+   The *context* parameter may be a :class:`ssl.SSLContext` instance.  If given,
+   it defines the SSL settings the opener uses to make HTTPS connections.
+
    Additional keyword parameters, collected in *x509*, may be used for
    authentication of the client when using the :file:`https:` scheme.  The keywords
    *key_file* and *cert_file* are supported to provide an  SSL key and certificate;