[Python-Dev] Using logging in the stdlib and its unit tests (original) (raw)

Glenn Linderman v+python at g.nevcal.com
Sat Dec 11 20:17:05 CET 2010

On 12/11/2010 3:52 AM, Vinay Sajip wrote:

I will try to incorporate more basic examples at the top of the documentation, but surely you don't want me to add more verbiage about basicConfig when your overall feeling is that there's too much documentation?

I try not to post unless I feel there is a new detail; yes the 8% is probably repetitive, but at present, going further, at least sequentially, does feel like a large mountain to climb... suddenly becoming significantly steeper there.

I really can't say much about the 92% of the documentation, because of the mountain.

Whether the existing documentation can be reordered to avoid the steep part, but rather provide a gentle upward path, I cannot say. If it is properly organized reference material, then probably adding more about something at the beginning is appropriate, to give the foundation, justification, and assistance for climbing the slope.

My overall feeling is not necessarily that there is too much documentation (there is a lot, but maybe that is a good thing, I should read it some week) but that it suffers in not providing useful information for the beginner at the front. I've listed what I've gleaned here and tried to point out the things that I still don't know, and tried to point out where things became less than obvious along the way. I do think it was primarily because the intro material is too brief and too disconnected, that I quit reading at the 8% mark (or so).
If the rest of the large document were to be similarly disconnected, it wouldn't be worth my time to read it... and if I had to read it all, just to understand enough to get started with simple logging, then it would be faster to write my own, which is the path I took. I suffer with my own being primitive, but I can tweak it when I need to. I still don't fully understand the nuances between handlers and filters, and likely won't until I read more of the documentation.

Jumping directly to the documentation (at the 28% mark, I'd have had to read a long way to find it) for basicConfig per your links helps, but sadly, because the first paragraph is full of the terms "logger", "handler", and "formatter", which I have only rudimentary ideas about what they do, being a beginner, I almost gave up again. But the description of the valid keywords for **kwargs was actually understandable, at the end of that documentation. I also learned that calling basicConfig more than once in a program is probably useless, and it should be nearly the first logger API called, if it is used. The first paragraph should be split, perhaps: "Does basic configuration for the logging system." is almost redundant with the name, but is OK if first. The rest of that paragraph, and the next three, should probably be moved after the list of kwargs keys and descriptions. Yes, the word handler is used a bit, but it is associated there with concepts like file names and stream handles, and that eases the uncertainty; together with the simple example at the front, and the verbage there, I can see that I specify a file name, and it makes the logger log to that file :)
And the level parameter is fine. I'm less sure about format and datefmt and why I would want to specify them or how, and am surprised to find that format is to be used by a "handler" not a "formatter", but the simple example shows me I can leave those out for starters.

Personally, I suffer in writing documentation; when I attempt to do so, and people read it, they usually tell me that after about the third read, they finally understand it, but sadly it takes them three reads.
It is interesting to be looking at the logger from the other side... maybe I'll be able to improve the documentation I write, after analyzing why the logger documentation was hard for me to approach.

-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20101211/84082181/attachment.html>

More information about the Python-Dev mailing list