Re: [Python-Dev] logging doc broken
On Sat, Dec 11, 2010 at 6:20 AM, K. Richard Pixley r...@noir.com wrote: I'm not sure where to report this but the online doc appears to be mismatched to python-2.6.5 for the logging module. Specifically, for a dir of an instance of a LogRecord, I'm seeing: ['__doc__', '__init__', '__module__', '__str__', 'args', 'created', 'exc_info', 'exc_text', 'filename', 'funcName', 'getMessage', 'levelname', 'levelno', 'lineno', 'module', 'msecs', 'msg', 'name', 'pathname', 'process', 'processName', 'relativeCreated', 'thread', 'threadName'] while the documentation lists a different set of attributes including lvl. As discussed on this list recently, the logging documentation can unfortunately give the impression that the attributes of the log record are the same as the arguments to the log record constructor. This is not the case - the actual list of attributes can be found in the table showing the useful LogRecord attributes that are available to formatters (and filters) when processing records: http://docs.python.org/library/logging#formatter-objects 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). Regards, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] logging doc broken
K. Richard Pixley rich at noir.com writes: I'm not sure where to report this but the online doc appears to be mismatched to python-2.6.5 for the logging module. Specifically, for a dir of an instance of a LogRecord, I'm seeing: ['__doc__', '__init__', '__module__', '__str__', 'args', 'created', 'exc_info', 'exc_text', 'filename', 'funcName', 'getMessage', 'levelname', 'levelno', 'lineno', 'module', 'msecs', 'msg', 'name', 'pathname', 'process', 'processName', 'relativeCreated', 'thread', 'threadName'] while the documentation lists a different set of attributes including lvl. Please report this on bugs.python.org. Check that you were referring to the 2.6 documentation - I didn't see any references to attributes there (following a quick scan). Ideally, link to the wrong doc section on docs.python.org in your bug report. Thanks, Vinay Sajip ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] logging doc broken
On 13/12/2010 10:31, Vinay Sajip wrote: [...] Ideally, link to the wrong doc section on docs.python.org in your bug report. Now that's not a piece of advice you see very often :) TJG ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] logging doc broken
On Mon, Dec 13, 2010 at 8:31 PM, Vinay Sajip vinay_sa...@yahoo.co.uk wrote: Please report this on bugs.python.org. Check that you were referring to the 2.6 documentation - I didn't see any references to attributes there (following a quick scan). Ideally, link to the wrong doc section on docs.python.org in your bug report. The reference to lvl makes me think this is the same mistake I made the other day (i.e. thinking the constructor parameters are also the LogRecord attributes) Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] logging doc broken
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.
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
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] logging doc broken
Tim Golden mail at timgolden.me.uk writes: On 13/12/2010 10:31, Vinay Sajip wrote: [...] Ideally, link to the wrong doc section on docs.python.org in your bug report. Now that's not a piece of advice you see very often :) True, but this area changed after 2.6 was released (after even 2.7, IIRC), so I want to be sure that if I'm going to change the doc sources on release26-maint, I'm doing the right thing. The 2.6 docs seem consistent with the 2.6 code, and while confusing (because the distinction between constructor param names and attr names is not spelled out), I don't see 2.6 docs as broken (or at least, I don't see where the breakage is). Regards, Vinay Sajip ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] logging doc broken
On Mon, Dec 13, 2010 at 8:58 PM, Vinay Sajip vinay_sa...@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 | ncogh...@gmail.com | Brisbane, Australia
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] logging doc broken
On Mon, Dec 13, 2010 at 9:04 PM, Vinay Sajip vinay_sa...@yahoo.co.uk wrote: Tim Golden mail at timgolden.me.uk writes: On 13/12/2010 10:31, Vinay Sajip wrote: [...] Ideally, link to the wrong doc section on docs.python.org in your bug report. Now that's not a piece of advice you see very often :) True, but this area changed after 2.6 was released (after even 2.7, IIRC), so I want to be sure that if I'm going to change the doc sources on release26-maint, I'm doing the right thing. It was more a comment on the fact that, at first glance, that sentence looks like an instuction to provide an incorrect link, rather than to provide a link to the section of the docs that is incorrect. Just a quirk of English grammar :) Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] logging doc broken
On 13/12/2010 11:21, Nick Coghlan wrote: On Mon, Dec 13, 2010 at 9:04 PM, Vinay Sajipvinay_sa...@yahoo.co.uk wrote: Tim Goldenmailat timgolden.me.uk writes: On 13/12/2010 10:31, Vinay Sajip wrote: [...] Ideally, link to the wrong doc section on docs.python.org in your bug report. Now that's not a piece of advice you see very often :) True, but this area changed after 2.6 was released (after even 2.7, IIRC), so I want to be sure that if I'm going to change the doc sources on release26-maint, I'm doing the right thing. It was more a comment on the fact that, at first glance, that sentence looks like an instuction to provide an incorrect link, rather than to provide a link to the section of the docs that is incorrect. Just a quirk of English grammar :) Thanks, Nick. That is what I meant. I wanted to indicate that it was tongue-in-cheek, but I never can remember the sequence of characters which means that... TJG ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] logging doc broken
Nick Coghlan ncoghlan at gmail.com writes: 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). I hadn't missed it - I'm just spelling out in more detail what I'm going to do. 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. I agree, it's a pretty unlikely scenario. Of course, I do make use of the parameter names in the dictConfig approach, so I can't really complain. I should hopefully remember this when I'm writing out a method or function signature for a public API :-) Regards, Vinay ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] logging doc broken
Nick Coghlan ncoghlan at gmail.com writes: 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). Ok, I've now checked in this change, and would be grateful for any feedback. Time for a break :-) Thanks a lot for all your patience and valuable feedback, Nick. It's been very helpful, and I hope it will make the logging docs more accessible to those who've been put off in the past. I've emailed Georg about how best to reorganise into: intro + basic tutorial (at current location) advanced tutorial reference cookbook and I'm waiting for his suggestions on how best to implement (in terms of breaking up into different files etc). Thanks and regards, Vinay ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] logging doc broken
On 12/13/2010 6:04 AM, Vinay Sajip wrote: True, but this area changed after 2.6 was released (after even 2.7, IIRC), so I want to be sure that if I'm going to change the doc sources on release26-maint, 2.6 is in security-fix only mode. I am not sure if that precludes doc fixes, on the chance that there will ever be a security fix, as it does non-security bug fixes, but is it hardly worth the bother compared to improving active releases. -- Terry Jan Reedy ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] logging doc broken
On Tue, Dec 14, 2010 at 5:34 AM, Terry Reedy tjre...@udel.edu wrote: On 12/13/2010 6:04 AM, Vinay Sajip wrote: True, but this area changed after 2.6 was released (after even 2.7, IIRC), so I want to be sure that if I'm going to change the doc sources on release26-maint, 2.6 is in security-fix only mode. I am not sure if that precludes doc fixes, on the chance that there will ever be a security fix, as it does non-security bug fixes, but is it hardly worth the bother compared to improving active releases. Fixing it in the 2.7 maintenance branch will be sufficient to modify docs.python.org, which is likely the most important place to update. Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] logging doc broken
On Tue, Dec 14, 2010 at 4:55 AM, Vinay Sajip vinay_sa...@yahoo.co.ukwrote: Nick Coghlan ncoghlan at gmail.com writes: 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). Ok, I've now checked in this change, and would be grateful for any feedback. Time for a break :-) Hmm, that may not have built correctly, since it isn't showing up in the web version of the dev docs yet. I skimmed the diff on python-checkins though, and it looked good to me. I think the revised docs should make it *much* easier for people to get a handle on how the logging system works (I know my own understanding of it is significantly better than it was a couple of weeks ago). Cheers, Nick. P.S. I'm off visiting family for a couple of weeks, so my email access is going to be sketchy for a while. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] logging doc broken
Nick Coghlan ncoghlan at gmail.com writes: Hmm, that may not have built correctly, since it isn't showing up in the web version of the dev docs yet. I skimmed the diff on python-checkins though, and it looked good to me. I'll keep an eye on the build (built OK on my machine but I'm not sure what the build trigger is for docs.python.org). I think the revised docs should make it *much* easier for people to get a handle on how the logging system works (I know my own understanding of it is significantly better than it was a couple of weeks ago). Glad to hear that. P.S. I'm off visiting family for a couple of weeks, so my email access is going to be sketchy for a while. Have a nice time, and thanks for all the help. Regards, Vinay ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
