Skip to content
master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 

pyramid-resource

Pyramid's URL traversal is a powerful tool and personally one of my favorite features of the framework. Unfortunately, Pyramid doesn't provide any framework or utilities for implementing resource trees. This project aims to reduce the boilerplate necessary for creating feature-full resource trees.

Basic usage

First, of course, you need to add pyramid-resource to your project using your package manager of choice. e.g.: pip install pyramid-resource

Make sure you're familiar with Pyramid's URL traversal.

You can create a new resource by subclassing pyramid_resource.Resource. For example, here's a simple application that has a resource tree with only a root resource.

from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from pyramid.response import Response
from pyramid_resource import Resource


class Root(Resource):
    pass


def hello_world(request):
    return Response('Hello!\n')


if __name__ == '__main__':
    with Configurator() as config:
        config.set_root_factory(Root)
        config.add_view(hello_world, context=Root)
        app = config.make_wsgi_app()
    server = make_server('0.0.0.0', 8080, app)
    server.serve_forever()

You can define child resources by setting the __children__ property to a dictionary. The key corresponds the URL segment and the value should be a resource subclass. pyramid-resource will automatically make the resources location-aware.

class Child(Resource):
    pass


class Root(Resource):
    __children__ = {
        'child': Child,
    }

You can see the full example here.

Name Resolution

For convenience, you can reference children as strings. Strings will be lazily resolved to a resource in the same module. This is useful for putting parent resources above child resources in your code, e.g.:

class Root(Resource):
    __children__ = {
        'child': 'Child',
    }


class Child(Resource):
    pass

You can also use zope.dottedname-style or pkg_resource-style references to resources in other packages, a la Configurator.maybe_dotted. These will resolve relative to the package of the parent resource.

class Root(Resource):
    __children__ = {
        'widget': '.widget.WidgetResource',
    }

Dynamic resource trees

One of the more interesting features of URL traversal is that trees can be created on the fly. This allows for dynamic resource trees that can mirror the application state, such as objects in a database.

Dynamic resource trees can be created by implementing a get_child method on a resource class. This method should accept a single argument of a URL segment and will be called if no child is found in the __children__ property. If the URL segment corresponds to a valid child resource, get_child should return a resource class and the child resource will be instanciated from that. If no corresponding child is found, None should be returned or KeyError raised, and traversal will be halted.

class Root(Resource):
    def get_child(self, key):
        if exists_in_db(key):
            return Child
        else:
            return None


class Child(Resource):
    pass

Of course, this isn't particularly useful if you can't attach information to the child resource. get_child can also return a two-tuple of a resource class and a dictionary of attributes that will be attached to the resulting child.

class Root(Resource):
    def get_child(self, key):
        if exists_in_db(key):
            return Child, {'id': key}


class Child(Resource):
    pass

The object ID will now be accessible via context.id in views on the child resource. Resources will proxy the attributes of their parent, so context.id will also be accessible in views further down the tree.

If you need to access the current request in your get_child implementations, it's available via self.request.

An example

Here's an example that demonstrates how a real application might utilize pyramid-resource.

from wsgiref.simple_server import make_server
from pyramid.decorator import reify
from pyramid.config import Configurator
from pyramid.view import view_config
from pyramid_resource import Resource


class Root(Resource):
    __children__ = {
        'widget': '.WidgetContainer',
    }


class WidgetContainer(Resource):
    """
    A resource containing the Widget resources.

    """
    def get_child(self, key):
        """
        Return a child resource if the widget exists in the database.

        """
        try:
            id = int(key)
        except ValueError:
            raise KeyError

        if self.request.widget_db.exists(id):
            return Widget, {'widget_id': id}


class Widget(Resource):
    """
    A resource representing a widget in the mock database.

    """
    @reify
    def widget(self):
        """
        Lookup the widget from the database.

        """
        return self.request.widget_db.find(self.widget_id)


@view_config(context=WidgetContainer, renderer='string')
def list_widgets(context, request):
    """
    GET /widget/

    List the URLs of all widgets.

    """
    urls = []
    for widget_id in request.widget_db:
        urls.append(request.resource_path(context[widget_id]))
    return '\n'.join(urls) + '\n'


@view_config(context=Widget, renderer='string')
def get_widget(context, request):
    """
    GET /widget/{id}/

    Greet the current widget.

    """
    return 'Hello {}!\n'.format(context.widget)


class MockDatabase:
    """
    An imitation of a widget database.

    """
    DATA = {
        1: 'Widget 1',
        2: 'Widget 2',
    }

    def exists(self, id):
        return id in self.DATA

    def find(self, id):
        return self.DATA[id]

    def __iter__(self):
        return iter(self.DATA.keys())


if __name__ == '__main__':
    with Configurator() as config:
        config.set_root_factory(Root)
        config.add_request_method(
            lambda _: MockDatabase(),
            'widget_db',
            property=True,
        )
        config.scan()
        app = config.make_wsgi_app()
    server = make_server('0.0.0.0', 8080, app)
    server.serve_forever()

The resulting application will behave like this:

>>> curl localhost:8080/widget/
> /widget/1/
> /widget/2/

>>> curl localhost:8080/widget/1/
> Hello Widget 1!

>>> curl localhost:8080/widget/2/
> Hello Widget 2!

Prior art

The pyramid_traversalwrapper project proxies a location-ignorant resource tree to make it location-aware.

About

A base resource class for Pyramid traversal

Resources

License

Packages

No packages published