[Python-Dev] Using logging in the stdlib and its unit tests
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
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...
More information about the Python-Dev