Merge pull request #739 from kgriffs/release-notes-1.0.0

doc(Changelogs): Add Changelog for 1.0.0 and prepare docs for release

README.rst

@@ -1,5 +1,5 @@
 Falcon |Docs| |Build Status| |codecov.io|
-==================================
+=========================================
 
     Perfection is finally attained not when there is no longer anything
     to add, but when there is no longer anything to take away.

doc/api/status.rst

@@ -29,7 +29,7 @@ handling. It takes status, additional headers and body as input arguments.
 HTTPStatus
 ----------
 
-.. autoclass:: falcon.http_status.HTTPStatus
+.. autoclass:: falcon.HTTPStatus
     :members:
 
 

doc/changes/0.2.0.rst

@@ -1,8 +1,23 @@
 Changelog for Falcon 0.2.0
 ==========================
 
-New
----
+Breaking Changes
+----------------
+
+-  The deprecated util.misc.percent\_escape and
+   util.misc.percent\_unescape functions were removed. Please use the
+   functions in the util.uri module instead.
+-  The deprecated function, API.set\_default\_route, was removed. Please
+   use sinks instead.
+-  HTTPRangeNotSatisfiable no longer accepts a media\_type parameter.
+-  When using the comma-delimited list convention,
+   req.get\_param\_as\_list(...) will no longer insert placeholders,
+   using the None type, for empty elements. For example, where
+   previously the query string "foo=1,,3" would result in ['1', None,
+   '3'], it will now result in ['1', '3'].
+
+New & Improved
+--------------
 
 -  Since 0.1 we've added proper RTD docs to make it easier for everyone
    to get started with the framework. Over time we will continue adding
@@ -64,21 +79,6 @@ New
 -  Python 3.4 is now fully supported.
 -  Various minor performance improvements
 
-Breaking Changes
-----------------
-
--  The deprecated util.misc.percent\_escape and
-   util.misc.percent\_unescape functions were removed. Please use the
-   functions in the util.uri module instead.
--  The deprecated function, API.set\_default\_route, was removed. Please
-   use sinks instead.
--  HTTPRangeNotSatisfiable no longer accepts a media\_type parameter.
--  When using the comma-delimited list convention,
-   req.get\_param\_as\_list(...) will no longer insert placeholders,
-   using the None type, for empty elements. For example, where
-   previously the query string "foo=1,,3" would result in ['1', None,
-   '3'], it will now result in ['1', '3'].
-
 Fixed
 -----
 
@@ -97,4 +97,4 @@ Fixed
    submitted by the client, wsgiref will set the value of that header to
    an empty string in the WSGI environ.
 -  Resolved an issue causing several source files to not be Cythonized.
--  Docstrings have been edited for clarity and correctness.
+-  Docstrings have been edited for clarity and correctness.

doc/changes/0.3.0.rst

@@ -1,8 +1,13 @@
 Changelog for Falcon 0.3.0
 ==========================
 
-New
----
+Breaking Changes
+----------------
+- Date headers are now returned as :py:class:`datetime.datetime` objects
+  instead of strings.
+
+New & Improved
+--------------
 
 - This release includes a new router architecture for improved performance
   and flexibility.
@@ -23,11 +28,6 @@ New
   :py:attr:`falcon.HTTP_NO_CONTENT` vs. :py:attr:`falcon.HTTP_204`.)
 - Several minor performance optimizations were made to the code base.
 
-Breaking Changes
-----------------
-- Date headers are now returned as :py:class:`datetime.datetime` objects
-  instead of strings.
-
 Fixed
 -----
 
@@ -36,4 +36,4 @@ Fixed
 - Several errors in the documentation were corrected.
 - The :py:mod:`six` package was pinned to 1.4.0 or better.
   :py:attr:`six.PY2` is required by Falcon, but that wasn't added to
-  :py:mod:`six` until version 1.4.0.
+  :py:mod:`six` until version 1.4.0.

doc/changes/1.0.0.rst

@@ -0,0 +1,147 @@
+Changelog for Falcon 1.0.0
+==========================
+
+Breaking Changes
+----------------
+- The deprecated global hooks feature has been removed.
+  :class:`~falcon.API` no longer accepts `before` and `after`
+  kwargs. Applications can work around this by migrating any logic
+  contained in global hooks to reside in middleware components instead.
+- The middleware method :meth:`process_resource` must now accept
+  an additional `params` argument. This gives the middleware method an
+  opportunity to interact with the values for any fields defined in a
+  route's URI template.
+- The middleware method :meth:`process_resource` is now skipped when
+  no route is found for the incoming request. This avoids having to
+  include an ``if resource is not None`` check when implementing this
+  method. A sink may be used instead to execute logic in the case that
+  no route is found.
+- An option was added to toggle automatic parsing of form params. Falcon
+  will no longer automatically parse, by default, requests that have the
+  content type "application/x-www-form-urlencoded". This was done to
+  avoid unintended side-effects that may arise from consuming the
+  request stream. It also makes it more straightforward for applications
+  to customize and extend the handling of form submissions. Applications
+  that require this functionality must re-enable it explicitly, by
+  setting a new request option that was added for that purpose, per the
+  example below::
+
+        app = falcon.API()
+        app.req_options.auto_parse_form_urlencoded = True
+
+- The performance of composing the response body was
+  improved. As part of this work, the :attr:`Response.body_encoded`
+  attribute was removed. This property was only intended to be used by
+  the framework itself, but any dependent code can be migrated per
+  the example below::
+
+    # Before
+    body = resp.body_encoded
+
+    # After
+    if resp.body:
+        body = resp.body.encode('utf-8')
+    else:
+        body = b''
+
+New & Improved
+--------------
+
+- A `code of conduct <https://github.com/falconry/falcon/blob/master/CODEOFCONDUCT.md>`_
+  was added to solidify our community's commitment to sustaining a
+  welcoming, respectful culture.
+- CPython 3.5 is now fully supported.
+- The constants HTTP_422, HTTP_428, HTTP_429, HTTP_431, HTTP_451, and
+  HTTP_511 were added.
+- The :class:`~falcon.HTTPUnprocessableEntity`,
+  :class:`~falcon.HTTPTooManyRequests`, and
+  :class:`~falcon.HTTPUnavailableForLegalReasons` error classes were
+  added.
+- The :any:`HTTPStatus` class is now available directly under
+  the `falcon` module, and has been properly documented.
+- Support for HTTP redirections was added via a set of
+  :any:`HTTPStatus` subclasses. This should avoid the problem
+  of hooks and responder methods possibly overriding the redirect.
+  Raising an instance of one of these new redirection classes will
+  short-circuit request processing, similar to raising an instance of
+  :class:`~falcon.HTTPError`.
+- The default 404 responder now raises an instance of
+  :class:`~falcon.HTTPError` instead of manipulating the
+  response object directly. This makes it possible to customize the
+  response body using a custom error handler or serializer.
+- A new method, :meth:`~falcon.Response.get_header`, was added to
+  :class:`~falcon.Response`. Previously there was no way to check if a
+  header had been set. The new :meth:`~falcon.Response.get_header`
+  method facilitates this and other use cases.
+- :meth:`falcon.Request.client_accepts_msgpack` now recognizes
+  "application/msgpack", in addition to "application/x-msgpack".
+- The :any:`access_route` and
+  :any:`remote_addr` properties were added to
+  :class:`~falcon.Request` for getting upstream IP addresses.
+- :class:`~falcon.Request` and :class:`~falcon.Response` now support
+  range units other than bytes.
+- The `API` and `srmock` class types can now be customized in
+  :class:`~falcon.testing.TestBase`.
+- Path segments with multiple field expressions may now be defined at
+  the same level as path segments having only a single field
+  expression. For example::
+
+    api.add_route('/files/{file_id}', resource_1)
+    api.add_route('/files/{file_id}.{ext}', resource_2)
+
+- Support was added to :any:`API.add_route()` for passing through
+  additional args and kwargs to custom routers.
+- Digits and the underscore character are now allowed in the
+  :meth:`falcon.routing.compile_uri_template` helper, for use in custom
+  router implementations.
+- A new testing framework was added that should be more intuitive to
+  use than the old one. Several of Falcon's own tests were ported to use
+  the new framework (the remainder to be ported in a
+  subsequent release.) The new testing framework performs wsgiref
+  validation on all requests.
+- The performance of setting :attr:`Response.content_range` was
+  improved by ~50%.
+- A new param, `obs_date`, was added to
+  :meth:`falcon.Request.get_header_as_datetime`, and defaults to
+  ``False``. This improves the method's performance when obsolete date
+  formats do not need to be supported.
+
+Fixed
+-----
+
+- Field expressions at a given level in the routing tree no longer
+  mask alternative branches. When a single segment in a requested path
+  can match more than one node at that branch in the routing tree, and
+  the first branch taken happens to be the wrong one (i.e., the
+  subsequent nodes do not match, but they would have under a different
+  branch), the other branches that could result in a
+  successful resolution of the requested path will now be subsequently
+  tried, whereas previously the framework would behave as if no route
+  could be found.
+- The user agent is now instructed to expire the cookie when it is
+  cleared via :meth:`~falcon.Response.unset_cookie`.
+- Support was added for hooks that have been defined via
+  :meth:`functools.partial`.
+- Tunneled UTF-8 characters in the request path are now properly
+  decoded, and a placeholder character is substituted for any invalid
+  code points.
+- The instantiation of :any:`Request.context_type` is now
+  delayed until after all other properties of the
+  :class:`~falcon.Request` class have been initialized, in case the
+  context type's own initialization depends on any of
+  :class:`~falcon.Request`'s properties.
+- A case was fixed in which reading from :any:`Request.stream`
+  could hang when using :mod:`wsgiref` to host the app.
+- The default error serializer now sets the Vary header in responses.
+  Implementing this required passing the :class:`~falcon.Response`
+  object to the serializer, which would normally be a breaking change.
+  However, the framework was modified to detect old-style error
+  serializers and wrap them with a shim to make them compatible with
+  the new interface.
+- A query string containing malformed percent-encoding no longer causes
+  the framework to raise an error.
+- Additional tests were added for a few lines of code that were
+  previously not covered, due to deficiencies in code coverage reporting
+  that have since been corrected.
+- The Cython note is no longer displayed when installing under Jython.
+- Several errors and ambiguities in the documentation were corrected.

doc/changes/index.rst

@@ -3,5 +3,6 @@ Changelogs
 
 .. toctree::
 
+   1.0.0 <1.0.0>
    0.3.0 <0.3.0>
-   0.2.0 <0.2.0>
+   0.2.0 <0.2.0>

doc/conf.py

@@ -55,16 +55,16 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Falcon'
-copyright = u'2015, Rackspace Hosting et al. (as noted in the source code)'
+copyright = u'2016, Rackspace Hosting et al. (as noted in the source code)'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.4'
+version = '1.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.4.0'
+release = '1.0.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/index.rst

@@ -8,10 +8,6 @@ The Falcon Web Framework
 
 Release v\ |version| (:ref:`Installation <install>`)
 
-.. note::
-
-  This documentation targets the upcoming |version| release of Falcon.
-
 Falcon is a minimalist WSGI library for building speedy web APIs and app
 backends. We like to think of Falcon as the `Dieter Rams` of web frameworks.
 

falcon/api.py

@@ -293,6 +293,13 @@ class API(object):
                 corresponding request handlers, and Falcon will do the right
                 thing.
 
+        Note:
+            Any additional args and kwargs not defined above are passed
+            through to the underlying router's ``add_route()`` method. The
+            default router does not expect any additional arguments, but
+            custom routers may take advantage of this feature to receive
+            additional options when setting up routes.
+
         """
 
         # NOTE(richardolsson): Doing the validation here means it doesn't have