- Added "Adding Methods to the Configurator via ``add_directive``" section ...

Chris McDonough

2011-01-20 14e91bfd4af61251853b73aad33ff47c237339aa

- Added "Adding Methods to the Configurator via ``add_directive``" section to
  Advanced Configuration narrative chapter.

 CHANGES.txt

@@ -18,6 +18,9 @@
- Fix deprecated example showing ``chameleon_zpt`` API call in testing
  narrative chapter.

- Added "Adding Methods to the Configurator via ``add_directive``" section to
  Advanced Configuration narrative chapter.

Deprecations
-------------


 TODO.txt

@@ -22,6 +22,13 @@
- Add docs for ``route_path`` and ``route_url``, etc to Request API docs (see
  also https://github.com/Pylons/pyramid/issues#issue/19).

- Add example for ``__action_decorator__`` to pyramid_handler docs.

- Figure out what to do with "Forms" chapter in narr docs.

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

- Reversing (context, request) in function view callable arglist produces
  incomprehensible traceback::

@@ -41,15 +48,6 @@
   if len(args) - len(defaults) == 1:
   zope.configuration.config.ConfigurationExecutionError: <type 'exceptions.TypeError'>: object of type 'NoneType' has no len()                                    in:
    ('reversed.py', 14, '<module>', "c.add_view(aview, renderer='__main__:foo.pt')")

- Document ``add_directive``.

- Add example for ``__action_decorator__`` to pyramid_handler docs.

- Figure out what to do with "Forms" chapter in narr docs.

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

- Fix misleading conflict error reports for static views ala
  http://cluebin.appspot.com/pasted/7242843

 docs/api/config.rst

@@ -28,6 +28,8 @@

     .. automethod:: include

     .. automethod:: add_directive

     .. automethod:: with_package

     .. automethod:: maybe_dotted
@@ -71,8 +73,6 @@
     .. automethod:: set_request_factory

     .. automethod:: set_renderer_globals_factory

     .. automethod:: add_directive

     .. automethod:: testing_securitypolicy


 docs/narr/advconfig.rst

@@ -403,3 +403,70 @@
constraints are not absolved by two-phase configuration.  Routes are still
added in configuration execution order.

Adding Methods to the Configurator via ``add_directive``
--------------------------------------------------------

Framework extension writers can add arbitrary methods to a
:term:`Configurator` by using the
:meth:`pyramid.config.Configurator.add_directive` method of the configurator.
This makes it possible to extend a Pyramid configurator in arbitrary ways,
and allows it to perform application-specific tasks more succinctly.

The :meth:`~pyramid.config.Configurator.add_directive` method accepts two
positional arguments: a method name and a callable object.  The callable
object is usually a function that takes the configurator instance as its
first argument and accepts other arbitrary positional and keyword arguments.
For example:

.. code-block:: python
   :linenos:

   from pyramid.events import NewRequest
   from pyramid.config import Configurator

   def add_newrequest_subscriber(config, subscriber):
       config.add_subscriber(subscriber, NewRequest).

   if __name__ == '__main__':
      config = Configurator()
      config.add_directive('add_newrequest_subscriber', 
                           add_newrequest_subscriber)

Once :meth:`~pyramid.config.Configurator.add_directive` is called, a user can
then call the method by its given name as if it were a built-in method of the
Configurator:

.. code-block:: python
   :linenos:

   def mysubscriber(event):
      print event.request

   config.add_newrequest_subscriber(mysubscriber)

A call to :meth:`~pyramid.config.Configurator.add_directive` is often
"hidden" within an ``includeme`` function within a "frameworky" package meant
to be included as per :ref:`including_configuration` via
:meth:`~pyramid.config.Configurator.include`.  For example, if you put this
code in a package named ``pyramid_subscriberhelpers``:

.. code-block:: python
   :linenos:

   def includeme(config)
      config.add_directive('add_newrequest_subscriber', 
                           add_newrequest_subscriber)

The user of the add-on package ``pyramid_subscriberhelpers`` would then be
able to install it and subsequently do:

.. code-block:: python
   :linenos:

   def mysubscriber(event):
      print event.request

   from pyramid.config import Configurator
   config = Configurator()
   config.include('pyramid_subscriberhelpers')
   config.add_newrequest_subscriber(mysubscriber)