Publish Python objects as RESTful resources over HTTP.
Project description
lazr.restful is a library for publishing Python objects through a RESTful web service. To tell lazr.restful which objects you want exposed and how, you annotate your existing Zope interfaces.
The WSGI example web service
The example web service in src/lazr/restful/example/wsgi/ is the best place to start understanding lazr.restful. It’s a very simple web service that uses a subset of lazr.restful’s features and can be run as a standalone WSGI application. An explanation of the code can be found in src/lazr/restful/example/wsgi/README.txt
The full example web service
To understand all of lazr.restful, you should look at the web service defined in src/lazr/restful/example/base/. It defines a simple application serving information about cookbooks and recipes. The interfaces (interfaces.py) are annotated with lazr.restful decorators that say which fields and methods to publish from IRecipe, ICookbook, and so on. The implementations of those interfaces are in root.py.
The machinery of lazr.restful takes the decorators in interfaces.py, and generates an interface that maps incoming HTTP requests to operations on the actual objects defined in root.py. You don’t have to do any HTTP server programming to get it to work (though at the moment you do have to know a fair amount about Zope).
You can test the example web service by running bin/test. The doctests in src/lazr/restful/example/base/tests use a fake httplib2 connection to simulate HTTP requests to the web service. You can watch the tests make GET, PUT, POST, PATCH, and DELETE requests to the web service. Start with root.txt.
Other code
Two other pieces of code might be of interest when you’re starting out.
declarations.py contains all the Python decorators. docs/webservice-declarations.txt shows how to use them.
docs/webservice.txt shows an example of a webservice that creates Entry and Collection classes directly rather than generating them with the declarations. If you want to use lazr.restful without using zope.schema, this is the test to look at.
NEWS for lazr.restful
0.9.6 (2009-09-16)
Simplified most web service configuration with grok directives.
0.9.5 (2009-08-26)
Added a function that generates a basic WSGI application, given a service root class, a publication class, and a response class.
Added an AbsoluteURL implementation for the simple ServiceRootResource.
Added an adapter from Django’s Manager class to IFiniteSequence, so that services that use Django can serve database objects as collections without special code.
Added an AbsoluteURL implementation for objects that provide more than one URL path for the generated URL.
For services that use Django, added an adapter from Django’s ObjectDoesNotExist to lazr.restful’s NotFoundView.
Fixed some testing infrastructure in lazr.restful.testing.webservice.
Fix some critical packaging problems.
0.9.4 (2009-08-17)
Fixed an import error in simple.py.
Removed a Python 2.6ism from example/wsgi/root.py.
0.9.3 (2009-08-17)
Added a lazr.restful.frameworks.django module to help with publishing Django model objects through lazr.restful web services.
TraverseWithGet implementations now pass the request object into get().
Create a simplified IServiceRootResource implementation for web services that don’t register their top-level collections as Zope utilities.
Make traversal work for entries whose canonical location is beneath another entry.
Raise a ValueError when numberic dates are passed to the DatetimeFieldMarshaller.
0.9.2 (2009-08-05)
Added a second example webservice that works as a standalone WSGI application.
Bug 400170; Stop hacking sys.path in setup.py.
Bug 387487; Allow a subordinate entry resource under a resource where there would normally be a field. Navigation to support subordinate IObjects is added to the publisher.
0.9.1 (2009-07-13)
Declare multipart/form-data as the incoming media type for named operations that include binary fields.
0.9 (2009-04-29)
Initial public release
