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

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

- Add a ``handler`` ZCML directive.  This implies some slightly dicey
  refactoring of the configurator to allow it to generate ZCML
  "discriminators" for views and routes, that could be implemented in terms
  of "twophase configuration" in "should have" below.

- Provide a .flash API on session object.

- Make default renderer work (renderer registered with no name, which is
  active for every view unless the view names a specific renderer).

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

- SQLAlchemy idiomatics:

   <RaFromBRC> mcdonc: those paster templates all look pretty good... the
   only thing i'd consider is adjusting your config variable names to match
   exactly what sqlalchemy uses as parameter names, see here:
   http://www.sqlalchemy.org/docs/core/engines.html

   <RaFromBRC> mcdonc: especially in the pylons_sqla ini file, where the db
   initialization is mixed in w/ the app config...

   <RaFromBRC> ... i'd use "sqlalchemy.PARAMETER" for all of the sqla
   settings, so it could easily be handed to engine_from_config w/o any need
   to parse by hand

   <RaFromBRC> mcdonc: in the other ini files, where sqlalchemy is given its
   own part, the "sqlalchemy." prefix probably isn't necessary, but matching
   the parameter names (e.g. 'url' instead of 'db_string') is still probably
   a good idea

- Better ``config.add_handler`` documentation.

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

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

- Create a ``docs`` directory for each paster template.

- 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``.

- Twophase configuration (config = Configurator(autocommit=False))

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 bfg_view.

- 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``.