From a1d8c03490bcd7cb00372170c4e9c67ea9af5ce3 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Tue, 19 Apr 2011 01:32:28 -0500 Subject: Converting docs to deprecate view parameters in config.add_route. --- docs/narr/hybrid.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) (limited to 'docs/narr/hybrid.rst') diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst index 780cb0975..d66ad59df 100644 --- a/docs/narr/hybrid.rst +++ b/docs/narr/hybrid.rst @@ -41,15 +41,15 @@ configuration: # config is an instance of pyramid.config.Configurator - config.add_route('foobar', '{foo}/{bar}', view='myproject.views.foobar') - config.add_route('bazbuz', '{baz}/{buz}', view='myproject.views.bazbuz') + config.add_route('foobar', '{foo}/{bar}') + config.add_route('bazbuz', '{baz}/{buz}') -Each :term:`route` typically corresponds to a single view callable, -and when that route is matched during a request, the view callable -named by the ``view`` attribute is invoked. + config.add_view('myproject.views.foobar', route_name='foobar') + config.add_view('myproject.views.bazbuz', route_name='bazbuz') -Typically, an application that uses only URL dispatch won't perform any calls -to :meth:`pyramid.config.Configurator.add_view` in its startup code. +Each :term:`route` corresponds to one or more view callables, +and when that route is matched during a request, :term:`view lookup` is used +to match the request to one of the view callables. Traversal Only ~~~~~~~~~~~~~~ @@ -196,12 +196,9 @@ remainder becomes the path used to perform traversal. The ``*remainder`` route pattern syntax is explained in more detail within :ref:`route_pattern_syntax`. -Note that unlike the examples provided within :ref:`urldispatch_chapter`, the -``add_route`` configuration statement named previously does not pass a -``view`` argument. This is because a hybrid mode application relies on -:term:`traversal` to do :term:`resource location` and :term:`view lookup` -instead of invariably invoking a specific view callable named directly within -the matched route's configuration. +A hybrid mode application relies more heavily on :term:`traversal` to do +:term:`resource location` and :term:`view lookup` than most examples indicate +within :ref:`urldispatch_chapter`. Because the pattern of the above route ends with ``*traverse``, when this route configuration is matched during a request, :app:`Pyramid` will attempt @@ -442,8 +439,8 @@ commonly in route declarations that look like this: .. code-block:: python :linenos: - config.add_route('static', '/static/*subpath', - view='mypackage.views.static_view') + config.add_route('static', '/static/*subpath') + config.add_view('mypackage.views.static_view', route_name='static') Where ``mypackage.views.static_view`` is an instance of :class:`pyramid.view.static`. This effectively tells the static helper to @@ -458,6 +455,9 @@ application. We'll detail them here. Registering a Default View for a Route That Has a ``view`` Attribute ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. note:: As of :app:`Pyramid` 1.1 this issue is deprecated along with + the ability to add views directly to the :term:`route configuration`. + It is an error to provide *both* a ``view`` argument to a :term:`route configuration` *and* a :term:`view configuration` which names a ``route_name`` that has no ``name`` value or the empty ``name`` value. For -- cgit v1.2.3 From ed7ffe0e2065100f551793b3774656d8bdde0fb0 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 22 Apr 2011 13:42:19 -0400 Subject: - Make sure deprecation warnings aren't raised when tests are run. - Modify documentation for cross-referencing. - Use add_view(viewname) syntax rather than add_view(view=viewname) syntax for normalization. - Use warnings.warn rather than zope.deprecated in order to make testing easier. - Move tests which test deprecated methods of configurator to a separate test case. --- docs/narr/hybrid.rst | 39 ++++++++++++++++++++++----------------- 1 file changed, 22 insertions(+), 17 deletions(-) (limited to 'docs/narr/hybrid.rst') diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst index d66ad59df..f8ed743fb 100644 --- a/docs/narr/hybrid.rst +++ b/docs/narr/hybrid.rst @@ -33,7 +33,7 @@ URL Dispatch Only ~~~~~~~~~~~~~~~~~ An application that uses :term:`url dispatch` exclusively to map URLs to code -will often have statements like this within your application startup +will often have statements like this within application startup configuration: .. code-block:: python @@ -47,9 +47,14 @@ configuration: config.add_view('myproject.views.foobar', route_name='foobar') config.add_view('myproject.views.bazbuz', route_name='bazbuz') -Each :term:`route` corresponds to one or more view callables, -and when that route is matched during a request, :term:`view lookup` is used -to match the request to one of the view callables. +Each :term:`route` corresponds to one or more view callables. Each view +callable is associated with a route by passing a ``route_name`` parameter +that matches its name during a call to +:meth:`~pyramid.config.Configurator.add_view`. When a route is matched +during a request, :term:`view lookup` is used to match the request to its +associated view callable. The presence of calls to +:meth:`~pyramid.config.Configurator.add_route` signify that an application is +using URL dispatch. Traversal Only ~~~~~~~~~~~~~~ @@ -423,13 +428,11 @@ attribute. Using ``*subpath`` in a Route Pattern ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There are certain extremely rare cases when you'd like to influence -the traversal :term:`subpath` when a route matches without actually -performing traversal. For instance, the -:func:`pyramid.wsgi.wsgiapp2` decorator and the -:class:`pyramid.view.static` helper attempt to compute -``PATH_INFO`` from the request's subpath, so it's useful to be able to -influence this value. +There are certain extremely rare cases when you'd like to influence the +traversal :term:`subpath` when a route matches without actually performing +traversal. For instance, the :func:`pyramid.wsgi.wsgiapp2` decorator and the +:class:`pyramid.view.static` helper attempt to compute ``PATH_INFO`` from the +request's subpath, so it's useful to be able to influence this value. When ``*subpath`` exists in a pattern, no path is actually traversed, but the traversal algorithm will return a :term:`subpath` list implied @@ -455,14 +458,16 @@ application. We'll detail them here. Registering a Default View for a Route That Has a ``view`` Attribute ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. note:: As of :app:`Pyramid` 1.1 this issue is deprecated along with - the ability to add views directly to the :term:`route configuration`. +.. warning:: As of :app:`Pyramid` 1.1 this section is slated to be removed in + a later documentation release because the the ability to add views + directly to the :term:`route configuration` by passing a ``view`` argument + to ``add_route`` has been deprecated. It is an error to provide *both* a ``view`` argument to a :term:`route configuration` *and* a :term:`view configuration` which names a ``route_name`` that has no ``name`` value or the empty ``name`` value. For -example, this pair of declarations will generate a "conflict" error at -startup time. +example, this pair of declarations will generate a conflict error at startup +time. .. code-block:: python :linenos: @@ -490,8 +495,8 @@ Can also be spelled like so: config.add_route('home', '{foo}/{bar}/*traverse') config.add_view('myproject.views.home', route_name='home') -The two spellings are logically equivalent. In fact, the former is -just a syntactical shortcut for the latter. +The two spellings are logically equivalent. In fact, the former is just a +syntactical shortcut for the latter. Binding Extra Views Against a Route Configuration that Doesn't Have a ``*traverse`` Element In Its Pattern ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3