[Python-Dev] logging doc broken

[Nick Coghlan]

On Mon, Dec 13, 2010 at 8:58 PM, Vinay Sajip <vinay_sajip at yahoo.co.uk> wrote:
> Nick Coghlan <ncoghlan <at> gmail.com> writes:
>
>> Vinay is currently working on updates to the logging documentation,
>> and this is one of the things that is likely to change (with the table
>> of attributes moved to the LogRecord section and referenced from the
>> sections on Formatter and Filter objects).
>
> Yes, and to compound matters, the LogRecord constructor documentation lists the
> attribute values in the place you'd expect the parameters to appear, using the
> doc markup for attributes. This I think is what causes the confusion, although
> the markup is different to that used for parameters it's not clear at first
> glance.
>
> However, these changes are after 2.7 and 3.1: In 2.6 documentation the
> parameters are named as in the source, but there's no reference in the
> LogRecord reference documentation about any attributes of the LogRecord.

That's the problem though - if you don't read the intro paragraph
closely (which I didn't do), it's easy to jump to the conclusion that
those are also the attributes (since there is nothing else in the
section).

> Perhaps it would be best to do the following:
>
> - Add constructor params using normal parameter markup (:param:)
> - Create a separate section "LogRecord Attributes" with a table containing attr
> name, description, how to use with % formatting and how to use with
> {}-formatting. There is some overlap here with the parameter documentation for
> the LogRecord constructor, but I can put in a rider which explains that the
> param names and attr names are slightly different. (I could kick myself now for
> not being more scrupulous originally, but I'm not sure I can go back and change
> the param names in the source code now because in theory, someone might be
> constructing a LogRecord using LogRecord(**kwargs)).
>
> - Link to the latter section from the Formatter, Filter sections.
>
> Anyone see problems with this, or have a better suggestion?

Yep, that's what I had assumed you were going to do (this did come up
in the big thread about the logging docs, but you may have missed it).

You're also right about the backwards compatibility problem with
changing the parameter names. It's the one downside of keyword
arguments - it makes the parameter names part of a function's public
API, so they are much harder to fix when you make a mistake.

That said, you can't get a one-to-one correspondence in this case
anyway, since some of the parameters relate to multiple attributes
(e.g. "lvl" becomes both "levelNo" and "levelName").

It is rare that anyone will be constructing a LogRecord manually
though, so I don't think the parameter names matter all that much in
practice. It is far more common that people will be creating them
implicitly through the Logger event notification methods or by
deserialising them.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia