Repository navigation
logging.warn() is not documented #57444
Description
| BPO | 13235 |
|---|---|
| Nosy | @vsajip, @ezio-melotti |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = <Date 2011-10-22.12:34:58.811>
created_at = <Date 2011-10-20.17:48:49.411>
labels = ['docs']
title = 'logging.warn() is not documented'
updated_at = <Date 2011-10-22.12:34:58.809>
user = 'https://bugs.python.org/techtonik'bugs.python.org fields:
activity = <Date 2011-10-22.12:34:58.809>
actor = 'python-dev'
assignee = 'docs@python'
closed = True
closed_date = <Date 2011-10-22.12:34:58.811>
closer = 'python-dev'
components = ['Documentation']
creation = <Date 2011-10-20.17:48:49.411>
creator = 'techtonik'
dependencies = []
files = []
hgrepos = []
issue_num = 13235
keywords = []
message_count = 14.0
messages = ['146039', '146042', '146045', '146047', '146057', '146058', '146063', '146160', '146161', '146164', '146165', '146166', '146168', '146170']
nosy_count = 5.0
nosy_names = ['vinay.sajip', 'techtonik', 'ezio.melotti', 'docs@python', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue13235'
versions = ['Python 2.7', 'Python 3.2', 'Python 3.3']
Activity
techtonik commentedon Oct 20, 2011
No docs for logging.warn() alias.
vsajip commentedon Oct 20, 2011
That's deliberate. The original code (before incorporation into Python) had warn(), which was kept for backward compatibility. The docs refer to warning() because that's what everyone is supposed to use. The method names map to the lower case of the appropriate logging level name.
techtonik commentedon Oct 20, 2011
I've got a traceback, because forgot to implement this method in logging wrapper. It should be either deprecated and removed or documented.
vsajip commentedon Oct 20, 2011
It is deprecated by not being documented. It certainly isn't going to have documentation added for it.
Which code was calling the warn() method? Is it not possible to change this to call warning()?
----- Original Message -----
techtonik commentedon Oct 21, 2011
./trac/env.py: self.log.warn('base_url option not set in configuration, '
./trac/env.py: self.log.warn('Couldn\'t write sample configuration file (%s)', e,
./trac/web/main.py: ## env.log.warn("%d uncollectable objects found.", uncollectable)
./trac/web/main.py: env.log.warn(exception_to_unicode(e))
./trac/web/.svn/text-base/main.py.svn-base: ## env.log.warn("%d uncollectable objects found.", uncollectable)
./trac/web/.svn/text-base/main.py.svn-base: env.log.warn(exception_to_unicode(e))
./trac/wiki/formatter.py: self.env.log.warn(e)
./trac/wiki/.svn/text-base/formatter.py.svn-base: self.env.log.warn(e)
./trac/versioncontrol/api.py: self.log.warn("Discarding duplicate repository '%s'",
./trac/versioncontrol/api.py: self.log.warn("Found no repositories matching '%s' base.",
./trac/versioncontrol/svn_prop.py: self.log.warn("svn:externals entry %s doesn't contain "
./trac/versioncontrol/.svn/text-base/api.py.svn-base: self.log.warn("Discarding duplicate repository '%s'",
./trac/versioncontrol/.svn/text-base/api.py.svn-base: self.log.warn("Found no repositories matching '%s' base.",
./trac/versioncontrol/.svn/text-base/svn_prop.py.svn-base: self.log.warn("svn:externals entry %s doesn't contain "
./trac/ticket/roadmap.py: def warn(msg):
./trac/ticket/roadmap.py: warn(('Milestone "%(name)s" already exists, please '
./trac/ticket/roadmap.py: warn(('You must provide a name for the milestone.'))
./trac/ticket/roadmap.py: warn(('Completion date may not be in the future'))
./trac/ticket/.svn/text-base/roadmap.py.svn-base: def warn(msg):
./trac/ticket/.svn/text-base/roadmap.py.svn-base: warn(('Milestone "%(name)s" already exists, please '
./trac/ticket/.svn/text-base/roadmap.py.svn-base: warn(('You must provide a name for the milestone.'))
./trac/ticket/.svn/text-base/roadmap.py.svn-base: warn(('Completion date may not be in the future'))
./trac/admin/web_ui.py: self.env.log.warn("Adding %s to group %s: " \
./trac/admin/.svn/text-base/web_ui.py.svn-base: self.env.log.warn("Adding %s to group %s: " \
./trac/prefs/web_ui.py: self.log.warn('Unknown preference panel %r', panel_id)
./trac/prefs/.svn/text-base/web_ui.py.svn-base: self.log.warn('Unknown preference panel %r', panel_id)
./trac/.svn/text-base/env.py.svn-base: self.log.warn('base_url option not set in configuration, '
./trac/.svn/text-base/env.py.svn-base: self.log.warn('Couldn\'t write sample configuration file (%s)', e,
quite a lot + probably trac plugins. So it's better to go through deprecation cycle and show appropriate message (but frankly - I don't mind against convenience alias - we already have some in testing modules).
ezio-melotti commentedon Oct 21, 2011
I think it's better to avoid "deprecations by missing documentation" and document explicitly if something is deprecated.
What happens is that people working on some old code find the deprecated method, check the doc to see what it does, don't find anything, get puzzled for a while until they figure out how it works, and then use it.
If they find it and see that is deprecated they will stop using it and start using the right method.
While it's true that new users don't need to know that there's a deprecated method, it's unlikely that they will start using it, so documenting deprecated methods makes more good than harm.
If you want to remove it eventually you'll also have to go through an actual deprecation process with warnings.
python-dev commentedon Oct 21, 2011
New changeset 37479f0f68bc by Vinay Sajip in branch 'default':
Closes bpo-13235: Added deprecation for warn() methods and function in logging.
http://hg.python.org/cpython/rev/37479f0f68bc
techtonik commentedon Oct 22, 2011
Just to me it clear - why do you want warn() to be removed aside from code duplication?
My argument to leave it and document is that it is convenient and makes lines shorter (and won't break existing code). From logging module I also see that there are also logging.WARN aliases that you'll need to deprecate also.
ezio-melotti commentedon Oct 22, 2011
Because there should be only one way to do things.
BTW, you could have used a DeprecationWarning instead of a PendingDeprecationWarning, especially if it was already deprecated.
vsajip commentedon Oct 22, 2011
Sorry, I don't agree. I was happy to leave it as is until you raised this issue, but now I think the right thing to do is deprecate and remove warn(). I'm not too fussed about the WARN level, and I can't easily issue a deprecation warning for it as it's a module attribute, so I'll leave it in as an internal implementation detail, for which the usual caveats apply.
vsajip commentedon Oct 22, 2011
It wasn't officially deprecated, just "deprecation via obscurity";-) which is why I made it a PendingDeprecationWarning.
ezio-melotti commentedon Oct 22, 2011
PendingDeprecations are not so useful now that warnings are silenced by default. Since it wasn't documented, you could deprecate it in 3.3 and remove it in 3.4 IMHO.
vsajip commentedon Oct 22, 2011
Hmmm, you're probably right. I'll change it to a DeprecationWarning.
python-dev commentedon Oct 22, 2011
New changeset 4a90d1ed115d by Vinay Sajip in branch 'default':
Closes bpo-13235: Changed PendingDeprecationWarning to DeprecationWarning.
http://hg.python.org/cpython/rev/4a90d1ed115d
Replace deprecated logging.warn with logging.warning (#165)