fix(app module): Fixed documentation stuff, and renamed a module (#1620)

* Fixes documentation, and renamed api_helpers module

* docs(newsfragments): tweak the API class deprecation note

* docs(newsfragments): rename extension to conform to the Towncrier standard types

* docs(newsfragments): tweak the note even further (remove one "compatibility")

* Changed deprecation class

README.rst

@@ -387,9 +387,9 @@ API.
                          '    ~ Immanuel Kant\n\n')
 
 
-    # falcon.API instances are callable WSGI apps
+    # falcon.App instances are callable WSGI apps
     # in larger applications the app is created in a separate file
-    app = falcon.API()
+    app = falcon.App()
 
     # Resources are represented by long-lived class instances
     things = ThingsResource()
@@ -618,7 +618,7 @@ bodies.
             resp.location = '/%s/things/%s' % (user_id, proper_thing['id'])
 
     # Configure your WSGI server to load "things.app" (app is a WSGI callable)
-    app = falcon.API(middleware=[
+    app = falcon.App(middleware=[
         AuthMiddleware(),
         RequireJSON(),
         JSONTranslator(),

docs/_newsfragments/api_class.removal.rst

@@ -0,0 +1,3 @@
+The ``falcon.API`` class was renamed to ``falcon.App``. The old ``API`` class
+remains available as an alias for backwards-compatibility, but it is now
+considered deprecated and will be removed in a future release.

docs/api/cors.rst

@@ -30,5 +30,5 @@ Usage
     import falcon
 
     # Enable a simple CORS policy for all responses
-    app = falcon.API(cors_enable=True)
+    app = falcon.App(cors_enable=True)
 

examples/look/look/app.py

@@ -7,9 +7,9 @@
 
 def create_app(image_store):
     image_resource = Resource(image_store)
-    api = falcon.API()
-    api.add_route('/images', image_resource)
-    return api
+    app = falcon.App()
+    app.add_route('/images', image_resource)
+    return app
 
 
 def get_app():

examples/things.py

@@ -21,7 +21,7 @@ def on_get(self, req, resp):
 
 # falcon.API instances are callable WSGI apps
 # in larger applications the app is created in a separate file
-app = falcon.API()
+app = falcon.App()
 
 # Resources are represented by long-lived class instances
 things = ThingsResource()

examples/things_advanced.py

@@ -191,7 +191,7 @@ def on_post(self, req, resp, user_id):
 
 
 # Configure your WSGI server to load "things.app" (app is a WSGI callable)
-app = falcon.API(middleware=[
+app = falcon.App(middleware=[
     AuthMiddleware(),
     RequireJSON(),
     JSONTranslator(),

falcon/app.py

@@ -18,7 +18,7 @@
 import re
 import traceback
 
-from falcon import api_helpers as helpers, DEFAULT_MEDIA_TYPE, routing
+from falcon import app_helpers as helpers, DEFAULT_MEDIA_TYPE, routing
 from falcon.http_error import HTTPError
 from falcon.http_status import HTTPStatus
 from falcon.middlewares import CORSMiddleware