[Twisted-Python] Log output formatting (was Re: logging question)

[Don Dwiggins]

On 11/17/2011 3:26 PM, exarkun at twistedmatrix.com wrote:
> `msg` doesn't really care about what you give it. It doesn't support
> the `format` keyword in any particular way.  It's the job of a log
> observer to handle that sort of thing.  So it could certainly be
> documented, but don't mix things together that are unrelated.
>
> Jean-Paul

True, but I was motivated by a different concern: when I first started 
using msg, I was unable to trace through the API docs to the place where 
I could find what I've quoted; Chris' message gave me the hint I needed 
to complete my detective work.  I'd like to spare future users of the 
method the trouble I had.

Looking at the source of log.py, I'm at a bit of a loss to reconcile 
these two forces.  Certainly, the two log observers implemented there 
use textFromEventDict, but one could create a different observer that 
does things entirely differently.

The best idea I can come up with is, in the documentation for msg, refer 
to the documentation for the chosen log observer; then, in each log 
observer's documentation, describe how the formatting is done, either 
explicitly, or by reference to textFromEventDict.  (And maybe in the 
documentation for ILogObserver, recommend strongly that each 
implementation be explicit about message formatting.)  There should 
probably also be something in the logging howto.

Any better suggestions?

-- 

Don Dwiggins
Advanced Publishing Technology