diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/narr/environment.rst | 2 | ||||
| -rw-r--r-- | docs/narr/hybrid.rst | 7 | ||||
| -rw-r--r-- | docs/narr/project.rst | 50 | ||||
| -rw-r--r-- | docs/narr/router.rst | 8 | ||||
| -rw-r--r-- | docs/narr/traversal.rst | 2 | ||||
| -rw-r--r-- | docs/narr/urldispatch.rst | 16 | ||||
| -rw-r--r-- | docs/tutorials/bfgwiki/basiclayout.rst | 9 | ||||
| -rw-r--r-- | docs/tutorials/bfgwiki2/authorization.rst | 12 | ||||
| -rw-r--r-- | docs/tutorials/bfgwiki2/basiclayout.rst | 16 | ||||
| -rw-r--r-- | docs/tutorials/gae/index.rst | 9 | ||||
| -rw-r--r-- | docs/tutorials/zeo/index.rst | 6 |
11 files changed, 78 insertions, 59 deletions
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index aec605a84..7163eff71 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -50,7 +50,7 @@ application-specific configuration settings. | | | the :term:`application registry` | | | | instead of the filename implied by | | | | ``filename`` value passed to | -| | | ``repoze.bfg.router.make_app``. If | +| | | ``repoze.bfg.router.make_app``. If | | | | this is a relative filename, it will | | | | be considered relative to the | | | | ``package`` passed to ``make_app`` | diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst index e0b5ea542..f04e7f3ba 100644 --- a/docs/narr/hybrid.rst +++ b/docs/narr/hybrid.rst @@ -122,10 +122,9 @@ When the view attached to this route is invoked, :mod:`repoze.bfg` will attempt to use :term:`traversal` against the context implied by the :term:`root factory` of this route. The above example isn't very useful unless you've defined a custom :term:`root factory` by passing -it to the ``repoze.bfg.router.make_app`` function, because the -*default* root factory cannot be traversed (it has no useful -``__getitem__`` method). But let's imagine that your root factory -looks like so: +it to constructor of a :term:`Configurator` because the *default* root +factory cannot be traversed (it has no useful ``__getitem__`` method). +But let's imagine that your root factory looks like so: .. code-block:: python diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 271dac897..18e63b474 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -220,10 +220,10 @@ the name ``main`` as a section name: >>> root <foo.models.MyModel object at 0x445270> -... note:: You *might* get away without passing - ``--plugin=repoze.bfg`` to the bfgshell command; the - ``--plugin=repoze.bfg`` option is only required under - conditions that are not yet well-understood. +.. note:: You *might* get away without passing + ``--plugin=repoze.bfg`` to the bfgshell command; the + ``--plugin=repoze.bfg`` option is only required under + conditions that are not yet well-understood. If you have `IPython <http://en.wikipedia.org/wiki/IPython>`_ installed in the interpreter you use to invoke the ``paster`` command, @@ -242,10 +242,36 @@ Press "Ctrl-D" to exit the interactive shell. You should always use a section name argument that refers to the actual ``app`` section within the Paste configuration file that points -at your BFG application *without any middleware wrapping*. In -particular, a section name is inappropriate as the second argument to -"bfgshell" if the configuration section it names is a ``pipeline`` -rather than an ``app``. +at your :mod:`repoze.bfg` application *without any middleware +wrapping*. In particular, a section name is inappropriate as the +second argument to "bfgshell" if the configuration section it names is +a ``pipeline`` rather than an ``app``. For example, if you have the +following ``.ini`` file content: + +.. code-block:: ini + :linenos: + + [app:myapp] + use = egg:MyProject#app + reload_templates = true + debug_authorization = false + debug_notfound = false + + [pipeline:main] + pipeline = egg:repoze.tm2#tm + myapp + +The command you use to invoke the interactive shell should be: + +.. code-block:: bash + :linenos: + + [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini myapp + +If you use ``main`` as the section name argument instead of ``myapp`` +against the above ``.ini`` file, an error will likely occur. Use the +most specific reference to the application within the ``.ini`` file +possible as the section name argument. Runnning The Project Application -------------------------------- @@ -372,8 +398,8 @@ shared by all the applications, servers and :term:`middleware` defined within the configuration file. By default it contains one key ``debug``, which is set to ``true``. This key is used by various components to decide whether to act in a "debugging" mode. -``repoze.bfg`` itself does not do anything with this parameter as of -this writing, and neither does the generated sample application. +``repoze.bfg`` itself does not do anything at all with this parameter, +and neither does any generated sample application. The ``[app:main]`` section represents configuration for your application. This section name represents the ``main`` application @@ -563,8 +589,8 @@ particular way. ``configure.zcml`` ~~~~~~~~~~~~~~~~~~ -The ``configure.zcml`` represents the :term:`application -registry`. It looks like so: +The ``configure.zcml`` contains configuration statements that inform +the :term:`application registry`. It looks like so: .. literalinclude:: MyProject/myproject/configure.zcml :linenos: diff --git a/docs/narr/router.rst b/docs/narr/router.rst index 7382c07ae..3871e154e 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -43,10 +43,10 @@ processing? :term:`route` named a ``factory`` argument, this factory is used to generate the root object, otherwise a default :term:`root factory` is used. If a root factory argument was passed to the - ``repoze.bfg.router.make_app``, that callable is used to generate - the root object. If the root factory argument passed to - ``make_app`` is ``None``, a default root factory is used to - generate a root. + :term:`Configurator` constructor, that callable is used to generate + the root object. If the root factory argument passed to the + Configurator constructor is ``None``, a default root factory is + used to generate a root. #. A ``NewRequest`` :term:`event` is sent to any subscribers. diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 9802ec01e..a1c906c3b 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -29,7 +29,7 @@ return an object which represents the root of the object graph. All usually a *mapping* object (such as a Python dictionary). .. note:: If a :term:`root factory` is passed to the :mod:`repoze.bfg` - "make_app" function as the value ``None``, a default root factory + :term:`Configurator` as the value ``None``, a default root factory is used. This is most useful when you're using :term:`URL dispatch` and you don't care very much about traversing any particular graph to resolve URLs to code. It is also possible to diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 33754e05b..ad0388284 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -41,13 +41,13 @@ before traversal has a chance to find it first. If a route matches, a :term:`context` is generated and :mod:`repoze.bfg` will call the :term:`view` specified with the context and the request. If no route matches, :mod:`repoze.bfg` will fail over to calling the :term:`root -factory` callable passed to the application in it's ``make_app`` -function (usually a traversal function). +factory` callable passed to the :term:`Configurator` for the +application (usually a traversal function). A root factory is not required for purely URL-dispatch-based apps: if -the root factory callable is passed as ``None`` to the ``make_app`` -function, :mod:`repoze.bfg` will return a ``NotFound`` error to the user's -browser when no routes match. +the root factory callable is passed as ``None`` to the +:term:`Configurator`, :mod:`repoze.bfg` will return a ``NotFound`` +error to the user's browser when no routes match. .. note:: See :ref:`modelspy_project_section` for an example of a simple root factory callable that will use traversal. @@ -497,9 +497,9 @@ class that accepts a request in its ``__init__``. type. If no route matches in the above configuration, :mod:`repoze.bfg` will -call the "fallback" :term:`root factory` callable provided to it -during ``make_app`. If the "fallback" root factory is None, a -``NotFound`` error will be raised when no route matches. +call the "fallback" :term:`root factory` callable provided to the +:term:`Configurator` constructor. If the "fallback" root factory is +None, a ``NotFound`` error will be raised when no route matches. .. note:: See :ref:`using_model_interfaces` for more information about how views are found when interfaces are attached to a diff --git a/docs/tutorials/bfgwiki/basiclayout.rst b/docs/tutorials/bfgwiki/basiclayout.rst index 738972fd1..e2f8ac00e 100644 --- a/docs/tutorials/bfgwiki/basiclayout.rst +++ b/docs/tutorials/bfgwiki/basiclayout.rst @@ -109,8 +109,9 @@ be in ``run.py`` and its ``app`` function: #. *Lines 17 - 18*. We create a :term:`root factory` using the finder. -#. Line *19*. We use the ``repoze.bfg.router.make_app`` to return a - :term:`WSGI` application. The ``make_app`` function takes the root - factory (``get_root``), the *package* representing our application, - and the settings keywords parsed by PasteDeploy. +#. Line *19*. We construct a :term:`Configurator` with a + :term:`root_factory` and the settings keywords parsed by + PasteDeploy. The root factory is named ``get_root``. We then use + the ``make_wsgi_app`` method of the :term:`Configurator` to return + a :term:`WSGI` application. diff --git a/docs/tutorials/bfgwiki2/authorization.rst b/docs/tutorials/bfgwiki2/authorization.rst index f701b4ef8..5257bbe5f 100644 --- a/docs/tutorials/bfgwiki2/authorization.rst +++ b/docs/tutorials/bfgwiki2/authorization.rst @@ -25,10 +25,10 @@ security declarations; when we begin to use a custom root factory to generate our contexts, we can begin to make use of the declarative security features of :mod:`repoze.bfg`. -Let's modify our ``run.py``, passing in a :term:`root factory` as the -first argument to ``repoze.bfg.router.make_app``. We'll point it at a -new class we create inside our ``models.py`` file. Add the following -statements to your ``models.py`` file: +Let's modify our ``run.py``, passing in a :term:`root factory` to our +:term:`Configurator` constructor. We'll point it at a new class we +create inside our ``models.py`` file. Add the following statements to +your ``models.py`` file: .. code-block:: python @@ -58,8 +58,8 @@ See :ref:`assigning_acls` for more information about what an :ref:`route_zcml_directive` for more info. We'll pass the ``RootFactory`` we created in the step above in as the -first argument to ``make_app``. When we're done, your application's -``run.py`` will look like this. +``root_factory`` argument to a :term:`Configurator`. When we're done, +your application's ``run.py`` will look like this. .. literalinclude:: src/authorization/tutorial/run.py :linenos: diff --git a/docs/tutorials/bfgwiki2/basiclayout.rst b/docs/tutorials/bfgwiki2/basiclayout.rst index 4cb37aa91..b8d0ddcc2 100644 --- a/docs/tutorials/bfgwiki2/basiclayout.rst +++ b/docs/tutorials/bfgwiki2/basiclayout.rst @@ -132,12 +132,12 @@ be in ``run.py`` and its ``app`` function: #. Line *25*. We initialize our SQL database using SQLAlchemy, passing it the db string. -#. Line *26*. We use the ``repoze.bfg.router.make_app`` to return a - :term:`WSGI` application. The ``make_app`` function's first - parameter is the "root factory", which is used by the - :mod:`repoze.bfg` :term:`traversal` mechanism. Since this is a URL - dispatch application, the root factory is ``None``. The second - argument is the *package* representing our application, and the - third argument, ``settings`` is passed as a keyword argument. It - contains a dictionary of settings parsed by PasteDeploy. +#. Line *26*. We construct a :term:`Configurator`. The first + argument provided to the configurator is the :term:`root factory`, + which is used by the :mod:`repoze.bfg` :term:`traversal` mechanism. + Since this is a URL dispatch application, the root factory is + ``None``. The second argument ``settings`` is passed as a keyword + argument. It contains a dictionary of settings parsed by + PasteDeploy. We then use the ``make_wsgi_app`` method of the + :term:`Configurator` to return a :term:`WSGI` application. diff --git a/docs/tutorials/gae/index.rst b/docs/tutorials/gae/index.rst index 2cdb3bf81..a165ff5f1 100644 --- a/docs/tutorials/gae/index.rst +++ b/docs/tutorials/gae/index.rst @@ -81,7 +81,7 @@ system. #. Edit ``config.py`` Edit the ``APP_NAME`` and ``APP_ARGS`` settings within - ``config.py``. The APP_NAME must be ``bfgapp.run:make_app``, and + ``config.py``. The ``APP_NAME`` must be ``bfgapp.run:app``, and the APP_ARGS must be ``({},)``. Any other settings in ``config.py`` should remain the same. @@ -91,13 +91,6 @@ system. APP_NAME = 'bfgapp.run:app' APP_ARGS = ({},) - .. warning:: It's very important that the ``APP_NAME`` is - ``bfgapp.run:app`` instead of ``bfgapp.run.make_app``. If you - use the latter by mistake, you'll be confused for at least an - hour when debugging an error like this: ``IOError: [Errno 2] No - such file or directory: - '/Users/chrism/projects/bfg_gae/bfgapp2/app/configure.zcml'``. - #. Edit ``runner.py`` To prevent errors for ``import site``, add this code stanza before diff --git a/docs/tutorials/zeo/index.rst b/docs/tutorials/zeo/index.rst index 6519145db..145bdf4f5 100644 --- a/docs/tutorials/zeo/index.rst +++ b/docs/tutorials/zeo/index.rst @@ -162,7 +162,7 @@ Configuration .. code-block:: python :linenos: - from repoze.bfg.router import make_app + from repoze.bfg.configuration import Configurator from repoze.zodbconn.finder import PersistentApplicationFinder from myapp.models import MyModel import transaction @@ -176,8 +176,8 @@ Configuration finder = PersistentApplicationFinder(zodb_uri, appmaker) def get_root(request): return finder(request.environ) - import myapp - return make_app(get_root, myapp, settings=settings) + config = Configurator(root_factory=get_root, settings=settings) + return config.make_wsgi_app() def appmaker(root): if not 'myapp' in root: |