On Tue, Sep 29, 2009 at 10:59 PM, Vinay Sajip <vinay_sa...@yahoo.co.uk> wrote: > > On Sep 29, 1:53 pm, Russell Keith-Magee <freakboy3...@gmail.com> > wrote: >> >> However, since you're interested in feedback, my suggestion would be >> to look at every defense you've made of logging in this thread (and >> any other threads where you've had similar arguments), and work out >> why the current docs have allowed those viewpoints to be established >> as apparent fact. Some examples: >> >> * Acknowledge that there is some Java heritage, but point out that >> this doesn't mean it's a bad thing, and that there is a lot that >> _isn't_ Java based about Python's logger. >> > > That's easier to do when people raise specific points, rather than > talk about Java heritage in an arm-waving way, as if it's an offshoot > of the Black Death ;-)
I was thinking that a calming, motherly "there there, it's all right, the boogeymonster isn't real" would do the trick :-) >> * Highlight the important architectural picture. As you noted in >> another reply - the logger and the handler are quite separate, and >> this gives a lot of power. However, the existence and significance of >> that architectural separation isn't really a major feature of the >> current docs. At present, the architectural bits are buried inside API > > That's because the docs are really pitched mainly as a a reference > guide. I suppose this is a big part of the problem. The logging module isn't a trivial API, and you really need to understand how it works before you can use it effectively. What is needed is a really good tutorial; what we have is a reference guide with a little bit of a tutorial tacked on the front. The reference is needed, but the tutorial is much more important from the point of view of getting the message out and encouraging people to use the API. >> discussion, but understanding this architecture is important if you're >> going to understand why logging works the way it does, and understand >> that logging isn't just putting lines into a file. > > I've recently created a blog about Python logging, where I talk about > logging from first principles and try to show why the design of Python > logging is as it is. It's not perfect, but it's a start. > > http://plumberjack.blogspot.com/2009/09/python-logging-101.html I saw this, and yes, it's a good start. However, it (or a version of it) needs to be formalized and in the official docs, not lingering on a blog somewhere. >> * Make the simple example actually simple. IMHO, a single-file simple >> logging example is good for exactly 2 things: >> - showing how to configure the simplest possible case of logging >> - explaining the "why don't I have any output" problem. > > I'm not sure what you're getting at. Sometimes, those two things is > all that people want to know at that time. Agreed, it's important that the simple use case is demonstrated. However, in the docs, the simple example is then used as a staging ground for demonstrating rotating file loggers and other things that a simple example doesn't need. Logging is a complex topic. A simple example doesn't provide the complexity that is required to demonstrate the strengths of the API. The simple example is useful for demonstrating the "hello world" case, but not for demonstrating more complex features. On the subject of examples, another suggestion: I'm wary of examples that try to be too smart. Take the logging level demonstration (the 5th code snippet in 16.6.1.1). This code very cleverly writes a script that can take a command line argument and turn it into a logging level, but in being clever, it obscures the point of the example - that you can output log messages at any level, but the configuration determines which ones are output. When you're trying to demonstrate the simple stuff, the less extraneous detail, the better. The next example (which demonstrates multiple loggers) is much clearer - it's obvious from first inspection what the code is doing. >> > They (logging and signals) are two different things. Python logging >> > allows you to consider the dimensions "What happened?", "Where did it >> > happen?", "How important is it?" and "Who wants to know?" >> > intelligently, and in particular it treats "What happened" and "Who >> > wants to know?" orthogonally. You get a lot of ways of getting >> > information to *people* whereas signals is more about letting *code* >> > know what's going on. >> >> Granted, although the two aren't mutually exclusive. After all, the >> way you let someone know "what happened" is with code; It isn't hard >> to think of a setup where we emit a signal everywhere that we might >> want to log, and then attach a logging signal handler to those signal. >> >> I'm not suggesting that this would be a good architecture - merely a >> possible one. > > I agree - it's possible, but perhaps not the most simple or intuitive. > If you can log something directly from where you are, why send a > signal to some other code which, while processing that signal, will > log something for you? To avoid a dependency on the logging module, thereby keeping Adrian happy :-) Seriously - I really do want to find out the nature of Adrian's objection to logging (if it is even current). I'd rather have an actual discussion than dance around a strawman. Yours, Russ Magee %-) --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to django-developers@googlegroups.com To unsubscribe from this group, send email to django-developers+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/django-developers?hl=en -~----------~----~----~----~------~----~------~--~---
