From 19919b44c4af95f125704c902acecdf83d70a3e4 Mon Sep 17 00:00:00 2001
From: Zane Bitter <zbitter@redhat.com>
Date: Tue, 21 Nov 2017 12:39:22 -0500
Subject: [PATCH] Add documentation for available status codes

There was no way to determine what actual names were available outside
of looking at the source code. They were not listed in the documentation
or accessible through the interactive help.

In addition, doing `pydoc requests.status_codes` displayed some pretty
unhelpful information - the utf-8 encoding string was included in the
module name, there was no description, and internal variables used for
initialisation leaked into the module scope:

    DATA
        code = 511
        codes = <lookup 'status_codes'>
        title = 'network_authentication'
        titles = ('network_authentication_required', 'network_auth', ...

This change prevents the internal variables from leaking, adds a
docstring (which has the side-effect of correcting the module name), and
appends information on the allowed status code names to the docstring
when the module is initialised.

The improved module documentation is then used in the API documentation
to provide another easy reference to the complete list of status codes.
---
 docs/api.rst             | 12 +-----------
 requests/status_codes.py | 38 +++++++++++++++++++++++++++++++++-----
 2 files changed, 34 insertions(+), 16 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index ed61bb38..c3e00e54 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -109,17 +109,7 @@ Status Code Lookup
 
 .. autoclass:: requests.codes
 
-::
-
-    >>> requests.codes['temporary_redirect']
-    307
-
-    >>> requests.codes.teapot
-    418
-
-    >>> requests.codes['\o/']
-    200
-
+.. automodule:: requests.status_codes
 
 
 Migrating to 1.x
diff --git a/requests/status_codes.py b/requests/status_codes.py
index dee89190..96b86ddb 100644
--- a/requests/status_codes.py
+++ b/requests/status_codes.py
@@ -1,5 +1,22 @@
 # -*- coding: utf-8 -*-
 
+"""
+The ``codes`` object defines a mapping from common names for HTTP statuses
+to their numerical codes, accessible either as attributes or as dictionary
+items.
+
+>>> requests.codes['temporary_redirect']
+307
+>>> requests.codes.teapot
+418
+>>> requests.codes['\o/']
+200
+
+Some codes have multiple names, and both upper- and lower-case versions of
+the names are allowed. For example, ``codes.ok``, ``codes.OK``, and
+``codes.okay`` all correspond to the HTTP status code 200.
+"""
+
 from .structures import LookupDict
 
 _codes = {
@@ -84,8 +101,19 @@ _codes = {
 
 codes = LookupDict(name='status_codes')
 
-for code, titles in _codes.items():
-    for title in titles:
-        setattr(codes, title, code)
-        if not title.startswith(('\\', '/')):
-            setattr(codes, title.upper(), code)
+def _init():
+    for code, titles in _codes.items():
+        for title in titles:
+            setattr(codes, title, code)
+            if not title.startswith(('\\', '/')):
+                setattr(codes, title.upper(), code)
+
+    def doc(code):
+        names = ', '.join('``%s``' % n for n in _codes[code])
+        return '* %d: %s' % (code, names)
+
+    global __doc__
+    __doc__ = (__doc__ + '\n' +
+               '\n'.join(doc(code) for code in sorted(_codes)))
+
+_init()