Commits

Jesper Nøhr committed 3766d68

Automated commit message

Comments (0)

Files changed (1)

Documentation.wiki

 
 In addition to these, you may define any other methods you want. You can use these by including their names in the {{{fields}}} directive, and by doing so, the function will be called with a single argument: The instance of the {{{model}}}. It can then return anything, and the return value will be used as the value for that key.
 
+**NB**: These "resource methods" should be decorated with the @classmethod decorator, as they will not always receive an instance of itself. For example, if you have a UserHandler defined, and you return a User from another handler, you will not receive an instance of that handler, but rather the UserHandler.
+
 Lets start out by creating a simple handler in handlers.py:
 
 {{{
 
 === Emitters ===
 
-Emitters are what spews out the data, and are the things responsible for speaking YAML, JSON and XML. They currently reside in {{{emitters.py}}} as {{{XMLEmitter}}}, {{{JSONEmitter}}} and {{{YAMLEmitter}}}.
+Emitters are what spews out the data, and are the things responsible for speaking YAML, JSON, XML, Pickle and Django. They currently reside in {{{emitters.py}}} as {{{XMLEmitter}}}, {{{JSONEmitter}}}, {{{YAMLEmitter}}}, {{{PickleEmitter}}} and {{{DjangoEmitter}}}.
 
 Writing your own emitters is easy, all you have to do is create a class that subclasses {{{Emitter}}} and has a {{{render}}} method. The render method will receive 1 argument, 'request', which is a copy of the request object, which is useful if you need to look at request.GET (like defining callbacks, like the JSON emitter does.)
 
 
 Now a request for /blogposts.json will use the JSON emitter, etc.
 
+Additionally, you may specify the format in your URL mapping, via the keyword arguments shortcut:
+
+{{{
+#!python
+
+urlpatterns = patterns('',
+   url(r'^blogposts$', resource_here, { 'emitter_format': 'json' }),
+)
+}}}
+
 === Mapping URLs ===
 
 URL mappings in Piston work just like they do in Django. Lets map our BlogpostHandler:
    # same stuff as before 
 }}}
 
+You don't need a "proxy handler" subclassing BaseHandler to use anonymous handlers, you can just point directly at an anonymous resource as well.
+
 === Working with Models ===
 
 Piston allows you to tie to a model, but does not require it. The benefit you get from doing so, will become obvious when you work with it:
 
 * If you don't override read/create/update/delete it provides sensible defaults (if the method is allowed by {{{allow_methods}}} of course.)
 * You don't have to specify {{{fields}}} or {{{exclude}}} (but you still can, they aren't mutually exclusive!)
-* By using a model in a handler, Piston will remember your {{{fields}}}/{{{ exclude }}} directives and use them in other handlers who return objects of that type (unless overridden.)
+* By using a model in a handler, Piston will remember your {{{fields}}}/{{{exclude}}} directives and use them in other handlers who return objects of that type (unless overridden.)
 
 As we've seen earlier, tying to a model is as simple as setting the {{{model}}} class variable on a handler.
 
 
 {{{challenge}}} will receive no arguments, and must return a {{{HttpResponse}}} containing the proper challenge instructions. For Basic auth, it will return an empty response, with the header {{{WWW-Authenticate}}} set, and status code 401. This will tell the receiving end that they need to supply us with authentication.
 
-For anonymous handlers, there is a special class, {{{NoAuthentication}}} in {{{piston.resource}}} that always returns True for {{{is_authenticated}}}.
+For anonymous handlers, there is a special class, {{{NoAuthentication}}} in {{{piston.authentication}}} that always returns True for {{{is_authenticated}}}.
 
 ==== OAuth ====
 
 
 For your convenience, there's a set of helpers and utilities you can use. One of those is {{{rc}}} from {{{piston.utils}}}. It contains a set of standard returns that you can return from your actions to indicate a certain situation to the client.
 
+Since <<cset 26293e3884f4>>, these return a **fresh** instance of HttpResponse, so you can use something like this:
+
+{{{
+#!python
+
+resp = rc.CREATED
+resp.write("Everything went fine!")
+return resp
+
+resp = rc.CREATED
+resp.write("This will not have the previous 'fine' text in it.")
+return resp
+}}}
+
+This change is backwards compatible, as it overrides {{{__getattr__}}} to return a new instance rather than a singleton.
+
 |=Variable|=Result|=Description|
 |rc.ALL_OK|200 OK|Everything went well.|
 |rc.CREATED|201 Created|Object was created.|