summaryrefslogtreecommitdiff
path: root/docs/narr
diff options
context:
space:
mode:
Diffstat (limited to 'docs/narr')
-rw-r--r--docs/narr/commandline.rst22
-rw-r--r--docs/narr/hooks.rst88
-rw-r--r--docs/narr/introspector.rst15
-rw-r--r--docs/narr/project.rst21
-rw-r--r--docs/narr/renderers.rst20
-rw-r--r--docs/narr/resources.rst39
-rw-r--r--docs/narr/traversal.rst9
-rw-r--r--docs/narr/urldispatch.rst4
8 files changed, 128 insertions, 90 deletions
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index a1fcf12f5..95927cfca 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -606,19 +606,21 @@ Assuming that you have a route configured in your application like so:
config.add_route('verify', '/verify/{code}')
You need to inform the Pyramid environment that the WSGI application is
-handling requests from a certain base. For example, we want to mount our
-application at `example.com/prefix` and the generated URLs should use HTTPS.
-This can be done by mutating the request object:
+handling requests from a certain base. For example, we want to simulate
+mounting our application at `https://example.com/prefix`, to ensure that
+the generated URLs are correct for our deployment. This can be done by
+either mutating the resulting request object, or more simply by constructing
+the desired request and passing it into :func:`~pyramid.paster.bootstrap`:
.. code-block:: python
from pyramid.paster import bootstrap
- env = bootstrap('/path/to/my/development.ini#another')
- env['request'].host = 'example.com'
- env['request'].scheme = 'https'
- env['request'].script_name = '/prefix'
+ from pyramid.request import Request
+
+ request = Request.blank('/', base_url='https://example.com/prefix')
+ env = bootstrap('/path/to/my/development.ini#another', request=request)
print env['request'].application_url
- # will print 'https://example.com/prefix/another/url'
+ # will print 'https://example.com/prefix'
Now you can readily use Pyramid's APIs for generating URLs:
@@ -630,8 +632,8 @@ Now you can readily use Pyramid's APIs for generating URLs:
Cleanup
~~~~~~~
-When your scripting logic finishes, it's good manners (but not required) to
-call the ``closer`` callback:
+When your scripting logic finishes, it's good manners to call the ``closer``
+callback:
.. code-block:: python
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index fd6544416..2c4310080 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -406,11 +406,10 @@ via configuration.
.. code-block:: python
:linenos:
- from pyramid.interfaces import ITraverser
- from zope.interface import Interface
+ from pyramid.config import Configurator
from myapp.traversal import Traverser
-
- config.registry.registerAdapter(Traverser, (Interface,), ITraverser)
+ config = Configurator()
+ config.set_traverser(Traverser)
In the example above, ``myapp.traversal.Traverser`` is assumed to be a class
that implements the following interface:
@@ -456,12 +455,11 @@ used. Otherwise, the default traverser would be used. For example:
.. code-block:: python
:linenos:
- from pyramid.interfaces import ITraverser
- from zope.interface import Interface
from myapp.traversal import Traverser
from myapp.resources import MyRoot
-
- config.registry.registerAdapter(Traverser, (MyRoot,), ITraverser)
+ from pyramid.config import Configurator
+ config = Configurator()
+ config.set_traverser(Traverser, MyRoot)
If the above stanza was added to a Pyramid ``__init__.py`` file's ``main``
function, :app:`Pyramid` would use the ``myapp.traversal.Traverser`` only
@@ -481,58 +479,55 @@ When you add a traverser as described in :ref:`changing_the_traverser`, it's
often convenient to continue to use the
:meth:`pyramid.request.Request.resource_url` API. However, since the way
traversal is done will have been modified, the URLs it generates by default
-may be incorrect.
+may be incorrect when used against resources derived from your custom
+traverser.
If you've added a traverser, you can change how
:meth:`~pyramid.request.Request.resource_url` generates a URL for a specific
-type of resource by adding a registerAdapter call for
-:class:`pyramid.interfaces.IContextURL` to your application:
+type of resource by adding a call to
+:meth:`pyramid.config.add_resource_url_adapter`.
+
+For example:
.. code-block:: python
:linenos:
- from pyramid.interfaces import ITraverser
- from zope.interface import Interface
- from myapp.traversal import URLGenerator
+ from myapp.traversal import ResourceURLAdapter
from myapp.resources import MyRoot
- config.registry.registerAdapter(URLGenerator, (MyRoot, Interface),
- IContextURL)
+ config.add_resource_url_adapter(ResourceURLAdapter, resource_iface=MyRoot)
-In the above example, the ``myapp.traversal.URLGenerator`` class will be used
-to provide services to :meth:`~pyramid.request.Request.resource_url` any time
-the :term:`context` passed to ``resource_url`` is of class
-``myapp.resources.MyRoot``. The second argument in the ``(MyRoot,
-Interface)`` tuple represents the type of interface that must be possessed by
-the :term:`request` (in this case, any interface, represented by
-``zope.interface.Interface``).
+In the above example, the ``myapp.traversal.ResourceURLAdapter`` class will
+be used to provide services to :meth:`~pyramid.request.Request.resource_url`
+any time the :term:`resource` passed to ``resource_url`` is of the class
+``myapp.resources.MyRoot``. The ``resource_iface`` argument ``MyRoot``
+represents the type of interface that must be possessed by the resource for
+this resource url factory to be found. If the ``resource_iface`` argument is
+omitted, this resource url adapter will be used for *all* resources.
-The API that must be implemented by a class that provides
-:class:`~pyramid.interfaces.IContextURL` is as follows:
+The API that must be implemented by your a class that provides
+:class:`~pyramid.interfaces.IResourceURL` is as follows:
.. code-block:: python
:linenos:
- from zope.interface import Interface
-
- class IContextURL(Interface):
- """ An adapter which deals with URLs related to a context.
+ class MyResourceURL(object):
+ """ An adapter which provides the virtual and physical paths of a
+ resource
"""
- def __init__(self, context, request):
- """ Accept the context and request """
-
- def virtual_root(self):
- """ Return the virtual root object related to a request and the
- current context"""
-
- def __call__(self):
- """ Return a URL that points to the context """
+ def __init__(self, resource, request):
+ """ Accept the resource and request and set self.physical_path and
+ self.virtual_path"""
+ self.virtual_path = some_function_of(resource, request)
+ self.physical_path = some_other_function_of(resource, request)
The default context URL generator is available for perusal as the class
-:class:`pyramid.traversal.TraversalContextURL` in the `traversal module
+:class:`pyramid.traversal.ResourceURL` in the `traversal module
<http://github.com/Pylons/pyramid/blob/master/pyramid/traversal.py>`_ of the
:term:`Pylons` GitHub Pyramid repository.
+See :meth:`pyramid.config.add_resource_url_adapter` for more information.
+
.. index::
single: IResponse
single: special view responses
@@ -606,24 +601,24 @@ adapter to the more complex IResponse interface:
If you want to implement your own Response object instead of using the
:class:`pyramid.response.Response` object in any capacity at all, you'll have
to make sure the object implements every attribute and method outlined in
-:class:`pyramid.interfaces.IResponse` and you'll have to ensure that it's
-marked up with ``zope.interface.implements(IResponse)``:
+:class:`pyramid.interfaces.IResponse` and you'll have to ensure that it uses
+``zope.interface.implementer(IResponse)`` as a class decoratoror.
.. code-block:: python
:linenos:
from pyramid.interfaces import IResponse
- from zope.interface import implements
+ from zope.interface import implementer
+ @implementer(IResponse)
class MyResponse(object):
- implements(IResponse)
# ... an implementation of every method and attribute
# documented in IResponse should follow ...
When an alternate response object implementation is returned by a view
callable, if that object asserts that it implements
:class:`~pyramid.interfaces.IResponse` (via
-``zope.interface.implements(IResponse)``) , an adapter needn't be registered
+``zope.interface.implementer(IResponse)``) , an adapter needn't be registered
for the object; Pyramid will use it directly.
An IResponse adapter for ``webob.Response`` (as opposed to
@@ -812,14 +807,15 @@ performed, enabling you to set up the utility in advance:
.. code-block:: python
:linenos:
+ from zope.interface import implementer
+
from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from mypackage.interfaces import IMyUtility
+ @implementer(IMyUtility)
class UtilityImplementation:
- implements(IMyUtility)
-
def __init__(self):
self.registrations = {}
diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst
index 11d779854..08cc430f6 100644
--- a/docs/narr/introspector.rst
+++ b/docs/narr/introspector.rst
@@ -529,6 +529,21 @@ introspectables in categories not described here.
A normalized version of the ``spec`` argument provided to
``add_static_view``.
+``traversers``
+
+ Each introspectable in the ``traversers`` category represents a call to
+ :meth:`pyramid.config.Configurator.add_traverser`; each will have the
+ following data.
+
+ ``iface``
+
+ The (resolved) interface or class object that represents the return value
+ of a root factory that this traverser will be used for.
+
+ ``factory``
+
+ The (resolved) traverser class.
+
Introspection in the Toolbar
----------------------------
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index ea0045ca7..4566a4fb8 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -98,7 +98,7 @@ Or on Windows:
.. code-block:: text
- $ Scripts\pcreate alchemy MyProject
+ $ Scripts\pcreate -s alchemy MyProject
Here's sample output from a run of ``pcreate`` on UNIX for a project we name
``MyProject``:
@@ -322,9 +322,26 @@ image again.
.. image:: project-debug.png
+If you don't see the debug toolbar image on the right hand top of the page,
+it means you're browsing from a system that does not have debugging access.
+By default, for security reasons, only a browser originating from
+``localhost`` (``127.0.0.1``) can see the debug toolbar. To allow your
+browser on a remote system to access the server, add the a line within the
+``[app:main]`` section of the ``development.ini`` file in the form
+``debugtoolbar.hosts = X.X.X.X``. For example, if your Pyramid application
+is running on a remote system, and you're browsing from a host with the IP
+address ``192.168.1.1``, you'd add something like this to enable the toolbar
+when your system contacts Pyramid:
+
+.. code-block:: ini
+
+ [app:main]
+ # .. other settings ...
+ debugtoolbar.hosts = 192.168.1.1
+
For more information about what the debug toolbar allows you to do, see `the
documentation for pyramid_debugtoolbar
-<http://docs.pylonsproject.org/projects/pyramid_debugtoolbar/dev/>`_.
+<http://docs.pylonsproject.org/projects/pyramid_debugtoolbar/en/latest/>`_.
The debug toolbar will not be shown (and all debugging will be turned off)
when you use the ``production.ini`` file instead of the ``development.ini``
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index ed391f4fe..1f1b1943b 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -156,7 +156,6 @@ dictionary:
.. code-block:: python
:linenos:
- from pyramid.response import Response
from pyramid.view import view_config
@view_config(renderer='string')
@@ -193,7 +192,6 @@ render the returned dictionary to a JSON serialization:
.. code-block:: python
:linenos:
- from pyramid.response import Response
from pyramid.view import view_config
@view_config(renderer='json')
@@ -335,15 +333,15 @@ dictionary, an error will be raised.
Before passing keywords to the template, the keyword arguments derived from
the dictionary returned by the view are augmented. The callable object --
-whatever object was used to define the view -- will be automatically
-inserted into the set of keyword arguments passed to the template as the
-``view`` keyword. If the view callable was a class, the ``view`` keyword
-will be an instance of that class. Also inserted into the keywords passed to
-the template are ``renderer_name`` (the string used in the ``renderer``
-attribute of the directive), ``renderer_info`` (an object containing
-renderer-related information), ``context`` (the context resource of the view
-used to render the template), and ``request`` (the request passed to the view
-used to render the template).
+whatever object was used to define the view -- will be automatically inserted
+into the set of keyword arguments passed to the template as the ``view``
+keyword. If the view callable was a class, the ``view`` keyword will be an
+instance of that class. Also inserted into the keywords passed to the
+template are ``renderer_name`` (the string used in the ``renderer`` attribute
+of the directive), ``renderer_info`` (an object containing renderer-related
+information), ``context`` (the context resource of the view used to render
+the template), and ``request`` (the request passed to the view used to render
+the template). ``request`` is also available as ``req`` in Pyramid 1.3+.
Here's an example view configuration which uses a Chameleon ZPT renderer:
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index 256f69fc3..a24c44f29 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -303,13 +303,22 @@ The ``__resource_url__`` hook is passed two arguments: ``request`` and
two keys:
``physical_path``
- The "physical path" computed for the resource, as defined by
- ``pyramid.traversal.resource_path(resource)``.
+ A string representing the "physical path" computed for the resource, as
+ defined by ``pyramid.traversal.resource_path(resource)``. It will begin
+ and end with a slash.
``virtual_path``
- The "virtual path" computed for the resource, as defined by
- :ref:`virtual_root_support`. This will be identical to the physical path
- if virtual rooting is not enabled.
+ A string representing the "virtual path" computed for the resource, as
+ defined by :ref:`virtual_root_support`. This will be identical to the
+ physical path if virtual rooting is not enabled. It will begin and end
+ with a slash.
+
+``app_url``
+ A string representing the application URL generated during
+ ``request.resource_url``. It will not end with a slash. It represents a
+ potentially customized URL prefix, containing potentially custom scheme,
+ host and port information passed by the user to ``request.resource_url``.
+ It should be preferred over use of ``request.application_url``.
The ``__resource_url__`` method of a resource should return a string
representing a URL. If it cannot override the default, it should return
@@ -322,16 +331,16 @@ Here's an example ``__resource_url__`` method.
class Resource(object):
def __resource_url__(self, request, info):
- return request.application_url + info['virtual_path']
+ return info['app_url'] + info['virtual_path']
The above example actually just generates and returns the default URL, which
-would have been what was returned anyway, but your code can perform arbitrary
-logic as necessary. For example, your code may wish to override the hostname
-or port number of the generated URL.
+would have been what was generated by the default ``resource_url`` machinery,
+but your code can perform arbitrary logic as necessary. For example, your
+code may wish to override the hostname or port number of the generated URL.
Note that the URL generated by ``__resource_url__`` should be fully
qualified, should end in a slash, and should not contain any query string or
-anchor elements (only path elements) to work best with
+anchor elements (only path elements) to work with
:meth:`~pyramid.request.Request.resource_url`.
.. index::
@@ -540,14 +549,14 @@ declares that the blog entry implements an :term:`interface`.
:linenos:
import datetime
- from zope.interface import implements
+ from zope.interface import implementer
from zope.interface import Interface
class IBlogEntry(Interface):
pass
+ @implementer(IBlogEntry)
class BlogEntry(object):
- implements(IBlogEntry)
def __init__(self, title, body, author):
self.title = title
self.body = body
@@ -556,15 +565,15 @@ declares that the blog entry implements an :term:`interface`.
This resource consists of two things: the class which defines the resource
constructor as the class ``BlogEntry``, and an :term:`interface` attached to
-the class via an ``implements`` statement at class scope using the
-``IBlogEntry`` interface as its sole argument.
+the class via an ``implementer`` class decorator using the ``IBlogEntry``
+interface as its sole argument.
The interface object used must be an instance of a class that inherits from
:class:`zope.interface.Interface`.
A resource class may implement zero or more interfaces. You specify that a
resource implements an interface by using the
-:func:`zope.interface.implements` function at class scope. The above
+:func:`zope.interface.implementer` function as a class decorator. The above
``BlogEntry`` resource implements the ``IBlogEntry`` interface.
You can also specify that a particular resource *instance* provides an
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index 8c5d950c1..8e7f93a1b 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -488,20 +488,21 @@ you must create an interface and mark up your resource classes or instances
with interface declarations that refer to this interface.
To attach an interface to a resource *class*, you define the interface and
-use the :func:`zope.interface.implements` function to associate the interface
-with the class.
+use the :func:`zope.interface.implementer` class decorator to associate the
+interface with the class.
.. code-block:: python
:linenos:
from zope.interface import Interface
- from zope.interface import implements
+ from zope.interface import implementer
class IHello(Interface):
""" A marker interface """
+ @implementer(IHello)
class Hello(object):
- implements(IHello)
+ pass
To attach an interface to a resource *instance*, you define the interface and
use the :func:`zope.interface.alsoProvides` function to associate the
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 6d9dfdd92..a7bf74786 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -340,8 +340,8 @@ The above pattern will match these URLs, generating the following matchdicts:
.. code-block:: text
- foo/1/2/ -> {'baz':u'1', 'bar':u'2', 'fizzle':()}
- foo/abc/def/a/b/c -> {'baz':u'abc', 'bar':u'def', 'fizzle': u'a/b/c')}
+ foo/1/2/ -> {'baz':u'1', 'bar':u'2', 'fizzle':u''}
+ foo/abc/def/a/b/c -> {'baz':u'abc', 'bar':u'def', 'fizzle': u'a/b/c'}
This occurs because the default regular expression for a marker is ``[^/]+``
which will match everything up to the first ``/``, while ``{fizzle:.*}`` will
generated by cgit v1.2.3 (git 2.25.1) at 2026-04-28 06:36:19 +0000