From d7f2590a4c2c2164bdb01ba977119ccbb6b2b09c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 9 Dec 2010 02:30:23 -0500 Subject: fix docs: pyramid.configuration -> pyramid.config --- docs/zcml/aclauthorizationpolicy.rst | 2 +- docs/zcml/authtktauthenticationpolicy.rst | 2 +- docs/zcml/default_permission.rst | 4 ++-- docs/zcml/forbidden.rst | 2 +- docs/zcml/localenegotiator.rst | 2 +- docs/zcml/notfound.rst | 2 +- docs/zcml/remoteuserauthenticationpolicy.rst | 2 +- docs/zcml/renderer.rst | 2 +- docs/zcml/repozewho1authenticationpolicy.rst | 2 +- docs/zcml/resource.rst | 2 +- docs/zcml/route.rst | 2 +- docs/zcml/scan.rst | 2 +- docs/zcml/static.rst | 2 +- docs/zcml/subscriber.rst | 2 +- docs/zcml/translationdir.rst | 2 +- docs/zcml/view.rst | 2 +- 16 files changed, 17 insertions(+), 17 deletions(-) (limited to 'docs/zcml') diff --git a/docs/zcml/aclauthorizationpolicy.rst b/docs/zcml/aclauthorizationpolicy.rst index 7eecf6c6e..2c66da0c8 100644 --- a/docs/zcml/aclauthorizationpolicy.rst +++ b/docs/zcml/aclauthorizationpolicy.rst @@ -24,7 +24,7 @@ Alternatives You may create an instance of the :class:`pyramid.authorization.ACLAuthorizationPolicy` and pass it -to the :class:`pyramid.configuration.Configurator` constructor as +to the :class:`pyramid.config.Configurator` constructor as the ``authorization_policy`` argument during initial application configuration. diff --git a/docs/zcml/authtktauthenticationpolicy.rst b/docs/zcml/authtktauthenticationpolicy.rst index 1119de9b0..25be4186c 100644 --- a/docs/zcml/authtktauthenticationpolicy.rst +++ b/docs/zcml/authtktauthenticationpolicy.rst @@ -91,7 +91,7 @@ Alternatives You may create an instance of the :class:`pyramid.authentication.AuthTktAuthenticationPolicy` and -pass it to the :class:`pyramid.configuration.Configurator` +pass it to the :class:`pyramid.config.Configurator` constructor as the ``authentication_policy`` argument during initial application configuration. diff --git a/docs/zcml/default_permission.rst b/docs/zcml/default_permission.rst index beb60db1a..54e720ea6 100644 --- a/docs/zcml/default_permission.rst +++ b/docs/zcml/default_permission.rst @@ -43,11 +43,11 @@ Alternatives ~~~~~~~~~~~~ Using the ``default_permission`` argument to the -:class:`pyramid.configuration.Configurator` constructor can be used +:class:`pyramid.config.Configurator` constructor can be used to achieve the same purpose. Using the -:meth:`pyramid.configuration.Configurator.set_default_permission` +:meth:`pyramid.config.Configurator.set_default_permission` method can be used to achieve the same purpose when using imperative configuration. diff --git a/docs/zcml/forbidden.rst b/docs/zcml/forbidden.rst index f5b1b4644..7ea6b85fd 100644 --- a/docs/zcml/forbidden.rst +++ b/docs/zcml/forbidden.rst @@ -68,7 +68,7 @@ Alternatives Use the :ref:`view_directive` directive with a ``context`` that names the :exc:`pyramid.exceptions.Forbidden` class. -Use the :meth:`pyramid.configuration.Configurator.add_view` method, +Use the :meth:`pyramid.config.Configurator.add_view` method, passing it a ``context`` which is the :exc:`pyramid.exceptions.Forbidden` class. diff --git a/docs/zcml/localenegotiator.rst b/docs/zcml/localenegotiator.rst index 100fa837a..c90e649f6 100644 --- a/docs/zcml/localenegotiator.rst +++ b/docs/zcml/localenegotiator.rst @@ -29,7 +29,7 @@ Example Alternatives ~~~~~~~~~~~~ -Use :meth:`pyramid.configuration.Configurator.set_locale_negotiator` +Use :meth:`pyramid.config.Configurator.set_locale_negotiator` method instance during initial application setup. See Also diff --git a/docs/zcml/notfound.rst b/docs/zcml/notfound.rst index 54826ea17..a2ed95bc4 100644 --- a/docs/zcml/notfound.rst +++ b/docs/zcml/notfound.rst @@ -67,7 +67,7 @@ Alternatives Use the :ref:`view_directive` directive with a ``context`` that names the :exc:`pyramid.exceptions.NotFound` class. -Use the :meth:`pyramid.configuration.Configurator.add_view` method, +Use the :meth:`pyramid.config.Configurator.add_view` method, passing it a ``context`` which is the :exc:`pyramid.exceptions.NotFound` class. diff --git a/docs/zcml/remoteuserauthenticationpolicy.rst b/docs/zcml/remoteuserauthenticationpolicy.rst index d21cd99d2..56e73ee7a 100644 --- a/docs/zcml/remoteuserauthenticationpolicy.rst +++ b/docs/zcml/remoteuserauthenticationpolicy.rst @@ -40,7 +40,7 @@ Alternatives You may create an instance of the :class:`pyramid.authentication.RemoteUserAuthenticationPolicy` and -pass it to the :class:`pyramid.configuration.Configurator` +pass it to the :class:`pyramid.config.Configurator` constructor as the ``authentication_policy`` argument during initial application configuration. diff --git a/docs/zcml/renderer.rst b/docs/zcml/renderer.rst index 67c2a7f0c..c7beead32 100644 --- a/docs/zcml/renderer.rst +++ b/docs/zcml/renderer.rst @@ -42,7 +42,7 @@ Examples Alternatives ~~~~~~~~~~~~ -The :meth:`pyramid.configuration.Configurator.add_renderer` method +The :meth:`pyramid.config.Configurator.add_renderer` method is equivalent to the ``renderer`` ZCML directive. See Also diff --git a/docs/zcml/repozewho1authenticationpolicy.rst b/docs/zcml/repozewho1authenticationpolicy.rst index e5152f2e1..11907ce31 100644 --- a/docs/zcml/repozewho1authenticationpolicy.rst +++ b/docs/zcml/repozewho1authenticationpolicy.rst @@ -42,7 +42,7 @@ Alternatives You may create an instance of the :class:`pyramid.authentication.RepozeWho1AuthenticationPolicy` and -pass it to the :class:`pyramid.configuration.Configurator` +pass it to the :class:`pyramid.config.Configurator` constructor as the ``authentication_policy`` argument during initial application configuration. diff --git a/docs/zcml/resource.rst b/docs/zcml/resource.rst index 4cf5ef400..3f7c58faa 100644 --- a/docs/zcml/resource.rst +++ b/docs/zcml/resource.rst @@ -53,7 +53,7 @@ Examples Alternatives ~~~~~~~~~~~~ -The :meth:`pyramid.configuration.Configurator.override_resource` +The :meth:`pyramid.config.Configurator.override_resource` method can be used instead of the ``resource`` ZCML directive. See Also diff --git a/docs/zcml/route.rst b/docs/zcml/route.rst index c3bec72df..4f7cdb955 100644 --- a/docs/zcml/route.rst +++ b/docs/zcml/route.rst @@ -215,7 +215,7 @@ Alternatives You can also add a :term:`route configuration` via: -- Using the :meth:`pyramid.configuration.Configurator.add_route` method. +- Using the :meth:`pyramid.config.Configurator.add_route` method. See Also ~~~~~~~~ diff --git a/docs/zcml/scan.rst b/docs/zcml/scan.rst index cbf797e1c..df2cdd281 100644 --- a/docs/zcml/scan.rst +++ b/docs/zcml/scan.rst @@ -25,7 +25,7 @@ Example Alternatives ~~~~~~~~~~~~ -The :meth:`pyramid.configuration.Configurator.scan` method performs +The :meth:`pyramid.config.Configurator.scan` method performs the same job as the ``scan`` ZCML directive. See Also diff --git a/docs/zcml/static.rst b/docs/zcml/static.rst index 164e7400c..9538d18f0 100644 --- a/docs/zcml/static.rst +++ b/docs/zcml/static.rst @@ -79,7 +79,7 @@ Examples Alternatives ~~~~~~~~~~~~ -:meth:`pyramid.configuration.configurator.add_static_view` can also +:meth:`pyramid.config.Configurator.add_static_view` can also be used to add a static view. See Also diff --git a/docs/zcml/subscriber.rst b/docs/zcml/subscriber.rst index d584f1e02..25c4abf2e 100644 --- a/docs/zcml/subscriber.rst +++ b/docs/zcml/subscriber.rst @@ -37,7 +37,7 @@ Alternatives ~~~~~~~~~~~~ You can also register an event listener by using the -:meth:`pyramid.configuration.Configurator.add_subscriber` method. +:meth:`pyramid.config.Configurator.add_subscriber` method. See Also ~~~~~~~~ diff --git a/docs/zcml/translationdir.rst b/docs/zcml/translationdir.rst index 56c0977db..5cf615d26 100644 --- a/docs/zcml/translationdir.rst +++ b/docs/zcml/translationdir.rst @@ -55,7 +55,7 @@ Example 3 Alternatives ~~~~~~~~~~~~ -Use :meth:`pyramid.configuration.Configurator.add_translation_dirs` +Use :meth:`pyramid.config.Configurator.add_translation_dirs` method instance during initial application setup. See Also diff --git a/docs/zcml/view.rst b/docs/zcml/view.rst index 6e67b4c56..74d497cb3 100644 --- a/docs/zcml/view.rst +++ b/docs/zcml/view.rst @@ -244,7 +244,7 @@ You can also add a :term:`view configuration` via: - Using the :class:`pyramid.view.view_config` class as a decorator. -- Using the :meth:`pyramid.configuration.Configurator.add_view` method. +- Using the :meth:`pyramid.config.Configurator.add_view` method. See Also ~~~~~~~~ -- cgit v1.2.3 From e8edd5ff7157c9a11b6478702c1e45bb46f11344 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 9 Dec 2010 04:04:39 -0500 Subject: - Add a ``handler`` ZCML directive. This directive does the same thing as ``pyramid.configuration.add_handler``. --- docs/zcml/handler.rst | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 docs/zcml/handler.rst (limited to 'docs/zcml') diff --git a/docs/zcml/handler.rst b/docs/zcml/handler.rst new file mode 100644 index 000000000..301bf7895 --- /dev/null +++ b/docs/zcml/handler.rst @@ -0,0 +1,158 @@ +.. _handler_directive: + +``handler`` +----------- + +The ``handler`` directive adds the configuration of a :term:`view handler` to +the :term:`application registry`. + +Attributes +~~~~~~~~~~ + +``route_name`` + The name of the route, e.g. ``myroute``. This attribute is required. It + must be unique among all defined handler and route names in a given + configuration. + +``pattern`` + The pattern of the route e.g. ``ideas/{idea}``. This attribute is + required. See :ref:`route_pattern_syntax` for information about the syntax + of route patterns. The name ``{action}`` is treated specially in handler + patterns. See :ref:`using_add_handler` for a discussion of how + ``{action}`` in handler patterns is treated. + +``action`` + If the action name is not specified in the ``pattern``, use this name as the + handler action (method name). + +``factory`` + The :term:`dotted Python name` to a function that will generate a + :app:`Pyramid` context object when the associated route matches. + e.g. ``mypackage.models.MyFactoryClass``. If this argument is not + specified, a default root factory will be used. + +``xhr`` + This value should be either ``True`` or ``False``. If this value is + specified and is ``True``, the :term:`request` must possess an + ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header for this + route to match. This is useful for detecting AJAX requests issued + from jQuery, Prototype and other Javascript libraries. If this + predicate returns false, route matching continues. + +``traverse`` + If you would like to cause the :term:`context` to be something other + than the :term:`root` object when this route matches, you can spell + a traversal pattern as the ``traverse`` argument. This traversal + pattern will be used as the traversal path: traversal will begin at + the root object implied by this route (either the global root, or + the object returned by the ``factory`` associated with this route). + + The syntax of the ``traverse`` argument is the same as it is for + ``pattern``. For example, if the ``pattern`` provided to the + ``route`` directive is ``articles/{article}/edit``, and the + ``traverse`` argument provided to the ``route`` directive is + ``/{article}``, when a request comes in that causes the route to + match in such a way that the ``article`` match value is '1' (when + the request URI is ``/articles/1/edit``), the traversal path will be + generated as ``/1``. This means that the root object's + ``__getitem__`` will be called with the name ``1`` during the + traversal phase. If the ``1`` object exists, it will become the + :term:`context` of the request. :ref:`traversal_chapter` has more + information about traversal. + + If the traversal path contains segment marker names which are not + present in the ``pattern`` argument, a runtime error will occur. + The ``traverse`` pattern should not contain segment markers that do + not exist in the ``pattern``. + + A similar combining of routing and traversal is available when a + route is matched which contains a ``*traverse`` remainder marker in + its ``pattern`` (see :ref:`using_traverse_in_a_route_pattern`). The + ``traverse`` argument to the ``route`` directive allows you to + associate route patterns with an arbitrary traversal path without + using a a ``*traverse`` remainder marker; instead you can use other + match information. + + Note that the ``traverse`` argument to the ``handler`` directive is + ignored when attached to a route that has a ``*traverse`` remainder + marker in its pattern. + +``request_method`` + A string representing an HTTP method name, e.g. ``GET``, ``POST``, + ``HEAD``, ``DELETE``, ``PUT``. If this argument is not specified, + this route will match if the request has *any* request method. If + this predicate returns false, route matching continues. + +``path_info`` + The value of this attribute represents a regular expression pattern + that will be tested against the ``PATH_INFO`` WSGI environment + variable. If the regex matches, this predicate will be true. If + this predicate returns false, route matching continues. + +``request_param`` + This value can be any string. A view declaration with this + attribute ensures that the associated route will only match when the + request has a key in the ``request.params`` dictionary (an HTTP + ``GET`` or ``POST`` variable) that has a name which matches the + supplied value. If the value supplied to the attribute has a ``=`` + sign in it, e.g. ``request_params="foo=123"``, then the key + (``foo``) must both exist in the ``request.params`` dictionary, and + the value must match the right hand side of the expression (``123``) + for the route to "match" the current request. If this predicate + returns false, route matching continues. + +``header`` + The value of this attribute represents an HTTP header name or a + header name/value pair. If the value contains a ``:`` (colon), it + will be considered a name/value pair (e.g. ``User-Agent:Mozilla/.*`` + or ``Host:localhost``). The *value* of an attribute that represent + a name/value pair should be a regular expression. If the value does + not contain a colon, the entire value will be considered to be the + header name (e.g. ``If-Modified-Since``). If the value evaluates to + a header name only without a value, the header specified by the name + must be present in the request for this predicate to be true. If + the value evaluates to a header name/value pair, the header + specified by the name must be present in the request *and* the + regular expression specified as the value must match the header + value. Whether or not the value represents a header name or a + header name/value pair, the case of the header name is not + significant. If this predicate returns false, route matching + continues. + +``accept`` + The value of this attribute represents a match query for one or more + mimetypes in the ``Accept`` HTTP request header. If this value is + specified, it must be in one of the following forms: a mimetype + match token in the form ``text/plain``, a wildcard mimetype match + token in the form ``text/*`` or a match-all wildcard mimetype match + token in the form ``*/*``. If any of the forms matches the + ``Accept`` header of the request, this predicate will be true. If + this predicate returns false, route matching continues. + +``custom_predicates`` + This value should be a sequence of references to custom predicate + callables. Use custom predicates when no set of predefined + predicates does what you need. Custom predicates can be combined + with predefined predicates as necessary. Each custom predicate + callable should accept two arguments: ``info`` and ``request`` + and should return either ``True`` or ``False`` after doing arbitrary + evaluation of the info and/or the request. If all custom and + non-custom predicate callables return ``True`` the associated route + will be considered viable for a given request. If any predicate + callable returns ``False``, route matching continues. Note that the + value ``info`` passed to a custom route predicate is a dictionary + containing matching information; see :ref:`custom_route_predicates` + for more information about ``info``. + + +Alternatives +~~~~~~~~~~~~ + +You can also add a :term:`route configuration` via: + +- Using the :meth:`pyramid.config.Configurator.add_handler` method. + +See Also +~~~~~~~~ + +See also :ref:`handlers_chapter`. -- cgit v1.2.3