diff options
Diffstat (limited to 'docs/narr/scanning.rst')
| -rw-r--r-- | docs/narr/scanning.rst | 202 |
1 files changed, 0 insertions, 202 deletions
diff --git a/docs/narr/scanning.rst b/docs/narr/scanning.rst deleted file mode 100644 index 83908540e..000000000 --- a/docs/narr/scanning.rst +++ /dev/null @@ -1,202 +0,0 @@ -.. _scanning_chapter: - -Configuration, Decorations And Code Scanning -============================================ - -:mod:`repoze.bfg` provides a number of "modes" for performing -application configuration. These modes can be used interchangeably or -even combined, as necessary. - -For example: - -- A ``<view>`` :term:`ZCML declaration` adds a :term:`view - configuration` to the current :term:`application registry`. - -- A call to the :meth:`repoze.bfg.configuration.Configurator.add_view` - method adds a :term:`view configuration` to the current - :term:`application registry`. - -- the :class:`repoze.bfg.view.bfg_view` :term:`decorator` adds - :term:`configuration decoration` to the function or method it - decorates. This particular decoration can result in a :term:`view - configuration` to be added to the current :term:`application - registry` if the package the code lives in is run through a - :term:`scan`. - -.. index:: - single: decorator - single: scan - -Decorations and Code Scanning ------------------------------ - -To lend more *locality of reference* to a :term:`configuration -declaration`, :mod:`repoze.bfg` allows you to insert -:term:`configuration decoration` statements very close to code that is -referred to by the declaration itself. - -The mere existence of configuration decoration doesn't cause any -configuration registration to be made. Before they have any effect on -the configuration of a :mod:`repoze.bfg` application, a configuration -decoration within application code must be found through a process -known as *scanning*. - -:mod:`repoze.bfg` is willing to :term:`scan` a module or a package and -its subpackages for decorations when the -:meth:`repoze.bfg.configuration.Configurator.scan` method is invoked: -scanning implies searching for configuration declarations in a package -and its subpackages. :term:`ZCML` can also invoke a :term:`scan` via -its ``<scan>`` directive. - -The scanning machinery imports each module and subpackage in a package -or module recursively, looking for special attributes attached to -objects defined within a module. These special attributes are -typically attached to code via the use of a :term:`decorator`. For -example, the :class:`repoze.bfg.view.bfg_view` decorator can be -attached to a function or instance method: - -.. code-block:: python - :linenos: - - from repoze.bfg.view import bfg_view - from webob import Response - - @bfg_view(name='hello', request_method='GET') - def hello(request): - return Response('Hello') - -The :class:`repoze.bfg.view.bfg_view` decorator above simply adds an -attribute to the ``hello`` function, making it available for a -:term:`scan` to find it later. - -Once scanning is invoked, and :term:`configuration decoration` is -found by the scanner, a set of calls are made to a -:term:`Configurator` on behalf of the developer: these calls represent -the intent of the configuration decoration. In the example above, -this is best represented as the scanner translating the arguments to -:class:`repoze.bfg.view.bfg_view` into a call to the -:meth:`repoze.bfg.configuration.Configurator.add_view` method, -effectively: - -.. ignore-next-block -.. code-block:: python - - config.add_view(hello, name='hello', request_method='GET') - -Scanning for :term:`configuration decoration` is performed via the -:meth:`repoze.bfg.configuration.Configurator.scan` method or via a -``<scan>`` :term:`ZCML declaration`. See -:ref:`config_mode_equivalence` for examples. - -.. index:: - pair: configuration mode; equivalence - single: add_view - single: bfg_view - pair: ZCML directive; view - -.. _config_mode_equivalence: - -Configuration Mode Equivalence ------------------------------- - -A combination of imperative configuration, declarative configuration -via ZCML and scanning can be used to configure any application. Each -of the below examples produces the same application configuration. - -.. topic:: Completely Imperative Configuration - - .. code-block:: python - :linenos: - - # helloworld.py - - from repoze.bfg.view import bfg_view - from webob import Response - - def hello(request): - return Response('Hello') - - if __name__ == '__main__': - from repoze.bfg.configuration import Configurator - config = Configurator() - config.add_view(hello, name='hello', request_method='GET') - -.. topic:: Configuration via ZCML - - .. code-block:: python - :linenos: - - # helloworld.py - - from webob import Response - - def hello(request): - return Response('Hello') - - if __name__ == '__main__': - from repoze.bfg.configuration import Configurator - config = Configurator() - config.load_zcml('configure.zcml') - - .. code-block:: xml - :linenos: - - <configure xmlns="http://namespaces.repoze.org"> - - <!-- configure.zcml --> - - <include package="repoze.bfg.includes"/> - - <view name="hello" - request_method="GET"/> - - </configure> - -.. topic:: Using Decorations (Imperatively Starting a Scan) - - .. code-block:: python - :linenos: - - from repoze.bfg.view import bfg_view - from webob import Response - - @bfg_view(name='hello', request_method='GET') - def hello(request): - return Response('Hello') - - if __name__ == '__main__': - from repoze.bfg.configuration import Configurator - config = Configurator() - config.scan() - -.. topic:: Using Decorations (Starting a Scan via ZCML) - - .. code-block:: python - :linenos: - - # helloworld.py - - from repoze.bfg.view import bfg_view - from webob import Response - - @bfg_view(name='hello', request_method='GET') - def hello(request): - return Response('Hello') - - if __name__ == '__main__': - from repoze.bfg.configuration import Configurator - config = Configurator() - config.load_zcml('configure.zcml') - - .. code-block:: xml - :linenos: - - <configure xmlns="http://namespaces.repoze.org"> - - <!-- configure.zcml --> - - <include package="repoze.bfg.includes"/> - <scan package="."/> - - </configure> - |