[Twisted-Python] Re: Resource.render() returning NOT_DONE_YET

[Clark C. Evans]

On Mon, Apr 28, 2003 at 01:11:33PM -0400, Bob Ippolito wrote:
| Or, you could just deprecate NOT_DONE_YET and say "if you're doing
| something that uses req.write you need to return a deferred".
...
| I think that's the simplest way, and takes the return values for
| render down to three, but really two for new code:
| 1) a string
| 2) a deferred
| 3) a deprecated NOT_DONE_YET

Advantages:
 - keeps the clear error condition when mis-used
 - NOT_DONE_YET uglyness goes away
 - request.finish() can be handled automatically, ie, the
   default errback/callback and the end of the chain can
   make sure that request.finish() is called
 - could provide for better default exception handling,
   the first thing I did as a newbie was dig to find out
   how to get those wonderful traceback pages working
   for deferred failures... why not let it be the default?

I'd add one more... option though:

  4) If request.finish() has already been called, then
     it is acceptable to return None

On Mon, Apr 28, 2003 at 06:14:57PM -0400, Bob Ippolito wrote:
| On Monday, Apr 28, 2003, at 15:57 America/New_York, Glyph Lefkowitz wrote:
| >>|   2.  Alternatively, allow a Deferred to be a return
| >>|       value.  Then the underlying caller can add
| >>|       result.finish() to the deferred chain.   This
| >>|       has the advantage of not requiring finish() to
| >>|       really be managed.   Either the return value is
| >>|       a string, a Deferred, (or for backwards compatibiliy
| >>|       NOT_DONE_YET).  In either of the primary cases,
| >>|       result.finish() always gets called... thus making
| >>|       it easier on newbies.
| >
| >I've discussed this with several different people at various times... 
| >the trouble is, there isn't really a use-case that Deferreds make 
| >easier.  render() ends up being a relatively low-level interface, and 
| >the NOT_DONE_YET/write/finish API is quite convenient for the stuff 
| >that has been implemented with it.
| >
| >I am definitely a True Believer in the Deferred, but in this case it 
| >just doesn't seem worth the inconvenience of deprecating things and 
| >shuffling stuff around for a vanishingly small benefit.
| 
| The error handling inherent with Deferred makes it worth it IMHO.  I 
| see a lot of NOT_DONE_YET responses fail and it just hangs for the web 
| user unless the developer of the function did a lot more work.. a 
| deferred could just errback on a failure rather than having to summon 
| the web traceback mechanism manually.

I've had two use cases for NOT_DONE_YET they are:

   1.  You've already use req.write() several times followed
       by req.finish()... and then return NOT_DONE_YET.   This is
       confusing usage, primarly beacuse you *are* done.   This
       usage is supported by option #4 above.

   2.  You've setup a async call to finish handling the request,
       and in this case, it makes sence to return Deferred.  In
       this case returning NOT_DONE_YET, and having to call 
       req.finish() is just extra, unnecessary baggage; further,
       default error handling isn't provided when it should be.

NOT_DONE_YET is less than optimal in both use cases where it is used,
both of these cases confused a newbie that I was trying to teach.

Best,

Clark