Opened 8 years ago

Last modified 3 years ago

#1703 enhancement new

Generated API docs for twisted.python.log are confusing

Reported by: predictive Owned by:
Priority: normal Milestone:
Component: core Keywords:
Cc: spiv, mwh, zooko@…, thijs Branch:
Author: Launchpad Bug:

Description

It's confusing that err is in twisted.python.log, but msg is in twisted.python.LogPublisher, and twisted.python.debug is deprecated. Since simplicity is the attractive part of twisted's logging vs python's, shouldn't debug be undeprecated and all three put in LogPublisher?

It would be even more attractive if twistd took a -v or --verbose switch that 'turned on' log.debug messages, so code doesn't have to be littered with "if self.debug: log.msg('foo')".

Change History (12)

comment:1 Changed 8 years ago by spiv

  • Cc spiv added
  • Keywords log logging twistd removed
  • Owner changed from glyph to predictive

I'm not sure what exactly you mean:

>>> import sys
>>> from twisted.python import log
>>> log.startLogging(sys.stdout)
2006/05/05 18:29 EST [-] Log opened.
>>> log.msg('a msg')
2006/05/05 18:29 EST [-] a msg
>>> log.err('an error')
2006/05/05 18:29 EST [-] 'an error'

i.e. msg and err are both attributes of twisted.python.log.

Are you referring to the implementation of twisted/python/log.py being confusing, the generated API docs being confusing, to http://twistedmatrix.com/projects/core/documentation/howto/logging.html being confusing, or something else? I want to make sure we understand what you mean.

The suggestion that we undeprecate twisted.python.log.debug, and add a --verbose switch belongs in a seperate enhancement ticket, I think. Big, multiple-issue tickets don't tend to get done. Call it something like "Proposal: standard debug logging API". I suspect the existing debug function was deprecated largely because it wasn't very carefully thought out how it would work.

Reassigning back to the reporter, for clarification.

comment:2 Changed 8 years ago by predictive

My confusion stems from the generated API documentation. log() is at http://twistedmatrix.com/documents/current/api/twisted.python.log.html, and
msg() is at http://twistedmatrix.com/documents/current/api/twisted.python.log.LogPublisher.html.

I'll add the enhancement ticket for twistd you suggest, and maybe take a crack at debug and twistd integration in a couple of weeks after I have a chance to read your coding guidelines and get more familiar with the codebase.

comment:3 Changed 8 years ago by spiv

  • Owner changed from predictive to mwh
  • Summary changed from Twisted's logging API is confusing to Generated API docs for twisted.python.log are confusing

Reassigning to mwh for his thoughts. Can pydoctor do better here? The API docs ought to look more like the way http://twistedmatrix.com/projects/core/documentation/howto/logging.html describes them.

comment:4 Changed 8 years ago by mwh

  • Cc mwh added

comment:5 Changed 8 years ago by mwh

Well, it can be bodged, of course, in the way that t.p.c.Interface is done now. I don't really see a way to make sensible API docs from the static source.

Expanding the module docstring might help :)

comment:6 Changed 8 years ago by mwh

Well, what do you know, I've added some support for taking data from live objects in pydoctor svn. Currently it treats bound methods that turn up in module dictionaries like functions, which not entirely coincidentally is the case required to document twisted.python.log properly. See

http://starship.python.net/crew/mwh/apidocs-s/twisted.python.log.html

Lots more potential for hacking ahead (and the integration is a bit crappy too so far).

comment:7 Changed 6 years ago by exarkun

#2708 was a duplicate of this.

comment:8 follow-up: Changed 4 years ago by zooko

  • Cc zooko@… added

So, did the pydoctor hack that mwh mentioned in comment:6 work to make the hyperlink for log.msg on this page: http://twistedmatrix.com/documents/current/core/howto/logging.html stop being a broken hyperlink to: http://twistedmatrix.com/documents/10.0.0/api/twisted.python.log.msg.html ?

comment:9 Changed 4 years ago by <automation>

  • Owner mwh deleted

comment:10 Changed 3 years ago by exarkun

#5247 was a duplicate of this.

comment:11 in reply to: ↑ 8 Changed 3 years ago by thijs

  • Cc thijs added

Replying to zooko:

So, did the pydoctor hack that mwh mentioned in comment:6 work to make the hyperlink for log.msg on this page: http://twistedmatrix.com/documents/current/core/howto/logging.html stop being a broken hyperlink to: http://twistedmatrix.com/documents/10.0.0/api/twisted.python.log.msg.html ?

Yes, there are no broken links on the page anymore and it now links to http://twistedmatrix.com/documents/11.0.0/api/twisted.python.log.LogPublisher.msg.html.

comment:12 Changed 3 years ago by glyph

I just noticed this yet again. http://twistedmatrix.com/documents/11.0.0/api/twisted.python.log.html still doesn't include a reference to log.msg. mwh, did the hack featured on http://starship.python.net/crew/mwh/apidocs-s/twisted.python.log.html ever make it to trunk? are we generating the docs with an old version of pydoctor?

Note: See TracTickets for help on using tickets.