Overview¶
Traversal quick overview¶
Note
Refer to request processing and traversal chapters in pyramid documentation for details.
Using traversal, requesting /users/hadrien/photos/
is treated as dict
accesses:
RootFactory(request)['users']['hadrien']['photos']
A root factory object configured using
pyramid.config.Configurator.set_root_factory()
is instantiated for each
request.
A traverser function locates the context by traversing resources tree using any
existing __getitem__
on the root object and subobjects.
When any of the __getitem__
call raises a KeyError
exception or
traverser reach the end of request’s PATH_INFO
, context is found.
Then pyramid’s router looks up a view callable using the context.
Collections and Items¶
Note
Refer to Creating a Pyramid Project for details on pyramid configuration.
A REST API is a tree of resources accessible via HTTP methods. Here is an example with 3 resources, user, photo and user photo:
root
├── photos Collection of photos /photos
│ └── {photo_id} Photo item /photos/123/
└── users Collection of users /users/
└── {user_id} User item /users/hadrien/
└── photos Collection of user's photos /users/hadrien/photos
Two ways to configure this tree of resources with royal:
Imperative using
config.add_resource
. By convention, directive will look for classes namedCollection
and/orItem
in sub modules.
example/resource/__init__.py
:def includeme(config): config.add_resource('users') config.add_resource('users.photos') config.add_resource('photos')
example/resource/users.py
,example/resource/users_photos.py
andexample/resource/photos.py
:import royal class Collection(royal.Collection): pass class Item(royal.Item): passDeclarative using
collection_config
anditem_config
decorator:import royal def incudeme(config): config.scan() @royal.collection_config('users') class Users(royal.Collection): def index(self, params): pass @royal.item_config('users') class User(royal.Item): def show(self, params): pass @royal.collection_config('users.photos') class UserPhotos(royal.Collection): pass @royal.item_config('users.photos') @royal.item_config('photos') class Photo(royal.Item): pass @royal.collection_config('photos') class Photos(royal.Collection): pass
TBD...