diff options
Diffstat (limited to 'docs/narr/resources.rst')
| -rw-r--r-- | docs/narr/resources.rst | 194 |
1 files changed, 97 insertions, 97 deletions
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 92139c0ff..6b79d575f 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -92,9 +92,9 @@ named ``'b'``, and ``'b'`` has a single child named ``'c'``, which has no children. It is therefore possible to access the ``'c'`` leaf resource like so: .. code-block:: python - :linenos: + :linenos: - root['a']['b']['c'] + root['a']['b']['c'] If you returned the above ``root`` object from a :term:`root factory`, the path ``/a/b/c`` would find the ``'c'`` object in the resource tree as the result of @@ -133,11 +133,11 @@ The ``__parent__`` of the root resource should be ``None`` and its ``__name__`` should be the empty string. For instance: .. code-block:: python - :linenos: + :linenos: - class MyRootResource(object): - __name__ = '' - __parent__ = None + class MyRootResource(object): + __name__ = '' + __parent__ = None A resource returned from the root resource's ``__getitem__`` method should have a ``__parent__`` attribute that is a reference to the root resource, and its @@ -222,9 +222,9 @@ The simplest call to :meth:`~pyramid.request.Request.resource_url` looks like this: .. code-block:: python - :linenos: + :linenos: - url = request.resource_url(resource) + url = request.resource_url(resource) The ``request`` in the above example is an instance of a :app:`Pyramid` :term:`request` object. @@ -246,9 +246,9 @@ You can also pass extra elements to :meth:`~pyramid.request.Request.resource_url`: .. code-block:: python - :linenos: + :linenos: - url = request.resource_url(resource, 'foo', 'bar') + url = request.resource_url(resource, 'foo', 'bar') 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 ``example.com``, @@ -261,9 +261,9 @@ elements are passed. You can also pass a query string: .. code-block:: python - :linenos: + :linenos: - url = request.resource_url(resource, query={'a':'1'}) + url = request.resource_url(resource, query={'a':'1'}) 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 ``example.com``, @@ -320,11 +320,11 @@ representing a URL. If it cannot override the default, it should return Here's an example ``__resource_url__`` method. .. code-block:: python - :linenos: + :linenos: - class Resource(object): - def __resource_url__(self, request, info): - return info['app_url'] + info['virtual_path'] + class Resource(object): + def __resource_url__(self, request, info): + return info['app_url'] + info['virtual_path'] The above example actually just generates and returns the default URL, which would have been what was generated by the default ``resource_url`` machinery, @@ -347,10 +347,10 @@ the absolute physical path of the resource object based on its position in the resource tree. Each segment of the path is separated with a slash character. .. code-block:: python - :linenos: + :linenos: - from pyramid.traversal import resource_path - url = resource_path(resource) + from pyramid.traversal import resource_path + url = resource_path(resource) If ``resource`` in the example above was accessible in the tree as ``root['a']['b']``, the above example would generate the string ``/a/b``. @@ -359,10 +359,10 @@ 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 - :linenos: + :linenos: - from pyramid.traversal import resource_path - url = resource_path(resource, 'foo', 'bar') + from pyramid.traversal import resource_path + url = resource_path(resource, 'foo', 'bar') If ``resource`` in the example above was accessible in the tree as ``root['a']['b']``, the above example would generate the string @@ -387,20 +387,20 @@ You can resolve an absolute path by passing a string prefixed with a ``/`` as the ``path`` argument: .. code-block:: python - :linenos: + :linenos: - from pyramid.traversal import find_resource - url = find_resource(anyresource, '/path') + from pyramid.traversal import find_resource + url = find_resource(anyresource, '/path') Or you can resolve a path relative to the resource that you pass in to :func:`pyramid.traversal.find_resource` by passing a string that isn't prefixed by ``/``: .. code-block:: python - :linenos: + :linenos: - from pyramid.traversal import find_resource - url = find_resource(anyresource, 'path') + from pyramid.traversal import find_resource + url = find_resource(anyresource, 'path') Often the paths you pass to :func:`~pyramid.traversal.find_resource` are generated by the :func:`~pyramid.traversal.resource_path` API. These APIs are @@ -427,22 +427,22 @@ passed into it, then each parent of the resource in order. For example, if the resource tree is composed like so: .. code-block:: python - :linenos: + :linenos: - class Thing(object): pass + class Thing(object): pass - thing1 = Thing() - thing2 = Thing() - thing2.__parent__ = thing1 + thing1 = Thing() + thing2 = Thing() + thing2.__parent__ = thing1 Calling ``lineage(thing2)`` will return a generator. When we turn it into a list, we will get: .. code-block:: python - :linenos: + :linenos: - list(lineage(thing2)) - [ <Thing object at thing2>, <Thing object at thing1> ] + list(lineage(thing2)) + [ <Thing object at thing2>, <Thing object at thing1> ] The generator returned by :func:`~pyramid.location.lineage` first returns unconditionally the resource that was passed into it. Then, if the resource @@ -464,13 +464,13 @@ is in the :term:`lineage` of another resource. For example, if the resource tree is: .. code-block:: python - :linenos: + :linenos: - class Thing(object): pass + class Thing(object): pass - a = Thing() - b = Thing() - b.__parent__ = a + a = Thing() + b = Thing() + b.__parent__ = a Calling ``inside(b, a)`` will return ``True``, because ``b`` has a lineage that includes ``a``. However, calling ``inside(a, b)`` will return ``False`` @@ -498,13 +498,13 @@ you want to find the root. For example, if the resource tree is: .. code-block:: python - :linenos: + :linenos: - class Thing(object): pass + class Thing(object): pass - a = Thing() - b = Thing() - b.__parent__ = a + a = Thing() + b = Thing() + b.__parent__ = a Calling ``find_root(b)`` will return ``a``. @@ -538,22 +538,22 @@ For example, here's some code which describes a blog entry which also declares that the blog entry implements an :term:`interface`. .. code-block:: python - :linenos: + :linenos: - import datetime - from zope.interface import implementer - from zope.interface import Interface + import datetime + from zope.interface import implementer + from zope.interface import Interface - class IBlogEntry(Interface): - pass + class IBlogEntry(Interface): + pass - @implementer(IBlogEntry) - class BlogEntry(object): - def __init__(self, title, body, author): - self.title = title - self.body = body - self.author = author - self.created = datetime.datetime.now() + @implementer(IBlogEntry) + class BlogEntry(object): + def __init__(self, title, body, author): + self.title = title + self.body = body + self.author = author + self.created = datetime.datetime.now() This resource consists of two things: the class which defines the resource constructor as the class ``BlogEntry``, and an :term:`interface` attached to @@ -575,24 +575,24 @@ However, you can also just say that a single object provides the interface. To do so, use the :func:`zope.interface.directlyProvides` function: .. code-block:: python - :linenos: + :linenos: - import datetime - from zope.interface import directlyProvides - from zope.interface import Interface + import datetime + from zope.interface import directlyProvides + from zope.interface import Interface - class IBlogEntry(Interface): - pass + class IBlogEntry(Interface): + pass - class BlogEntry(object): - def __init__(self, title, body, author): - self.title = title - self.body = body - self.author = author - self.created = datetime.datetime.now() + class BlogEntry(object): + def __init__(self, title, body, author): + self.title = title + self.body = body + self.author = author + self.created = datetime.datetime.now() - entry = BlogEntry('title', 'body', 'author') - directlyProvides(entry, IBlogEntry) + entry = BlogEntry('title', 'body', 'author') + directlyProvides(entry, IBlogEntry) :func:`zope.interface.directlyProvides` will replace any existing interface that was previously provided by an instance. If a resource object already has @@ -600,29 +600,29 @@ instance-level interface declarations that you don't want to replace, use the :func:`zope.interface.alsoProvides` function: .. code-block:: python - :linenos: + :linenos: - import datetime - from zope.interface import alsoProvides - from zope.interface import directlyProvides - from zope.interface import Interface + import datetime + from zope.interface import alsoProvides + from zope.interface import directlyProvides + from zope.interface import Interface - class IBlogEntry1(Interface): - pass + class IBlogEntry1(Interface): + pass - class IBlogEntry2(Interface): - pass + class IBlogEntry2(Interface): + pass - class BlogEntry(object): - def __init__(self, title, body, author): - self.title = title - self.body = body - self.author = author - self.created = datetime.datetime.now() + class BlogEntry(object): + def __init__(self, title, body, author): + self.title = title + self.body = body + self.author = author + self.created = datetime.datetime.now() - entry = BlogEntry('title', 'body', 'author') - directlyProvides(entry, IBlogEntry1) - alsoProvides(entry, IBlogEntry2) + entry = BlogEntry('title', 'body', 'author') + directlyProvides(entry, IBlogEntry1) + alsoProvides(entry, IBlogEntry2) :func:`zope.interface.alsoProvides` will augment the set of interfaces directly provided by an instance instead of overwriting them like @@ -643,14 +643,14 @@ is of a particular Python class, or which implements some :term:`interface`. For example, if your resource tree is composed as follows: .. code-block:: python - :linenos: + :linenos: - class Thing1(object): pass - class Thing2(object): pass + class Thing1(object): pass + class Thing2(object): pass - a = Thing1() - b = Thing2() - b.__parent__ = a + a = Thing1() + b = Thing2() + b.__parent__ = a Calling ``find_interface(a, Thing1)`` will return the ``a`` resource because ``a`` is of class ``Thing1`` (the resource passed as the first argument is |