On 29 Nov, 06:44 pm, ddwiggins@advpubtech.com wrote:
On 11/17/2011 3:26 PM, exarkun@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?
I'm not sure what you mean by "refer to the documentation for the chosen log observer". The only interpretation I can think of involves changing the documentation dynamically at runtime, which doesn't make any sense, so I don't think it's what you meant. :) Adding something about observers to the twisted.python.log.msg documentation does seem like it makes sense. Maybe that could be a link to most-used observers that Twisted comes with, or maybe to a document about observers in general. The second part of your suggestion, having each observer document what kind of events it expects to consume, sounds great. Extending the logging howto also sounds great. And a long-standing related issue, twisted.python.log.msg not appearing in the API documentation, would also be nice to resolve. Jean-Paul