logging.warn() is not documented

[techtonik]

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']

[techtonik]

No docs for logging.warn() alias.

[vsajip]

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]

I've got a traceback, because forgot to implement this method in logging wrapper. It should be either deprecated and removed or documented.

[vsajip]

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 -----

From: anatoly techtonik <[email protected]>
To: [email protected]
Cc:
Sent: Thursday, 20 October 2011, 20:32
Subject: [bpo-13235] logging.warn() is not documented

anatoly techtonik <[email protected]> added the comment:

I've got a traceback, because forgot to implement this method in logging
wrapper. It should be either deprecated and removed or documented.

----------
status: closed -> open

---

Python tracker <[email protected]>
<http://bugs.python.org/issue13235\>

---

[techtonik]

./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]

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]

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]

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]

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]

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.

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]

BTW, you could have used a DeprecationWarning instead of a

PendingDeprecationWarning, especially if it was already deprecated.

It wasn't officially deprecated, just "deprecation via obscurity";-) which is why I made it a PendingDeprecationWarning.

[ezio-melotti]

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]

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.

Hmmm, you're probably right. I'll change it to a DeprecationWarning.

[python-dev]

New changeset 4a90d1ed115d by Vinay Sajip in branch 'default':
Closes bpo-13235: Changed PendingDeprecationWarning to DeprecationWarning.
http://hg.python.org/cpython/rev/4a90d1ed115d