From afa1cb6352fd39d8b0788c7708768aaca2974385 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Mon, 20 Dec 2010 23:33:08 -0700 Subject: promote parenthetical to an actual sentence, minor reword --- docs/narr/resources.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/resources.rst') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index fe1f760bb..4c2897ac8 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -3,8 +3,8 @@ Resources A :term:`resource` is an object that represents a "place" in a tree related to your application. Every :app:`Pyramid` application has at least one -resource object: the :term:`root` resource (even if you don't define one -manually, a default root resource is created for you). The root resource is +resource object: the :term:`root` resource. Even if you don't define a +root resource manually, a default one is created for you. The root resource is the root of a :term:`resource tree`. A resource tree is a set of nested dictionary-like objects which you can use to represent your website's structure. -- cgit v1.2.3 From 14575f52880028537594eb06b35f2b39dd9818c9 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Mon, 20 Dec 2010 23:37:39 -0700 Subject: reword, reorder paragraph for clarity --- docs/narr/resources.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) (limited to 'docs/narr/resources.rst') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 4c2897ac8..7b31a8260 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -1,21 +1,21 @@ Resources ========= -A :term:`resource` is an object that represents a "place" in a tree related -to your application. Every :app:`Pyramid` application has at least one -resource object: the :term:`root` resource. Even if you don't define a -root resource manually, a default one is created for you. The root resource is -the root of a :term:`resource tree`. A resource tree is a set of nested -dictionary-like objects which you can use to represent your website's -structure. +A :term:`resource` is an object that represents a "place" in a tree +related to your application. Every :app:`Pyramid` application has at +least one resource object: the :term:`root` resource. Even if you don't +define a root resource manually, a default one is created for you. The +root resource is the root of a :term:`resource tree`. A resource tree +is a set of nested dictionary-like objects which you can use to +represent your website's structure. In an application which uses :term:`traversal` to map URLs to code, the -resource tree structure is used heavily to map a URL to a :term:`view -callable`. :app:`Pyramid` will walk "up" the resource tree by traversing -through the nested dictionary structure of the tree when :term:`traversal` is -used in order to find a :term:`context` resource. Once a context resource is -found, the context resource and data in the request will be used to find a -:term:`view callable`. +resource tree structure is used heavily to map each URL to a :term:`view +callable`. When :term:`traversal` is used, :app:`Pyramid` will walk +through the resource tree by traversing through its nested dictionary +structure in order to find a :term:`context` resource. Once a context +resource is found, the context resource and data in the request will be +used to find a :term:`view callable`. In an application which uses :term:`URL dispatch`, the resource tree is only used indirectly, and is often "invisible" to the developer. In URL dispatch -- cgit v1.2.3 From 5f0a81a0fd40afcabd4e8f3185136f829193d4bc Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Mon, 20 Dec 2010 23:46:30 -0700 Subject: make it clear that leaf resource's __getitem__ must always raise KeyError --- docs/narr/resources.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/resources.rst') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 7b31a8260..6350f01ec 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -26,7 +26,7 @@ much less important in applications that use URL dispatch than applications that use traversal. In "Zope-like" :app:`Pyramid` applications, resource objects also often store -data persistently and offer methods related to mutating that persistent data. +data persistently, and offer methods related to mutating that persistent data. In these kinds of applications, resources not only represent the site structure of your website, but they become the :term:`domain model` of the application. @@ -72,8 +72,8 @@ tree: the container's ``__getitem__`` should return the sub-resource. - Leaf resources, which do not contain other resources, must not implement a - ``__getitem__``, or if they do, their ``__getitem__`` method must raise a - :exc:`KeyError`. + ``__getitem__``, or if they do, their ``__getitem__`` method must always + raise a :exc:`KeyError`. See :ref:`traversal_chapter` for more information about how traversal works against resource instances. -- cgit v1.2.3 From c661f30d1ad82baedb2847d5ba65b8f85311e9e5 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Tue, 21 Dec 2010 00:01:07 -0700 Subject: remove word typically to improve flow --- docs/narr/resources.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/resources.rst') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 6350f01ec..2485689a4 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -239,7 +239,7 @@ A slash is appended to all resource URLs when :func:`~pyramid.url.resource_url` is used to generate them in this simple manner, because resources are "places" in the hierarchy, and URLs are meant to be clicked on to be visited. Relative URLs that you include on HTML pages -rendered as the result of the default view of a resource are typically more +rendered as the result of the default view of a resource are more apt to be relative to these resources than relative to their parent. You can also pass extra elements to :func:`~pyramid.url.resource_url`: -- cgit v1.2.3 From 4a10119ecd49316b38c556ef720b515a0c5f7a22 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Tue, 21 Dec 2010 00:07:36 -0700 Subject: add missing space --- docs/narr/resources.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/resources.rst') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 2485689a4..69dbc0af6 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -399,7 +399,7 @@ Obtaining the Lineage of a Resource ----------------------------------- :func:`pyramid.location.lineage` returns a generator representing the -:term:`lineage` of the :term:`location` aware:term:`resource` object. +:term:`lineage` of the :term:`location` aware :term:`resource` object. The :func:`~pyramid.location.lineage` function returns the resource it is passed, then each parent of the resource, in order. For example, if the -- cgit v1.2.3 From a827e04ac308f8005f674bef01d70a842be708cf Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 23 Dec 2010 13:20:39 -0500 Subject: note __resource_url__ requirements --- docs/narr/resources.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/narr/resources.rst') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index f90b1eb12..ac88afdfd 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -324,6 +324,11 @@ 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. +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 +:func:`pyramid.url.resource_url`. + Generating the Path To a Resource --------------------------------- -- cgit v1.2.3 From 203e848985fca05263893132896b552ccbeaa4b0 Mon Sep 17 00:00:00 2001 From: Marius Gedminas Date: Wed, 29 Dec 2010 01:36:06 +0200 Subject: Markup fix. --- docs/narr/resources.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/resources.rst') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index ac88afdfd..3962e9e00 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -404,7 +404,7 @@ Obtaining the Lineage of a Resource ----------------------------------- :func:`pyramid.location.lineage` returns a generator representing the -:term:`lineage` of the :term:`location` aware:term:`resource` object. +:term:`lineage` of the :term:`location` aware :term:`resource` object. The :func:`~pyramid.location.lineage` function returns the resource it is passed, then each parent of the resource, in order. For example, if the -- cgit v1.2.3 From 5e2c481dda9c69477749693c3563255b94f25990 Mon Sep 17 00:00:00 2001 From: Marius Gedminas Date: Wed, 29 Dec 2010 01:41:55 +0200 Subject: Whitespace bigotry. --- docs/narr/resources.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/resources.rst') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 3962e9e00..8cf2cead2 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -533,7 +533,7 @@ declares that the blog entry implements an :term:`interface`. implements(IBlogEntry) def __init__(self, title, body, author): self.title = title - self.body = body + self.body = body self.author = author self.created = datetime.datetime.now() @@ -568,7 +568,7 @@ To do so, use the :func:`zope.interface.directlyProvides` function: class BlogEntry(object): def __init__(self, title, body, author): self.title = title - self.body = body + self.body = body self.author = author self.created = datetime.datetime.now() @@ -596,7 +596,7 @@ the :func:`zope.interface.alsoProvides` function: class BlogEntry(object): def __init__(self, title, body, author): self.title = title - self.body = body + self.body = body self.author = author self.created = datetime.datetime.now() -- cgit v1.2.3 From f7c36724a22cb951f2c6cc7cdd49602be6506873 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 3 Jan 2011 02:23:42 -0500 Subject: edit much ado chapter --- docs/narr/resources.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr/resources.rst') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index b892cf3cd..cf13f8c8d 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -1,3 +1,5 @@ +.. _resources_chapter: + Resources ========= -- cgit v1.2.3 From 5d23bd01db7ba99975a2f6c7205c2f1cd838ee52 Mon Sep 17 00:00:00 2001 From: tomlikestorock Date: Sat, 8 Jan 2011 11:44:46 -0800 Subject: fixing typo --- docs/narr/resources.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/resources.rst') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index ac88afdfd..da1933190 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -184,7 +184,7 @@ you will reach the filesystem root directory. objects "by hand". Instead, as necessary, during traversal :app:`Pyramid` will wrap each resource (even the root resource) in a ``LocationProxy`` which will dynamically assign a ``__name__`` and a ``__parent__`` to the - traversed resrouce (based on the last traversed resource and the name + traversed resource (based on the last traversed resource and the name supplied to ``__getitem__``). The root resource will have a ``__name__`` attribute of ``None`` and a ``__parent__`` attribute of ``None``. -- cgit v1.2.3 From c88d441533c46c80d3e08572013973446308ebd5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 21 Jan 2011 04:04:45 -0500 Subject: - Added "What's New in Pyramid 1.0" chapter to HTML rendering of documentation. --- docs/narr/resources.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr/resources.rst') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index c97b4c676..895d6c1c6 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -205,6 +205,8 @@ In general, since so much :app:`Pyramid` infrastructure depends on location-aware resources, it's a good idea to make each resource in your tree location-aware. +.. _generating_the_url_of_a_resource: + .. index:: single: resource_url pair: generating; resource url -- cgit v1.2.3 From 70acd25f40f32fc6cbb3b5d38a695b8982b52a31 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 27 Jan 2011 23:06:55 -0500 Subject: module name contractions --- docs/narr/resources.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) (limited to 'docs/narr/resources.rst') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 895d6c1c6..4fc7e037e 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -36,8 +36,8 @@ application. Also: - The ``context`` and ``containment`` predicate arguments to - :meth:`pyramid.config.Configurator.add_view` (or a - :func:`pyramid.view.view_config` decorator) reference a resource class + :meth:`~pyramid.config.Configurator.add_view` (or a + :func:`~pyramid.view.view_config` decorator) reference a resource class or resource :term:`interface`. - A :term:`root factory` returns a resource. @@ -46,7 +46,7 @@ Also: view. - Various helpful :app:`Pyramid` API methods expect a resource as an - argument (e.g. :func:`pyramid.url.resource_url` and others). + argument (e.g. :func:`~pyramid.url.resource_url` and others). .. index:: single: resource tree @@ -162,9 +162,9 @@ you will reach the filesystem root directory. .. warning:: If your root resource has a ``__name__`` argument that is not ``None`` or the empty string, URLs returned by the - :func:`pyramid.url.resource_url` function and paths generated by - the :func:`pyramid.traversal.resource_path` and - :func:`pyramid.traversal.resource_path_tuple` APIs will be + :func:`~pyramid.url.resource_url` function and paths generated by + the :func:`~pyramid.traversal.resource_path` and + :func:`~pyramid.traversal.resource_path_tuple` APIs will be generated improperly. The value of ``__name__`` will be prepended to every path and URL generated (as opposed to a single leading slash or empty tuple element). @@ -281,7 +281,7 @@ about virtually rooting a resource. The shortcut method of the :term:`request` named :meth:`pyramid.request.Request.resource_url` can be used instead of -:func:`pyramid.url.resource_url` to generate a resource URL. +:func:`~pyramid.url.resource_url` to generate a resource URL. For more information about generating resource URLs, see the documentation for :func:`pyramid.url.resource_url`. @@ -292,13 +292,13 @@ Overriding Resource URL Generation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If a resource object implements a ``__resource_url__`` method, this method -will be called when :func:`pyramid.url.resource_url` is called to generate a +will be called when :func:`~pyramid.url.resource_url` is called to generate a URL for the resource, overriding the default URL returned for the resource by :func:`~pyramid.url.resource_url`. The ``__resource_url__`` hook is passed two arguments: ``request`` and ``info``. ``request`` is the :term:`request` object passed to -:func:`pyramid.url.resource_url`. ``info`` is a dictionary with two +:func:`~pyramid.url.resource_url`. ``info`` is a dictionary with two keys: ``physical_path`` @@ -331,7 +331,7 @@ 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 -:func:`pyramid.url.resource_url`. +:func:`~pyramid.url.resource_url`. Generating the Path To a Resource --------------------------------- @@ -350,7 +350,7 @@ character. If ``resource`` in the example above was accessible in the tree as ``root['a']['b']``, the above example would generate the string ``/a/b``. -Any positional arguments passed in to :func:`pyramid.traversal.resource_path` +Any positional arguments passed in to :func:`~pyramid.traversal.resource_path` will be appended as path segments to the end of the resource path. .. code-block:: python @@ -618,7 +618,7 @@ configuration, see :ref:`using_resource_interfaces`. Finding a Resource With a Class or Interface in Lineage ------------------------------------------------------- -Use the :func:`pyramid.traversal.find_interface` API to locate a parent that +Use the :func:`~pyramid.traversal.find_interface` API to locate a parent that is of a particular Python class, or which implements some :term:`interface`. For example, if your resource tree is composed as follows: @@ -669,7 +669,7 @@ These can be used to walk down a resource tree, or conveniently locate one resource "inside" another. Some APIs in :ref:`security_module` accept a resource object as a parameter. -For example, the :func:`pyramid.security.has_permission` API accepts a +For example, the :func:`~pyramid.security.has_permission` API accepts a resource object as one of its arguments; the ACL is obtained from this resource or one of its ancestors. Other APIs in the :mod:`pyramid.security` module also accept :term:`context` as an argument, and a context is always a -- cgit v1.2.3 From a42a1efebd872f21c2fa96382248a2459cfb483c Mon Sep 17 00:00:00 2001 From: Kyle Johnson Date: Fri, 28 Jan 2011 20:16:49 -0800 Subject: minor grammar fixes ('a' vs 'an') --- docs/narr/resources.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/resources.rst') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 4fc7e037e..90dd34bfe 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -231,7 +231,7 @@ The simplest call to :func:`~pyramid.url.resource_url` looks like this: url = resource_url(resource, request) The ``request`` passed to ``resource_url`` in the above example is an -instance of an :app:`Pyramid` :term:`request` object. +instance of a :app:`Pyramid` :term:`request` object. If the resource referred to as ``resource`` in the above example was the root resource, and the host that was used to contact the server was -- cgit v1.2.3 From a9ff226bdeaa43d03759e9605cb8b51fb961979b Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 30 Jan 2011 18:34:11 -0500 Subject: fix references --- docs/narr/resources.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/resources.rst') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 90dd34bfe..a11466a87 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -205,12 +205,12 @@ In general, since so much :app:`Pyramid` infrastructure depends on location-aware resources, it's a good idea to make each resource in your tree location-aware. -.. _generating_the_url_of_a_resource: - .. index:: single: resource_url pair: generating; resource url +.. _generating_the_url_of_a_resource: + Generating The URL Of A Resource -------------------------------- -- cgit v1.2.3