PEP 476: improve guidance on opting out

pep-0476.txt

@@ -121,8 +121,9 @@ no opposition.
 Opting out
 ----------
 
-For users who wish to opt out of certificate verification, they can achieve
-this by providing the ``context`` argument to ``urllib.urlopen``::
+For users who wish to opt out of certificate verification on a single
+connection, they can achieve this by providing the ``context`` argument to
+``urllib.urlopen``::
 
     import ssl
 
@@ -130,12 +131,33 @@ this by providing the ``context`` argument to ``urllib.urlopen``::
     context = ssl._create_unverified_context()
     urllib.urlopen("https://no-valid-cert", context=context)
 
-It is also possible **though highly discouraged** to globally disable
-verification by monkeypatching the ``ssl`` module::
+It is also possible, **though highly discouraged**, to globally disable
+verification by monkeypatching the ``ssl`` module in versions of Python that
+implement this PEP::
 
     import ssl
 
-    ssl._create_default_https_context = ssl._create_unverified_context
+    try:
+        _create_unverified_https_context = ssl._create_unverified_context
+    except AttributeError:
+        # Legacy Python that doesn't verify HTTPS certificates by default
+        pass
+    else:
+        # Handle target environment that doesn't support HTTPS verification
+        ssl._create_default_https_context = _create_unverified_https_context
+
+This guidance is aimed primarily at system administrators that wish to adopt
+newer versions of Python that implement this PEP in legacy environments that
+do not yet support certificate verification on HTTPS connections. For
+example, an administrator may opt out by adding the monkeypatch above to
+``sitecustomize.py`` in their Standard Operating Environment for Python.
+Applications and libraries SHOULD NOT be making this change process wide
+(except perhaps in response to a system administrator controlled configuration
+setting).
+
+Particularly security sensitive applications should always provide an explicit
+application defined SSL context rather than relying on the default behaviour
+of the underlying Python implementation.
 
 Other protocols
 ===============