doc: Add package and module docstrings for use in help() (#850)

Co-Authored-By: Kurt Griffiths <inbox@kgriffs.com>

falcon/__init__.py

@@ -12,6 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Primary package for Falcon, the minimalist WSGI library.
+
+Falcon is a minimalist WSGI library for building speedy web APIs and app
+backends. The `falcon` package can be used to directly access most of
+the framework's classes, functions, and variables::
+
+    import falcon
+
+    app = falcon.API()
+
+"""
+
 HTTP_METHODS = (
     'CONNECT',
     'DELETE',

falcon/api.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Falcon API class."""
+
 import inspect
 import re
 

falcon/api_helpers.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Utilities for the API class."""
+
 from falcon import util
 
 

falcon/errors.py

@@ -12,6 +12,29 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""HTTP error classes.
+
+This module implements a collection of `falcon.HTTPError`
+specializations that can be raised to generate a 4xx or 5xx HTTP
+response. All classes are available directly from the `falcon`
+package namespace::
+
+    import falcon
+
+    class MessageResource(object):
+        def on_get(self, req, resp):
+
+            # ...
+
+            raise falcon.HTTPBadRequest(
+                'TTL Out of Range',
+                'The message's TTL must be between 60 and 300 seconds, inclusive.'
+            )
+
+            # ...
+
+"""
+
 from datetime import datetime
 
 from falcon import util

falcon/hooks.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Hook decorators."""
+
 import functools
 from functools import wraps
 import inspect

falcon/http_error.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""HTTPError exception class."""
+
 import json
 import xml.etree.ElementTree as et
 

falcon/http_status.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""HTTPStatus exception class."""
+
 
 class HTTPStatus(Exception):
     """Represents a generic HTTP status.

falcon/redirects.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""HTTPStatus specializations for 3xx redirects."""
+
 import falcon
 from falcon.http_status import HTTPStatus
 

falcon/request.py

@@ -10,6 +10,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Request class."""
+
 from datetime import datetime
 import json
 

falcon/request_helpers.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Utilities for the Request class."""
+
 
 def header_property(wsgi_name):
     """Creates a read-only header property.

falcon/responders.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Default responder implementations."""
+
 from falcon.errors import HTTPBadRequest
 from falcon.errors import HTTPNotFound
 from falcon.status_codes import HTTP_204

falcon/response.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Response class."""
+
 from six import PY2
 from six import string_types as STRING_TYPES
 

falcon/response_helpers.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Utilities for the Response class."""
+
 
 def header_property(name, doc, transform=None):
     """Creates a header getter/setter.

falcon/routing/__init__.py

@@ -12,6 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Default router and utility functions.
+
+This package implements Falcon's default routing engine, and also
+includes utility functions to aid in the implementation of custom
+routers.
+"""
+
 from falcon.routing.compiled import CompiledRouter
 from falcon.routing.util import create_http_method_map  # NOQA
 from falcon.routing.util import compile_uri_template  # NOQA

falcon/routing/compiled.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Default routing engine."""
+
 import keyword
 import re
 

falcon/routing/util.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Routing utilities."""
+
 import re
 
 import six

falcon/status_codes.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""HTTP status line constants."""
 
 HTTP_100 = '100 Continue'
 HTTP_CONTINUE = HTTP_100

falcon/testing/__init__.py

@@ -12,6 +12,29 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Testing utilities.
+
+This package contains various test classes and utility functions to
+support functional testing for both Falcon-based apps and the Falcon
+framework itself::
+
+    from falcon import testing
+    from myapp import app
+
+    class TestMyApp(testing.TestCase):
+        def setUp(self):
+            super(TestMyApp, self).setUp()
+            self.api = app.create_api()
+
+    def test_get_message(self):
+        doc = {u'message': u'Hello world!'}
+
+        result = self.simulate_get('/messages/42')
+        self.assertEqual(result.json, doc)
+
+For additional examples, see also Falcon's own test suite.
+"""
+
 # Hoist classes and functions into the falcon.testing namespace
 from falcon.testing.base import TestBase  # NOQA
 from falcon.testing.helpers import *  # NOQA

falcon/testing/base.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Test case base class (deprecated)."""
+
 import itertools
 
 try:

falcon/testing/helpers.py

@@ -12,6 +12,17 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Testing utilities.
+
+This module contains various testing utilities that can be accessed
+directly from the `testing` package::
+
+    from falcon import testing
+
+    wsgi_environ = testing.create_environ()
+
+"""
+
 import cgi
 import io
 import random

falcon/testing/resource.py

@@ -12,6 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Mock resource classes.
+
+This module contains mock resource classes and associated hooks for use
+in Falcon framework tests. The classes and hooks may be referenced
+directly from the `testing` package::
+
+    from falcon import testing
+
+    resource = testing.SimpleTestResource()
+
+"""
+
 from json import dumps as json_dumps
 
 import falcon

falcon/testing/srmock.py

@@ -12,6 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""WSGI start_response mock.
+
+This module implements a callable StartResponseMock class that can be
+used, along with a mock environ dict, to simulate a WSGI request.
+"""
+
 from falcon import util
 
 

falcon/testing/test_case.py

@@ -12,6 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""unittest-style base class and utilities for test cases.
+
+This package includes a unittest-style base class and requests-like
+utilities for simulating and validating HTTP requests.
+"""
+
 import json
 import wsgiref.validate
 

falcon/util/__init__.py

@@ -1,3 +1,25 @@
+"""General utilities.
+
+This package includes multiple modules that implement utility functions
+and classes that are useful to both apps and the Falcon framework
+itself.
+
+All utilities in the `structures`, `misc`, and `time` modules are
+imported directly into the front-door `falcon` module for convenience::
+
+    import falcon
+
+    now = falcon.http_now()
+
+Conversely, the `uri` module must be imported explicitly::
+
+    from falcon.util import uri
+
+    some_uri = '...'
+    decoded_uri = uri.decode(some_uri)
+
+"""
+
 # Hoist misc. utils
 from falcon.util import structures
 from falcon.util.misc import *  # NOQA

falcon/util/misc.py

@@ -12,6 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Miscellaneous utilities.
+
+This module provides misc. utility functions for apps and the Falcon
+framework itself. These functions are hoisted into the front-door
+`falcon` module for convenience::
+
+    import falcon
+
+    now = falcon.http_now()
+
+"""
+
 import datetime
 import functools
 import inspect

falcon/util/structures.py

@@ -14,6 +14,19 @@
 #    See the License for the specific language governing permissions and
 #    limitations under the License.
 
+
+"""Data structures.
+
+This module provides additional data structures not found in the
+standard library. These classes are hoisted into the `falcon` module
+for convenience::
+
+    import falcon
+
+    things = falcon.CaseInsensitiveDict()
+
+"""
+
 import collections
 
 

falcon/util/time.py

@@ -1,3 +1,15 @@
+"""Time and date utilities.
+
+This module provides utility functions and classes for dealing with
+times and dates. These functions are hoisted into the `falcon` module
+for convenience::
+
+    import falcon
+
+    tz = falcon.TimezoneGMT()
+
+"""
+
 import datetime
 
 

falcon/util/uri.py

@@ -12,6 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""URI utilities.
+
+This module provides utility functions to parse, encode, decode, and
+otherwise manipulate a URI. These functions are not available directly
+in the `falcon` module, and so must be explicitly imported::
+
+    from falcon import uri
+
+    name, port = uri.parse_host('example.org:8080')
+
+"""
+
 import six
 
 # NOTE(kgriffs): See also RFC 3986

falcon/version.py

@@ -12,5 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Falcon version."""
+
 __version__ = '1.1.0'
 """Current version of Falcon."""