[Python-Dev] logging doc broken (original) (raw)
Vinay Sajip vinay_sajip at yahoo.co.uk
Mon Dec 13 11:58:32 CET 2010
- Previous message: [Python-Dev] logging doc broken
- Next message: [Python-Dev] logging doc broken
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Nick Coghlan <ncoghlan 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.
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?
Regards,
Vinay Sajip
- Previous message: [Python-Dev] logging doc broken
- Next message: [Python-Dev] logging doc broken
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]