Pyramid TODOs
=============

Must-Have (before 1.0)
----------------------

- Narrative docs for ``Configurator.include`` and ``Configurator.commit``.

- Fix session behavior: when a Forbidden/NotFound hander is invoked, we'd
  like to allow people to save the session (currently when the response has
  an exception attribute, the session is tossed unconditionally).

- Provide a .flash API on session object.

- Use ``@register_view`` instead of ``@view_config`` and change view docs to
  use "view registration" instead of "view configuration".

- Change references to "model" to references to "resource" in all docs (and
  alias model_url to resource_url, etc).

Should-Have
-----------

- Add docs for httpexceptions module for each webob.exc class that inherits
  from WSGIHTTPException.

- Remove "BFG" from Pyramid-specific environ variables.

- translationdir ZCML directive use of ``path_spec`` should maybe die.

- Add CRSF token creation/checking machinery (only "should have" vs. "must
  have" because I'm not sure it belongs in Pyramid.. it definitely must exist
  in formgen libraries, and *might* belong in Pyramid).

- Change "Cleaning up After a Request" in the urldispatch chapter to
  use ``request.add_response_callback``.

Nice-to-Have
------------

- Try to make test suite pass on IronPython.

- Non-bwcompat use of threadlocals that need to be documented or ameliorated:

  security.principals_allowed_by_permission

  resource.OverrideProvider._get_overrides: can't credibly be removed,
  because it stores an overrideprovider as a module-scope global.

  traversal.traverse: this API is a stepchild, and needs to be changed.

  Configurator.add_translation_dirs: not passed any context but a message,
  can't credibly be removed.

- Supply ``X-Vhm-Host`` support.

- Basic WSGI documentation (pipeline / app / server).

- Fix message catalog extraction / compilation documentation.

- Change docs about creating a venusian decorator to not use ZCA.

- ``decorator=`` parameter to view_config.  This would replace the existing
  _map_view "decorator" if it existed.

- Try to better explain the relationship between a renderer and a
  template in the templates chapter and elsewhere.  Scan the
  documentation for reference to a renderer as *only* view
  configuration (it's a larger concept now).

- Create a ``render_view`` that works by using config.derive_view
  against an existing view instead of querying the registry.

- Create a function which performs a recursive request.

- Debug option to print route matching decision.

- Debug option to print view matching decision.

- Script or paster command that prints, for a given URL, the views
  that might match.  Underneath each potentially matching route, list
  the predicates required.  Underneath each route+predicate set, print
  each view that might match and its predicates.  E.g. with the input
  URL ``/foo``::

    '/foo' (foo_xhr)
       xhr = True
         (no view predicates)
           mypackage.views.MyXHRFooView.__call__

    '/{action}' (action_route)
       request_method = 'POST'
         action = '^foo$'
           mypackage.views.MyView.foo_POST
       request_method = 'GET'
         action = '^foo$'
           mypackage.views.MyView.foo_GET

- Provide a response_cookies attribute on the request for rendered
  responses that can be used as input to response.set_cookie.

- Raise an exception when a value in response_headerlist is not a
  string or decide to encode.

- Update App engine chapter with less creaky directions.

- Add functionality that mocks the behavior of ``repoze.browserid``.

- One way to split up views chapter: views with renderers / views without
  renderers.
