better headings

$ python -m requests.help

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,28 @@
+Summary.
+
+## Expected Result
+
+What you expected.
+
+## Actual Result
+
+What happened instead.
+
+## Reproduction Steps
+
+```python
+import requests
+
+```
+
+## System Information
+
+    $ python -m requests.help
+
+```
+<paste here>
+```
+
+This command is only available on Requests v2.16.4 and greater. Otherwise,
+please provide some basic information about your system (Python version,
+operating system, &c).

HISTORY.rst

@@ -3,6 +3,46 @@
 Release History
 ---------------
 
+2.16.4 (2017-05-27)
++++++++++++++++++++
+
+- Introduction of the ``$ python -m requests.help`` command, for debugging with maintainers!
+
+2.16.3 (2017-05-27)
++++++++++++++++++++
+
+- Further restored the ``requests.packages`` namespace for compatibility reasons.
+
+2.16.2 (2017-05-27)
++++++++++++++++++++
+
+- Further restored the ``requests.packages`` namespace for compatibility reasons.
+
+No code modification (noted below) should be neccessary any longer.
+
+2.16.1 (2017-05-27)
++++++++++++++++++++
+
+- Restored the ``requests.packages`` namespace for compatibility reasons.
+- Bugfix for ``urllib3`` version parsing.
+
+**Note**: code that was written to import against the ``requests.packages``
+namespace previously will have to import code that rests at this module-level
+now.
+
+For example::
+
+    from requests.packages.urllib3.poolmanager import PoolManager
+
+Will need to be re-written to be::
+
+    from requests.packages import urllib3
+    urllib3.poolmanager.PoolManager
+
+Or, even better::
+
+    from urllib3.poolmanager import PoolManager
+
 2.16.0 (2017-05-26)
 +++++++++++++++++++
 

README.rst

@@ -57,8 +57,7 @@ See `the similar code, sans Requests <https://gist.github.com/973705>`_.
 Requests allows you to send *organic, grass-fed* HTTP/1.1 requests, without the
 need for manual labor. There's no need to manually add query strings to your
 URLs, or to form-encode your POST data. Keep-alive and HTTP connection pooling
-are 100% automatic, powered by `urllib3 <https://github.com/shazow/urllib3>`_,
-which is embedded within Requests.
+are 100% automatic, thanks to `urllib3 <https://github.com/shazow/urllib3>`_.
 
 Besides, all the cool kids are doing it. Requests is one of the most
 downloaded Python packages of all time, pulling in over 11,000,000 downloads

docs/index.rst

@@ -57,8 +57,7 @@ See `similar code, sans Requests <https://gist.github.com/973705>`_.
 **Requests** allows you to send *organic, grass-fed* HTTP/1.1 requests, without the
 need for manual labor. There's no need to manually add query strings to your
 URLs, or to form-encode your POST data. Keep-alive and HTTP connection pooling
-are 100% automatic, powered by `urllib3 <https://github.com/shazow/urllib3>`_,
-which is embedded within Requests.
+are 100% automatic, thanks to `urllib3 <https://github.com/shazow/urllib3>`_.
 
 User Testimonials
 -----------------

requests/__init__.py

@@ -46,7 +46,11 @@ from .__version__ import __copyright__, __cake__
 
 # Check urllib3 for compatibility.
 import urllib3
-major, minor, patch = urllib3.__version__.split('.')[:3]
+urllib3_version = urllib3.__version__.split('.')
+# Sometimes, urllib3 only reports its version as 16.1.
+if len(urllib3_version) == 2:
+    urllib3_version.append('0')
+major, minor, patch = urllib3_version
 major, minor, patch = int(major), int(minor), int(patch)
 # urllib3 >= 1.21.1, < 1.22
 try:
@@ -83,6 +87,7 @@ from urllib3.exceptions import DependencyWarning
 warnings.simplefilter('ignore', DependencyWarning)
 
 from . import utils
+from . import packages
 from .models import Request, Response, PreparedRequest
 from .api import request, get, head, post, patch, put, delete, options
 from .sessions import session, Session

requests/__version__.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 # .-. .-. .-. . . .-. .-. .-. .-.
 # |(  |-  |.| | | |-  `-.  |  `-.
 # ' ' `-' `-`.`-' `-' `-'  '  `-'
@@ -7,10 +5,12 @@
 __title__ = 'requests'
 __description__ = 'Python HTTP for Humans.'
 __url__ = 'http://python-requests.org'
-__version__ = '2.16.0'
-__build__ = 0x021600
+__version__ = '2.16.4'
+__build__ = 0x021604
 __author__ = 'Kenneth Reitz'
 __author_email__ = 'me@kennethreitz.org'
 __license__ = 'Apache 2.0'
 __copyright__ = 'Copyright 2017 Kenneth Reitz'
-__cake__ = u'✨ 🍰 ✨'
+__cake__ = u'\u2728 \U0001f370 \u2728'
+
+

requests/help.py

@@ -0,0 +1,110 @@
+"""Module containing bug report helper(s)."""
+from __future__ import print_function
+
+import json
+import platform
+import sys
+import ssl
+
+import urllib3
+import chardet
+
+from . import __version__ as requests_version
+
+try:
+    from .packages.urllib3.contrib import pyopenssl
+except ImportError:
+    pyopenssl = None
+    OpenSSL = None
+    cryptography = None
+else:
+    import OpenSSL
+    import cryptography
+
+
+def _implementation():
+    """Return a dict with the Python implementation and verison.
+
+    Provide both the name and the version of the Python implementation
+    currently running. For example, on CPython 2.7.5 it will return
+    {'name': 'CPython', 'version': '2.7.5'}.
+
+    This function works best on CPython and PyPy: in particular, it probably
+    doesn't work for Jython or IronPython. Future investigation should be done
+    to work out the correct shape of the code for those platforms.
+    """
+    implementation = platform.python_implementation()
+
+    if implementation == 'CPython':
+        implementation_version = platform.python_version()
+    elif implementation == 'PyPy':
+        implementation_version = '%s.%s.%s' % (sys.pypy_version_info.major,
+                                               sys.pypy_version_info.minor,
+                                               sys.pypy_version_info.micro)
+        if sys.pypy_version_info.releaselevel != 'final':
+            implementation_version = ''.join([
+                implementation_version, sys.pypy_version_info.releaselevel
+                ])
+    elif implementation == 'Jython':
+        implementation_version = platform.python_version()  # Complete Guess
+    elif implementation == 'IronPython':
+        implementation_version = platform.python_version()  # Complete Guess
+    else:
+        implementation_version = 'Unknown'
+
+    return {'name': implementation, 'version': implementation_version}
+
+
+def info():
+    """Generate information for a bug report."""
+    try:
+        platform_info = {
+            'system': platform.system(),
+            'release': platform.release(),
+        }
+    except IOError:
+        platform_info = {
+            'system': 'Unknown',
+            'release': 'Unknown',
+        }
+
+    implementation_info = _implementation()
+    urllib3_info = urllib3.__version__
+    chardet_info = chardet.__version__
+
+    pyopenssl_info = {
+        'version': None,
+        'openssl_version': '',
+    }
+    if OpenSSL:
+        pyopenssl_info = {
+            'version': OpenSSL.__version__,
+            'openssl_version': '%x' % OpenSSL.SSL.OPENSSL_VERSION_NUMBER,
+        }
+    cryptography_info = {
+        'version': getattr(cryptography, '__version__', ''),
+    }
+
+    return {
+        'platform': platform_info,
+        'implementation': implementation_info,
+        'system_ssl': {
+            'version': '%x' % ssl.OPENSSL_VERSION_NUMBER,
+        },
+        'using_pyopenssl': pyopenssl is not None,
+        'pyOpenSSL': pyopenssl_info,
+        'urllib3': urllib3_info,
+        'chardet': chardet_info,
+        'cryptography': cryptography_info,
+        'requests': {
+            'version': requests_version,
+        },
+    }
+
+def main():
+    """Pretty-print the bug information as JSON."""
+    print(json.dumps(info(), sort_keys=True, indent=2))
+
+if __name__ == '__main__':
+    main()
+

requests/packages.py

@@ -0,0 +1,15 @@
+import sys
+
+# This code exists for backwards compatibility reasons.
+# I don't like it either. Just look the other way. :)
+
+import urllib3
+sys.modules['requests.packages.urllib3'] = urllib3
+
+import idna
+sys.modules['requests.packages.idna'] = idna
+
+import chardet
+sys.modules['requests.packages.chardet'] = chardet
+
+# Kinda cool, though, right?

setup.py

@@ -47,7 +47,7 @@ requires = [
 test_requirements = ['pytest>=2.8.0', 'pytest-httpbin==0.0.7', 'pytest-cov', 'pytest-mock']
 
 about = {}
-with open(os.path.join(here, 'requests', '__version__.py')) as f:
+with open(os.path.join(here, 'requests', '__version__.py'), 'r', 'utf-8') as f:
     exec(f.read(), about)
 
 with open('README.rst', 'r', 'utf-8') as f:

tests/test_requests.py

@@ -65,6 +65,8 @@ class TestRequests:
         requests.put
         requests.patch
         requests.post
+        # Not really an entry point, but people rely on it.
+        from requests.packages.urllib3.poolmanager import PoolManager
 
     @pytest.mark.parametrize(
         'exception, url', (