Opened 5 years ago

Closed 5 years ago

#14616 closed (wontfix)

Recommend a leading underscore on module-level loggers in docs

Reported by: dgolden_ichec Owned by: nobody
Component: Documentation Version: master
Severity: Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:


The in-development django logging docs, at least at time of writing, suggest using "logger" for module-level logger instances. That is problematic - consider people doing "from blah import *" and accidentally grabbing the "wrong" logger instance. Using a leading underscore on such module-level loggers is therefore common in pythonland i.e.

_log = logging.getLogger(__name__)

While this is ultimately just a python quirk, I suggest the docs should be trivially amended to recommend a leading underscore (e.g. "_log") convention rather than "logger", possibly with a very brief explanation as to why, for beginner-friendliness. Mistakenly importing another module's logger leads to quite confusing logging behaviour.

Change History (1)

comment:1 Changed 5 years ago by russellm

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Resolution set to wontfix
  • Status changed from new to closed

I don't deny that _log is a common idiom, but the real fix here is "don't use from blah import *", or, in a refined form "don't use from blah import * unless the module author has used __all__ or has explicitly marked a module as safe for import *". This transcends anything in the logging code -- it's just good advice in general.

However, I'm going to mark this wontfix. There is a limit to how many times we can say "no, really, you need to learn Python" in Django's docs before Django's docs become a Python tutorial, and that's not what our docs are for.

Note: See TracTickets for help on using tickets.
Back to Top