diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 4 | ||||
| -rw-r--r-- | docs/designdefense.rst | 4 | ||||
| -rw-r--r-- | docs/index.rst | 9 | ||||
| -rw-r--r-- | docs/narr/assets.rst | 8 | ||||
| -rw-r--r-- | docs/narr/hooks.rst | 16 | ||||
| -rw-r--r-- | docs/narr/i18n.rst | 8 | ||||
| -rw-r--r-- | docs/narr/install.rst | 4 | ||||
| -rw-r--r-- | docs/narr/logging.rst | 4 | ||||
| -rw-r--r-- | docs/narr/muchadoabouttraversal.rst | 4 | ||||
| -rw-r--r-- | docs/narr/project.rst | 4 | ||||
| -rw-r--r-- | docs/narr/resources.rst | 6 | ||||
| -rw-r--r-- | docs/narr/templates.rst | 4 | ||||
| -rw-r--r-- | docs/narr/urldispatch.rst | 91 | ||||
| -rw-r--r-- | docs/tutorials/wiki/definingviews.rst | 8 | ||||
| -rw-r--r-- | docs/tutorials/wiki2/definingviews.rst | 4 |
15 files changed, 137 insertions, 41 deletions
diff --git a/docs/conf.py b/docs/conf.py index 71c4f58d4..a5eaeb0fb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -106,6 +106,10 @@ today_fmt = '%B %d, %Y' # List of documents that shouldn't be included in the build. #unused_docs = [] +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_themes/README.rst',] + # List of directories, relative to source directories, that shouldn't be searched # for source files. #exclude_dirs = [] diff --git a/docs/designdefense.rst b/docs/designdefense.rst index d1b969ff4..d71f9af7f 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -245,7 +245,9 @@ its API is much nicer than the ZCA registry API, work on it was largely abandoned and it is not used in :app:`Pyramid`. We continued to use a ZCA registry within :app:`Pyramid` because it ultimately proved a better fit. -.. note:: We continued using ZCA registry rather than disusing it in +.. note:: + + We continued using ZCA registry rather than disusing it in favor of using the registry implementation in :mod:`repoze.component` largely because the ZCA concept of interfaces provides for use of an interface hierarchy, which is diff --git a/docs/index.rst b/docs/index.rst index d7f2f4fb6..25aaab7af 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -227,3 +227,12 @@ Index and Glossary * :ref:`glossary` * :ref:`genindex` * :ref:`search` + + +.. add glossary in hidden toc tree so it does not complain its not included + +.. toctree:: + :hidden: + + glossary + diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst index 93b03fbc9..cd76f7b60 100644 --- a/docs/narr/assets.rst +++ b/docs/narr/assets.rst @@ -102,7 +102,9 @@ directory on a filesystem to an application user's browser. Use the mechanism makes a directory of static files available at a name relative to the application root URL, e.g. ``/static`` or as an external URL. -.. note:: :meth:`~pyramid.config.Configurator.add_static_view` cannot serve a +.. note:: + + :meth:`~pyramid.config.Configurator.add_static_view` cannot serve a single file, nor can it serve a directory of static files directly relative to the root URL of a :app:`Pyramid` application. For these features, see :ref:`advanced_static`. @@ -312,7 +314,9 @@ instance of this class is actually used by the :meth:`~pyramid.config.Configurator.add_static_view` configuration method, so its behavior is almost exactly the same once it's configured. -.. warning:: The following example *will not work* for applications that use +.. warning:: + + The following example *will not work* for applications that use :term:`traversal`, it will only work if you use :term:`URL dispatch` exclusively. The root-relative route we'll be registering will always be matched before traversal takes place, subverting any views registered via diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 4afc0506b..3ab82ecf7 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -55,7 +55,9 @@ Here's some sample code that implements a minimal NotFound view callable: def notfound_view(request): return HTTPNotFound() -.. note:: When a NotFound view callable is invoked, it is passed a +.. note:: + + When a NotFound view callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will be an instance of the :exc:`~pyramid.httpexceptions.HTTPNotFound` exception that caused the not found view to be called. The value of @@ -64,7 +66,9 @@ Here's some sample code that implements a minimal NotFound view callable: ``pyramid.debug_notfound`` environment setting is true than it is when it is false. -.. warning:: When a NotFound view callable accepts an argument list as +.. warning:: + + When a NotFound view callable accepts an argument list as described in :ref:`request_and_context_view_definitions`, the ``context`` passed as the first argument to the view callable will be the :exc:`~pyramid.httpexceptions.HTTPNotFound` exception instance. If @@ -121,7 +125,9 @@ Here's some sample code that implements a minimal forbidden view: def forbidden_view(request): return Response('forbidden') -.. note:: When a forbidden view callable is invoked, it is passed a +.. note:: + + When a forbidden view callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will be an instance of the :exc:`~pyramid.httpexceptions.HTTPForbidden` exception that caused the forbidden view to be called. The value of @@ -1100,7 +1106,9 @@ in the ``pyramid.tweens`` list will be used as the producer of the effective declared directly "below" it, ad infinitum. The "main" Pyramid request handler is implicit, and always "at the bottom". -.. note:: Pyramid's own :term:`exception view` handling logic is implemented +.. note:: + + Pyramid's own :term:`exception view` handling logic is implemented as a tween factory function: :func:`pyramid.tweens.excview_tween_factory`. If Pyramid exception view handling is desired, and tween factories are specified via the ``pyramid.tweens`` configuration setting, the diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index aef9b59ab..bac86e982 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -518,7 +518,9 @@ negotiator is registered. def aview(request): locale = get_localizer(request) -.. note:: If you need to create a localizer for a locale use the +.. note:: + + If you need to create a localizer for a locale use the :func:`pyramid.i18n.make_localizer` function. .. index:: @@ -555,7 +557,9 @@ represented by the request. The translation returned from its ``domain`` attribute of the provided translation string as well as the locale of the localizer. -.. note:: If you're using :term:`Chameleon` templates, you don't need +.. note:: + + If you're using :term:`Chameleon` templates, you don't need to pre-translate translation strings this way. See :ref:`chameleon_translation_strings`. diff --git a/docs/narr/install.rst b/docs/narr/install.rst index a1e7ce382..e1b5eb208 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -229,7 +229,9 @@ following: New python executable in env/bin/python Installing setuptools.............done. -.. warning:: Using ``--no-site-packages`` when generating your +.. warning:: + + Using ``--no-site-packages`` when generating your virtualenv is *very important*. This flag provides the necessary isolation for running the set of packages required by :app:`Pyramid`. If you do not specify ``--no-site-packages``, diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 8abcba3c7..3e39151a3 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -7,7 +7,9 @@ Logging :mod:`logging` module. This chapter describes how to configure logging and how to send log messages to loggers that you've configured. -.. warning:: This chapter assumes you've used a :term:`scaffold` to create a +.. warning:: + + This chapter assumes you've used a :term:`scaffold` to create a project which contains ``development.ini`` and ``production.ini`` files which help configure logging. All of the scaffolds which ship along with :app:`Pyramid` do this. If you're not using a scaffold, or if you've used diff --git a/docs/narr/muchadoabouttraversal.rst b/docs/narr/muchadoabouttraversal.rst index 6ad33c1ce..a948e57cc 100644 --- a/docs/narr/muchadoabouttraversal.rst +++ b/docs/narr/muchadoabouttraversal.rst @@ -313,6 +313,8 @@ don't require it, great: stick with :term:`URL dispatch`. But if you're using :app:`Pyramid` and you ever find that you *do* need to support one of these use cases, you'll be glad you have traversal in your toolkit. -.. note:: It is even possible to mix and match :term:`traversal` with +.. note:: + + It is even possible to mix and match :term:`traversal` with :term:`URL dispatch` in the same :app:`Pyramid` application. See the :ref:`hybrid_chapter` chapter for details. diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 10b7a5d04..345672204 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -64,7 +64,9 @@ The included scaffolds are these: URL mapping via :term:`traversal` and persistence via :term:`SQLAlchemy` -.. note:: At this time, each of these scaffolds uses the :term:`Chameleon` +.. note:: + + At this time, each of these scaffolds uses the :term:`Chameleon` templating system, which is incompatible with Jython. To use scaffolds to build applications which will run on Jython, you can try the ``pyramid_jinja2_starter`` scaffold which ships as part of the diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 9335906a0..256f69fc3 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -160,7 +160,9 @@ resource in the resource tree, you will eventually come to the root resource, just like if you keep executing the ``cd ..`` filesystem command, eventually you will reach the filesystem root directory. -.. warning:: If your root resource has a ``__name__`` argument that is not +.. warning:: + + If your root resource has a ``__name__`` argument that is not ``None`` or the empty string, URLs returned by the :func:`~pyramid.request.Request.resource_url` function and paths generated by the :func:`~pyramid.traversal.resource_path` and @@ -229,7 +231,7 @@ this: .. code-block:: python :linenos: - url = request.resource_url(resource, request) + url = request.resource_url(resource) The ``request`` in the above example is an instance of a :app:`Pyramid` :term:`request` object. diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 6412c070d..052843a23 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -46,7 +46,9 @@ within the body of a view callable like so: {'foo':1, 'bar':2}, request=request) -.. warning:: Earlier iterations of this documentation +.. warning:: + + Earlier iterations of this documentation (pre-version-1.3) encouraged the application developer to use ZPT-specific APIs such as :func:`pyramid.chameleon_zpt.render_template_to_response` and diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index a6e46515f..2fcbce507 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -190,7 +190,7 @@ at the end of the segment represented by ``{name}.html`` (it only contains To capture both segments, two replacement markers can be used: .. code-block:: text - + foo/{name}.{ext} The literal path ``/foo/biz.html`` will match the above route pattern, and @@ -256,10 +256,10 @@ The above pattern will match these URLs, generating the following matchdicts: .. code-block:: text - foo/1/2/ -> + foo/1/2/ -> {'baz':u'1', 'bar':u'2', 'fizzle':()} - foo/abc/def/a/b/c -> + foo/abc/def/a/b/c -> {'baz':u'abc', 'bar':u'def', 'fizzle':(u'a', u'b', u'c')} Note that when a ``*stararg`` remainder match is matched, the value put into @@ -288,7 +288,7 @@ split by segment. Changing the regular expression used to match a marker can also capture the remainder of the URL, for example: .. code-block:: text - + foo/{baz}/{bar}{fizzle:.*} The above pattern will match these URLs, generating the following matchdicts: @@ -353,7 +353,9 @@ process. Examples of route predicate arguments are ``pattern``, ``xhr``, and Other arguments are ``name`` and ``factory``. These arguments represent neither predicates nor view configuration information. -.. warning:: Some arguments are view-configuration related arguments, such as +.. warning:: + + Some arguments are view-configuration related arguments, such as ``view_renderer``. These only have an effect when the route configuration names a ``view`` and these arguments have been deprecated as of :app:`Pyramid` 1.1. @@ -646,7 +648,9 @@ other non-``name`` and non-``pattern`` arguments to exception to this rule is use of the ``pregenerator`` argument, which is not ignored when ``static`` is ``True``. -.. note:: the ``static`` argument to +.. note:: + + the ``static`` argument to :meth:`~pyramid.config.Configurator.add_route` is new as of :app:`Pyramid` 1.1. @@ -695,10 +699,10 @@ route with an appended slash. .. warning:: - You **should not** rely on this mechanism to redirect ``POST`` requests. - The redirect of the slash-appending not found view will turn a ``POST`` - request into a ``GET``, losing any ``POST`` data in the original - request. + You **should not** rely on this mechanism to redirect ``POST`` requests. + The redirect of the slash-appending not found view will turn a ``POST`` + request into a ``GET``, losing any ``POST`` data in the original + request. To configure the slash-appending not found view in your application, change the application's startup configuration, adding the following stanza: @@ -706,7 +710,7 @@ the application's startup configuration, adding the following stanza: .. code-block:: python :linenos: - config.add_view('pyramid.view.append_slash_notfound_view', + config.add_view('pyramid.view.append_slash_notfound_view', context='pyramid.httpexceptions.HTTPNotFound') See :ref:`view_module` and :ref:`changing_the_notfound_view` for more @@ -768,7 +772,7 @@ which you started the application from. For example: :linenos: [chrism@thinko pylonsbasic]$ PYRAMID_DEBUG_ROUTEMATCH=true \ - bin/paster serve development.ini + bin/paster serve development.ini Starting server in PID 13586. serving on 0.0.0.0:6543 view at http://127.0.0.1:6543 2010-12-16 14:45:19,956 no route matched for url \ @@ -809,7 +813,7 @@ will have their pattern prefixed with the value of ``route_prefix``. This can be used to help mount a set of routes at a different location than the included callable's author intended while still maintaining the same route names. For example: - + .. code-block:: python :linenos: @@ -817,7 +821,7 @@ names. For example: def users_include(config): config.add_route('show_users', '/show') - + def main(global_config, **settings): config = Configurator() config.include(users_include, route_prefix='/users') @@ -840,7 +844,7 @@ will be prepended with the first: def timing_include(config): config.add_route('show_times', /times') - + def users_include(config): config.add_route('show_users', '/show') config.include(timing_include, route_prefix='/timing') @@ -867,7 +871,7 @@ that may be added in the future. For example: def timing_include(config): config.add_route('timing.show_times', /times') - + def users_include(config): config.add_route('users.show_users', '/show') config.include(timing_include, route_prefix='/timing') @@ -909,7 +913,7 @@ For example: num_one_two_or_three = any_of('num', 'one', 'two', 'three') - config.add_route('route_to_num', '/{num}', + config.add_route('route_to_num', '/{num}', custom_predicates=(num_one_two_or_three,)) The above ``any_of`` function generates a predicate which ensures that the @@ -940,7 +944,7 @@ instance, a predicate might do some type conversion of values: ymd_to_int = integers('year', 'month', 'day') - config.add_route('ymd', '/{year}/{month}/{day}', + config.add_route('ymd', '/{year}/{month}/{day}', custom_predicates=(ymd_to_int,)) Note that a conversion predicate is still a predicate so it must return @@ -963,7 +967,7 @@ expressions specifying requirements for that marker. For instance: ymd_to_int = integers('year', 'month', 'day') - config.add_route('ymd', '/{year:\d+}/{month:\d+}/{day:\d+}', + config.add_route('ymd', '/{year:\d+}/{month:\d+}/{day:\d+}', custom_predicates=(ymd_to_int,)) Now the try/except is no longer needed because the route will not match at @@ -1001,13 +1005,54 @@ the route in a set of route predicates: config.add_route('y', '/{year}', custom_predicates=(twenty_ten,)) config.add_route('ym', '/{year}/{month}', custom_predicates=(twenty_ten,)) - config.add_route('ymd', '/{year}/{month}/{day}', + config.add_route('ymd', '/{year}/{month}/{day}', custom_predicates=(twenty_ten,)) The above predicate, when added to a number of route configurations ensures that the year match argument is '2010' if and only if the route name is 'ymd', 'ym', or 'y'. +You can also caption the predicates by setting the ``__text__`` attribute. This +will help you with the ``paster pviews`` command (see +:ref:`displaying_application_routes`) and the ``pyramid_debugtoolbar``. + +If a predicate is a class just add __text__ property in a standard manner. + +.. code-block:: python + :linenos: + + class DummyCustomPredicate1(object): + def __init__(self): + self.__text__ = 'my custom class predicate' + + class DummyCustomPredicate2(object): + __text__ = 'my custom class predicate' + +If a predicate is a method you'll need to assign it after method declaration +(see `PEP 232 <http://www.python.org/dev/peps/pep-0232/>`_) + +.. code-block:: python + :linenos: + + def custom_predicate(): + pass + custom_predicate.__text__ = 'my custom method predicate' + +If a predicate is a classmethod using @classmethod will not work, but you can +still easily do it by wrapping it in classmethod call. + +.. code-block:: python + :linenos: + + def classmethod_predicate(): + pass + classmethod_predicate.__text__ = 'my classmethod predicate' + classmethod_predicate = classmethod(classmethod_predicate) + +Same will work with staticmethod, just use ``staticmethod`` instead of +``classmethod``. + + See also :class:`pyramid.interfaces.IRoute` for more API documentation about route objects. @@ -1030,7 +1075,7 @@ callable ultimately found via :term:`view lookup`. .. code-block:: python :linenos: - config.add_route('abc', '/abc', + config.add_route('abc', '/abc', factory='myproject.resources.root_factory') config.add_view('myproject.views.theview', route_name='abc') @@ -1098,7 +1143,9 @@ permission. Obviously you can do more generic things than inspect the routes match dict to see if the ``article`` argument matches a particular string; our sample ``Article`` factory class is not very ambitious. -.. note:: See :ref:`security_chapter` for more information about +.. note:: + + See :ref:`security_chapter` for more information about :app:`Pyramid` security and ACLs. .. index:: diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst index 9d783f8cb..ed3a84118 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -7,7 +7,9 @@ application is typically a simple Python function that accepts two parameters: :term:`context` and :term:`request`. A view callable is assumed to return a :term:`response` object. -.. note:: A :app:`Pyramid` view can also be defined as callable +.. note:: + + A :app:`Pyramid` view can also be defined as callable which accepts *only* a :term:`request` argument. You'll see this one-argument pattern used in other :app:`Pyramid` tutorials and applications. Either calling convention will work in any @@ -253,7 +255,9 @@ the below: .. literalinclude:: src/views/tutorial/templates/view.pt :language: xml -.. note:: The names available for our use in a template are always those that +.. note:: + + The names available for our use in a template are always those that are present in the dictionary returned by the view callable. But our templates make use of a ``request`` object that none of our tutorial views return in their dictionary. This value appears as if "by magic". diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index 8f6dd6455..234f91246 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -7,7 +7,9 @@ application is typically a simple Python function that accepts a single parameter named :term:`request`. A view callable is assumed to return a :term:`response` object. -.. note:: A :app:`Pyramid` view can also be defined as callable +.. note:: + + A :app:`Pyramid` view can also be defined as callable which accepts *two* arguments: a :term:`context` and a :term:`request`. You'll see this two-argument pattern used in other :app:`Pyramid` tutorials and applications. Either calling |