d = dostuff()
d.addCallback(process)
# Final error handler.
d.addErrback(writeFailure, logger, "myapp:subsystem")
Of course dostuff could be anything and may lead to the correct behavior but real-world, idiomatic code that does the correct thing is more likely to be:
d = DeferredContext(dostuff())
d.addCallback(process)
# Final error handler.
d.addErrback(writeFailure, logger, "myapp:subsystem")
I think it should be clear to most readers that the DeferredContext is required for process to be run in the correct action context. However, since this is the documentation for writeFailure, it probably makes sense to take care to point out that the DeferredContext is required for the failure to end up logged as part of the correct action (which makes plenty of sense but it wasn't obvious to me, reading the example, and I had to try it out to convince myself there wasn't some special behavior surrounding writeFailure that made the DeferredContext unnecessary).
This all assumes there is an active action. I think that's probably the common case, given the purpose of Eliot, but maybe it's worth also mentioning in the docstring, along with this change.
The docstring gives the example:
Of course
dostuff
could be anything and may lead to the correct behavior but real-world, idiomatic code that does the correct thing is more likely to be:I think it should be clear to most readers that the
DeferredContext
is required forprocess
to be run in the correct action context. However, since this is the documentation forwriteFailure
, it probably makes sense to take care to point out that theDeferredContext
is required for the failure to end up logged as part of the correct action (which makes plenty of sense but it wasn't obvious to me, reading the example, and I had to try it out to convince myself there wasn't some special behavior surrounding writeFailure that made theDeferredContext
unnecessary).This all assumes there is an active action. I think that's probably the common case, given the purpose of Eliot, but maybe it's worth also mentioning in the docstring, along with this change.