From c595946b859e48ea506dd3155da935eba10a1ed7 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 14 Feb 2012 05:48:26 -0500 Subject: ignore venvs put into this dir --- docs/tutorials/.gitignore | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/tutorials/.gitignore (limited to 'docs') diff --git a/docs/tutorials/.gitignore b/docs/tutorials/.gitignore new file mode 100644 index 000000000..71e689620 --- /dev/null +++ b/docs/tutorials/.gitignore @@ -0,0 +1 @@ +env*/ -- cgit v1.2.3 From c6a299ad7159ffcabe201fa79f485c388d837971 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 14 Feb 2012 05:57:06 -0500 Subject: - Don't create a ``session`` instance in SQLA Wiki tutorial, use raw ``DBSession`` instead (this is more common in real SQLA apps). --- docs/tutorials/wiki2/authorization.rst | 4 ++-- docs/tutorials/wiki2/definingviews.rst | 8 ++++---- docs/tutorials/wiki2/src/authorization/tutorial/views.py | 13 +++++-------- docs/tutorials/wiki2/src/views/tutorial/views.py | 13 +++++-------- 4 files changed, 16 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index 56237a1b9..b1d0bf37c 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -159,14 +159,14 @@ logged in user and redirect back to the front page. The ``login`` view callable will look something like this: .. literalinclude:: src/authorization/tutorial/views.py - :lines: 90-116 + :lines: 87-113 :linenos: :language: python The ``logout`` view callable will look something like this: .. literalinclude:: src/authorization/tutorial/views.py - :lines: 118-122 + :lines: 115-119 :linenos: :language: python diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index bda0a2eb7..a067dbd66 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -126,7 +126,7 @@ HTML anchor for each *WikiWord* reference in the rendered HTML using a compiled regular expression. .. literalinclude:: src/views/tutorial/views.py - :lines: 23-44 + :lines: 23-43 :linenos: :language: python @@ -161,7 +161,7 @@ The ``matchdict`` attribute of the request passed to the ``add_page`` view will have the values we need to construct URLs and find model objects. .. literalinclude:: src/views/tutorial/views.py - :lines: 46-58 + :lines: 45-56 :linenos: :language: python @@ -184,7 +184,7 @@ If the view execution *is* a result of a form submission (if the expression ``'form.submitted' in request.params`` is ``True``), we scrape the page body from the form data, create a Page object with this page body and the name taken from ``matchdict['pagename']``, and save it into the database using -``session.add``. We then redirect back to the ``view_page`` view for the +``DBSession.add``. We then redirect back to the ``view_page`` view for the newly created page. The ``edit_page`` view function @@ -197,7 +197,7 @@ request passed to the ``edit_page`` view will have a ``'pagename'`` key matching the name of the page the user wants to edit. .. literalinclude:: src/views/tutorial/views.py - :lines: 60-73 + :lines: 58-70 :linenos: :language: python diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/views.py b/docs/tutorials/wiki2/src/authorization/tutorial/views.py index 375f1f5a5..087e6076b 100644 --- a/docs/tutorials/wiki2/src/authorization/tutorial/views.py +++ b/docs/tutorials/wiki2/src/authorization/tutorial/views.py @@ -33,14 +33,13 @@ def view_wiki(request): @view_config(route_name='view_page', renderer='templates/view.pt') def view_page(request): pagename = request.matchdict['pagename'] - session = DBSession() - page = session.query(Page).filter_by(name=pagename).first() + page = DBSession.query(Page).filter_by(name=pagename).first() if page is None: return HTTPNotFound('No such page') def check(match): word = match.group(1) - exists = session.query(Page).filter_by(name=word).all() + exists = DBSession.query(Page).filter_by(name=word).all() if exists: view_url = request.route_url('view_page', pagename=word) return '%s' % (view_url, word) @@ -59,10 +58,9 @@ def view_page(request): def add_page(request): name = request.matchdict['pagename'] if 'form.submitted' in request.params: - session = DBSession() body = request.params['body'] page = Page(name, body) - session.add(page) + DBSession.add(page) return HTTPFound(location = request.route_url('view_page', pagename=name)) save_url = request.route_url('add_page', pagename=name) @@ -74,11 +72,10 @@ def add_page(request): permission='edit') def edit_page(request): name = request.matchdict['pagename'] - session = DBSession() - page = session.query(Page).filter_by(name=name).one() + page = DBSession.query(Page).filter_by(name=name).one() if 'form.submitted' in request.params: page.data = request.params['body'] - session.add(page) + DBSession.add(page) return HTTPFound(location = request.route_url('view_page', pagename=name)) return dict( diff --git a/docs/tutorials/wiki2/src/views/tutorial/views.py b/docs/tutorials/wiki2/src/views/tutorial/views.py index 5c49dd2e8..c2a94a96b 100644 --- a/docs/tutorials/wiki2/src/views/tutorial/views.py +++ b/docs/tutorials/wiki2/src/views/tutorial/views.py @@ -23,14 +23,13 @@ def view_wiki(request): @view_config(route_name='view_page', renderer='templates/view.pt') def view_page(request): pagename = request.matchdict['pagename'] - session = DBSession() - page = session.query(Page).filter_by(name=pagename).first() + page = DBSession.query(Page).filter_by(name=pagename).first() if page is None: return HTTPNotFound('No such page') def check(match): word = match.group(1) - exists = session.query(Page).filter_by(name=word).all() + exists = DBSession.query(Page).filter_by(name=word).all() if exists: view_url = request.route_url('view_page', pagename=word) return '%s' % (view_url, word) @@ -47,10 +46,9 @@ def view_page(request): def add_page(request): name = request.matchdict['pagename'] if 'form.submitted' in request.params: - session = DBSession() body = request.params['body'] page = Page(name, body) - session.add(page) + DBSession.add(page) return HTTPFound(location = request.route_url('view_page', pagename=name)) save_url = request.route_url('add_page', pagename=name) @@ -60,11 +58,10 @@ def add_page(request): @view_config(route_name='edit_page', renderer='templates/edit.pt') def edit_page(request): name = request.matchdict['pagename'] - session = DBSession() - page = session.query(Page).filter_by(name=name).one() + page = DBSession.query(Page).filter_by(name=name).one() if 'form.submitted' in request.params: page.data = request.params['body'] - session.add(page) + DBSession.add(page) return HTTPFound(location = request.route_url('view_page', pagename=name)) return dict( -- cgit v1.2.3 From 9bdb099a5f5cb9f70c1bc60c2e2f58d6bc6f5c28 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 14 Feb 2012 06:59:28 -0500 Subject: add note about debugtoolbar.hosts --- docs/narr/project.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index d69f0cf13..66643af73 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -322,6 +322,22 @@ 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] + debugtoolbar.hosts = 192.168.1.1 + For more information about what the debug toolbar allows you to do, see `the documentation for pyramid_debugtoolbar `_. -- cgit v1.2.3 From 72bb7174bb4a4c4547828ab20d3b174b35200e47 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 14 Feb 2012 07:00:39 -0500 Subject: denote other settings --- docs/narr/project.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 66643af73..d626667ca 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -336,6 +336,7 @@ 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 -- cgit v1.2.3 From 2f35a1e938b7f4e9ad182f1ead415632769345d6 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 14 Feb 2012 07:10:43 -0500 Subject: use the newer url --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index d626667ca..4566a4fb8 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -341,7 +341,7 @@ when your system contacts Pyramid: For more information about what the debug toolbar allows you to do, see `the documentation for pyramid_debugtoolbar -`_. +`_. 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`` -- cgit v1.2.3 From 2e7f0cfb4c5f0a4804e0c44cdf181c2ee35b020a Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 15 Feb 2012 16:18:06 -0500 Subject: remove unused imports --- docs/narr/renderers.rst | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index ed391f4fe..67354a1ed 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') -- cgit v1.2.3 From 1ca5b34f17ea889f705c1120a5b8878bff16ec63 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 15 Feb 2012 16:23:59 -0500 Subject: - Replace all mentions of zope.interface.implements with zope.interface.implementer. --- docs/narr/hooks.rst | 15 ++++++++------- docs/narr/resources.rst | 10 +++++----- docs/narr/traversal.rst | 9 +++++---- 3 files changed, 18 insertions(+), 16 deletions(-) (limited to 'docs') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index fd6544416..350b5734d 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -606,24 +606,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 +812,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/resources.rst b/docs/narr/resources.rst index 256f69fc3..83734be9f 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -540,14 +540,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 +556,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 -- cgit v1.2.3 From 748aad47f90136b151be13f477ed6af1caed0493 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 15 Feb 2012 19:09:08 -0500 Subject: - Add ``pyramid.config.Configurator.set_traverser`` API method. See the Hooks narrative documentation section entitled "Changing the Traverser" for more information. This is not a new feature, it just provides an API for adding a traverser without needing to use the ZCA API. --- docs/api/config.rst | 2 ++ docs/narr/hooks.rst | 14 ++++++-------- docs/narr/introspector.rst | 15 +++++++++++++++ 3 files changed, 23 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/api/config.rst b/docs/api/config.rst index d16930cc0..3c5ee563a 100644 --- a/docs/api/config.rst +++ b/docs/api/config.rst @@ -94,6 +94,8 @@ .. automethod:: set_notfound_view + .. automethod:: set_traverser + .. automethod:: set_renderer_globals_factory(factory) .. attribute:: introspectable diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 350b5734d..076f9fa5c 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 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 ---------------------------- -- cgit v1.2.3 From f9bcf47164a151587244deb3ce5334ba447e3b99 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 15 Feb 2012 19:13:58 -0500 Subject: update whatsnew --- docs/whatsnew-1.3.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'docs') diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst index b6cfde039..918870018 100644 --- a/docs/whatsnew-1.3.rst +++ b/docs/whatsnew-1.3.rst @@ -259,6 +259,30 @@ Minor Feature Additions http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for more information about how to use the ``ignore`` argument to ``scan``. +- Add :meth:`pyramid.config.Configurator.set_traverser` API method. See + :ref:`changing_the_traverser` for more information. This is not a new + feature, it just provides an API for adding a traverser without needing to + use the ZCA API. + +- The :meth:`pyramid.config.Configurator.scan` method can now be passed an + ``ignore`` argument, which can be a string, a callable, or a list + consisting of strings and/or callables. This feature allows submodules, + subpackages, and global objects from being scanned. See + http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for + more information about how to use the ``ignore`` argument to ``scan``. + +- Better error messages when a view callable returns a value that cannot be + converted to a response (for example, when a view callable returns a + dictionary without a renderer defined, or doesn't return any value at all). + The error message now contains information about the view callable itself + as well as the result of calling it. + +- Better error message when a .pyc-only module is ``config.include`` -ed. + This is not permitted due to error reporting requirements, and a better + error message is shown when it is attempted. Previously it would fail with + something like "AttributeError: 'NoneType' object has no attribute + 'rfind'". + Backwards Incompatibilities --------------------------- @@ -375,6 +399,8 @@ Dependency Changes - Pyramid no longer depends on the ``Paste`` or ``PasteScript`` packages. These packages are not Python 3 compatible. +- Depend on ``venusian`` >= 1.0a3 to provide scan ``ignore`` support. + Scaffolding Changes ------------------- -- cgit v1.2.3 From 4786cae2e7a053b01091b5e185102f9c26885b08 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 15 Feb 2012 19:32:46 -0500 Subject: - The system value ``r`` is now supplied to renderers as an alias for ``request``. This means that you can now, for example, in a template, do ``r.route_url(...)`` instead of ``request.route_url(...)``. Fixes #413. --- docs/narr/renderers.rst | 18 +++++++++--------- docs/whatsnew-1.3.rst | 7 ++++++- 2 files changed, 15 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 67354a1ed..1622f1f29 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -333,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 ``r`` in Pyramid 1.3+. Here's an example view configuration which uses a Chameleon ZPT renderer: diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst index 918870018..c4bde2b54 100644 --- a/docs/whatsnew-1.3.rst +++ b/docs/whatsnew-1.3.rst @@ -54,7 +54,8 @@ to make some changes: - We've replaced the ``paster`` command with Pyramid-specific analogues. -- We've made the default WSGI server the ``waitress`` server. +- We've made the default WSGI server used by Pyramid scaffolding the + :term:`waitress` server. Previously (in Pyramid 1.0, 1.1 and 1.2), you created a Pyramid application using ``paster create``, like so:: @@ -283,6 +284,10 @@ Minor Feature Additions something like "AttributeError: 'NoneType' object has no attribute 'rfind'". +- The system value ``r`` is now supplied to renderers as an alias for + ``request``. This means that you can now, for example, in a template, do + ``r.route_url(...)`` instead of ``request.route_url(...)``. + Backwards Incompatibilities --------------------------- -- cgit v1.2.3 From b2ea4c88b8b3bc9ed657160d8a888780d6c41844 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 15 Feb 2012 22:06:30 -0500 Subject: Use req instead of r for #413. It's more likely that somebody is already passing something named r, and a template may depend on its existence or nonexistence to conditionalize rendering a bit of html. --- docs/narr/renderers.rst | 2 +- docs/whatsnew-1.3.rst | 7 +++++-- 2 files changed, 6 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 1622f1f29..1f1b1943b 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -341,7 +341,7 @@ 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 ``r`` in Pyramid 1.3+. +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/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst index c4bde2b54..a27ef6af9 100644 --- a/docs/whatsnew-1.3.rst +++ b/docs/whatsnew-1.3.rst @@ -284,9 +284,12 @@ Minor Feature Additions something like "AttributeError: 'NoneType' object has no attribute 'rfind'". -- The system value ``r`` is now supplied to renderers as an alias for +- The system value ``req`` is now supplied to renderers as an alias for ``request``. This means that you can now, for example, in a template, do - ``r.route_url(...)`` instead of ``request.route_url(...)``. + ``req.route_url(...)`` instead of ``request.route_url(...)``. This is + purely a change to reduce the amount of typing required to use request + methods and attributes from within templates. The value ``request`` is + still available too, this is just an alternative. Backwards Incompatibilities --------------------------- -- cgit v1.2.3 From c51896756eeffc7e8c50ad71300ec355ae47465a Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 17 Feb 2012 01:08:42 -0500 Subject: Features -------- - Add ``pyramid.config.Configurator.add_resource_url_adapter`` API method. See the Hooks narrative documentation section entitled "Changing How pyramid.request.Request.resource_url Generates a URL" for more information. This is not a new feature, it just provides an API for adding a resource url adapter without needing to use the ZCA API. - A new interface was added: ``pyramid.interfaces.IResourceURL``. An adapter implementing its interface can be used to override resource URL generation when ``request.resource_url`` is called. This interface replaces the now-deprecated ``pyramid.interfaces.IContextURL`` interface. - The dictionary passed to a resource's ``__resource_url__`` method (see "Overriding Resource URL Generation" in the "Resources" chapter) now contains an ``app_url`` key, representing the application URL generated during ``request.resource_url``. 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 used instead of ``request.application_url`` where necessary. - The ``request.resource_url`` API now accepts these arguments: ``app_url``, ``scheme``, ``host``, and ``port``. The app_url argument can be used to replace the URL prefix wholesale during url generation. The ``scheme``, ``host``, and ``port`` arguments can be used to replace the respective default values of ``request.application_url`` partially. - A new API named ``request.resource_path`` now exists. It works like ``request.resource_url`` but produces a relative URL rather than an absolute one. - The ``request.route_url`` API now accepts these arguments: ``_app_url``, ``_scheme``, ``_host``, and ``_port``. The ``_app_url`` argument can be used to replace the URL prefix wholesale during url generation. The ``_scheme``, ``_host``, and ``_port`` arguments can be used to replace the respective default values of ``request.application_url`` partially. Backwards Incompatibilities --------------------------- - The ``pyramid.interfaces.IContextURL`` interface has been deprecated. People have been instructed to use this to register a resource url adapter in the "Hooks" chapter to use to influence ``request.resource_url`` URL generation for resources found via custom traversers since Pyramid 1.0. The interface still exists and registering such an adapter still works, but this interface will be removed from the software after a few major Pyramid releases. You should replace it with an equivalent ``pyramid.interfaces.IResourceURL`` adapter, registered using the new ``pyramid.config.Configurator.add_resource_url_adapter`` API. A deprecation warning is now emitted when a ``pyramid.interfaces.IContextURL`` adapter is found when ``request.resource_url`` is called. Misc ---- - Change ``set_traverser`` API name to ``add_traverser``. Ref #438. --- docs/api/config.rst | 2 +- docs/api/interfaces.rst | 4 ++++ docs/api/request.rst | 2 ++ docs/narr/hooks.rst | 59 +++++++++++++++++++++++-------------------------- docs/whatsnew-1.3.rst | 56 ++++++++++++++++++++++++++++++++++++++++++++-- 5 files changed, 89 insertions(+), 34 deletions(-) (limited to 'docs') diff --git a/docs/api/config.rst b/docs/api/config.rst index 3c5ee563a..3fc2cfc44 100644 --- a/docs/api/config.rst +++ b/docs/api/config.rst @@ -94,7 +94,7 @@ .. automethod:: set_notfound_view - .. automethod:: set_traverser + .. automethod:: add_traverser .. automethod:: set_renderer_globals_factory(factory) diff --git a/docs/api/interfaces.rst b/docs/api/interfaces.rst index 11cd8cf7e..1dea5fab0 100644 --- a/docs/api/interfaces.rst +++ b/docs/api/interfaces.rst @@ -79,3 +79,7 @@ Other Interfaces .. autointerface:: IAssetDescriptor :members: + + .. autointerface:: IResourceURL + :members: + diff --git a/docs/api/request.rst b/docs/api/request.rst index 1ab84e230..e1b233fbc 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -183,6 +183,8 @@ .. automethod:: resource_url + .. automethod:: resource_path + .. attribute:: response_* In Pyramid 1.0, you could set attributes on a diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 076f9fa5c..2c4310080 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -479,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 `_ 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 diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst index a27ef6af9..7d1c9217d 100644 --- a/docs/whatsnew-1.3.rst +++ b/docs/whatsnew-1.3.rst @@ -260,16 +260,21 @@ Minor Feature Additions http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for more information about how to use the ``ignore`` argument to ``scan``. -- Add :meth:`pyramid.config.Configurator.set_traverser` API method. See +- Add :meth:`pyramid.config.Configurator.add_traverser` API method. See :ref:`changing_the_traverser` for more information. This is not a new feature, it just provides an API for adding a traverser without needing to use the ZCA API. +- Add :meth:`pyramid.config.Configurator.add_resource_url_adapter` API + method. See :ref:`changing_resource_url` for more information. This is + not a new feature, it just provides an API for adding a resource url + adapter without needing to use the ZCA API. + - The :meth:`pyramid.config.Configurator.scan` method can now be passed an ``ignore`` argument, which can be a string, a callable, or a list consisting of strings and/or callables. This feature allows submodules, subpackages, and global objects from being scanned. See - http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for + http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for more information about how to use the ``ignore`` argument to ``scan``. - Better error messages when a view callable returns a value that cannot be @@ -291,6 +296,38 @@ Minor Feature Additions methods and attributes from within templates. The value ``request`` is still available too, this is just an alternative. +- A new interface was added: :class:`pyramid.interfaces.IResourceURL`. An + adapter implementing its interface can be used to override resource URL + generation when :meth:`pyramid.request.Request.resource_url` is called. + This interface replaces the now-deprecated + ``pyramid.interfaces.IContextURL`` interface. + +- The dictionary passed to a resource's ``__resource_url__`` method (see + :ref:`overriding_resource_url_generation`) now contains an ``app_url`` key, + representing the application URL generated during + :meth:`pyramid.request.Request.resource_url`. 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 + used instead of ``request.application_url`` where necessary. + +- The :meth:`pyramid.request.Request.resource_url` API now accepts these + arguments: ``app_url``, ``scheme``, ``host``, and ``port``. The app_url + argument can be used to replace the URL prefix wholesale during url + generation. The ``scheme``, ``host``, and ``port`` arguments can be used + to replace the respective default values of ``request.application_url`` + partially. + +- A new API named :meth:`pyramid.request.Request.resource_path` now exists. + It works like :meth:`pyramid.request.Request.resource_url`` but produces a + relative URL rather than an absolute one. + +- The :meth:`pyramid.request.Request.route_url` API now accepts these + arguments: ``_app_url``, ``_scheme``, ``_host``, and ``_port``. The + ``_app_url`` argument can be used to replace the URL prefix wholesale + during url generation. The ``_scheme``, ``_host``, and ``_port`` arguments + can be used to replace the respective default values of + ``request.application_url`` partially. + Backwards Incompatibilities --------------------------- @@ -360,6 +397,21 @@ Backwards Incompatibilities no negative affect because the implementation was broken for dict-based arguments. +- The ``pyramid.interfaces.IContextURL`` interface has been deprecated. + People have been instructed to use this to register a resource url adapter + in the "Hooks" chapter to use to influence + :meth:`pyramid.request.Request.resource_url` URL generation for resources + found via custom traversers since Pyramid 1.0. + + The interface still exists and registering such an adapter still works, but + this interface will be removed from the software after a few major Pyramid + releases. You should replace it with an equivalent + :class:`pyramid.interfaces.IResourceURL` adapter, registered using the new + :meth:`pyramid.config.Configurator.add_resource_url_adapter` API. A + deprecation warning is now emitted when a + ``pyramid.interfaces.IContextURL`` adapter is found when + :meth:`pyramid.request.Request.resource_url` is called. + Documentation Enhancements -------------------------- -- cgit v1.2.3 From 0a6a26ca36f6aff7d03b438eef57f6b8d17123e9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 17 Feb 2012 08:55:45 -0500 Subject: docs fixes --- docs/narr/resources.rst | 29 +++++++++++++++++++---------- docs/whatsnew-1.3.rst | 2 +- 2 files changed, 20 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 83734be9f..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:: diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst index 7d1c9217d..674b16e11 100644 --- a/docs/whatsnew-1.3.rst +++ b/docs/whatsnew-1.3.rst @@ -274,7 +274,7 @@ Minor Feature Additions ``ignore`` argument, which can be a string, a callable, or a list consisting of strings and/or callables. This feature allows submodules, subpackages, and global objects from being scanned. See - http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for + http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for more information about how to use the ``ignore`` argument to ``scan``. - Better error messages when a view callable returns a value that cannot be -- cgit v1.2.3 From 305d23f9e9dd095f4fdface116a2155bd86a453c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 17 Feb 2012 18:29:10 -0500 Subject: docs fixes --- docs/whatsnew-1.3.rst | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst index 674b16e11..acb884d49 100644 --- a/docs/whatsnew-1.3.rst +++ b/docs/whatsnew-1.3.rst @@ -364,9 +364,10 @@ Backwards Incompatibilities and upgrade Pyramid itself "in-place"; it may simply break instead (particularly if you use ZCML's ``includeOverrides`` directive). -- String values passed to ``route_url`` or ``route_path`` that are meant to - replace "remainder" matches will now be URL-quoted except for embedded - slashes. For example:: +- String values passed to :meth:`Pyramid.request.Request.route_url` or + :meth:`Pyramid.request.Request.route_path` that are meant to replace + "remainder" matches will now be URL-quoted except for embedded slashes. For + example:: config.add_route('remain', '/foo*remainder') request.route_path('remain', remainder='abc / def') @@ -385,8 +386,8 @@ Backwards Incompatibilities ``route_path`` or ``route_url`` to do this now. - If you pass a bytestring that contains non-ASCII characters to - ``add_route`` as a pattern, it will now fail at startup time. Use Unicode - instead. + :meth:`pyramid.config.Configurator.add_route` as a pattern, it will now + fail at startup time. Use Unicode instead. - The ``path_info`` route and view predicates now match against ``request.upath_info`` (Unicode) rather than ``request.path_info`` @@ -403,10 +404,11 @@ Backwards Incompatibilities :meth:`pyramid.request.Request.resource_url` URL generation for resources found via custom traversers since Pyramid 1.0. - The interface still exists and registering such an adapter still works, but - this interface will be removed from the software after a few major Pyramid - releases. You should replace it with an equivalent - :class:`pyramid.interfaces.IResourceURL` adapter, registered using the new + The interface still exists and registering an adapter using it as + documented in older versions still works, but this interface will be + removed from the software after a few major Pyramid releases. You should + replace it with an equivalent :class:`pyramid.interfaces.IResourceURL` + adapter, registered using the new :meth:`pyramid.config.Configurator.add_resource_url_adapter` API. A deprecation warning is now emitted when a ``pyramid.interfaces.IContextURL`` adapter is found when -- cgit v1.2.3