classification
Title: logging.warn() is not documented
Type: Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ezio.melotti, python-dev, techtonik, vinay.sajip
Priority: normal Keywords:

Created on 2011-10-20 17:48 by techtonik, last changed 2011-10-22 12:34 by python-dev. This issue is now closed.

Messages (14)
msg146039 - (view) Author: anatoly techtonik (techtonik) Date: 2011-10-20 17:48
No docs for logging.warn() alias.
msg146042 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2011-10-20 18:43
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.
msg146045 - (view) Author: anatoly techtonik (techtonik) Date: 2011-10-20 19:32
I've got a traceback, because forgot to implement this method in logging wrapper. It should be either deprecated and removed or documented.
msg146047 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2011-10-20 20:26
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 <report@bugs.python.org>
> To: vinay_sajip@yahoo.co.uk
> Cc: 
> Sent: Thursday, 20 October 2011, 20:32
> Subject: [issue13235] logging.warn() is not documented
> 
> 
> anatoly techtonik <techtonik@gmail.com> 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 <report@bugs.python.org>
> <http://bugs.python.org/issue13235>
> _______________________________________
>
msg146057 - (view) Author: anatoly techtonik (techtonik) Date: 2011-10-21 00:43
./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).
msg146058 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-21 02:28
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.
msg146063 - (view) Author: Roundup Robot (python-dev) Date: 2011-10-21 06:33
New changeset 37479f0f68bc by Vinay Sajip in branch 'default':
Closes #13235: Added deprecation for warn() methods and function in logging.
http://hg.python.org/cpython/rev/37479f0f68bc
msg146160 - (view) Author: anatoly techtonik (techtonik) Date: 2011-10-22 09:18
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.
msg146161 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-22 09:29
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.
msg146164 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2011-10-22 11:00
> 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.
msg146165 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2011-10-22 11:01
> 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.
msg146166 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-22 11:03
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.
msg146168 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2011-10-22 11:10
> 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.
msg146170 - (view) Author: Roundup Robot (python-dev) Date: 2011-10-22 12:34
New changeset 4a90d1ed115d by Vinay Sajip in branch 'default':
Closes #13235: Changed PendingDeprecationWarning to DeprecationWarning.
http://hg.python.org/cpython/rev/4a90d1ed115d
History
Date User Action Args
2011-10-22 12:34:58python-devsetstatus: open -> closed
resolution: fixed
messages: + msg146170
2011-10-22 11:10:33vinay.sajipsetmessages: + msg146168
2011-10-22 11:03:17ezio.melottisetmessages: + msg146166
2011-10-22 11:01:22vinay.sajipsetmessages: + msg146165
2011-10-22 11:00:18vinay.sajipsetmessages: + msg146164
2011-10-22 09:29:29ezio.melottisetmessages: + msg146161
2011-10-22 09:18:32techtoniksetstatus: closed -> open
resolution: fixed -> (no value)
messages: + msg146160
2011-10-21 06:33:52python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg146063

resolution: fixed
stage: needs patch -> resolved
2011-10-21 02:28:26ezio.melottisetversions: + Python 3.2
nosy: + ezio.melotti

messages: + msg146058

resolution: not a bug -> (no value)
stage: needs patch
2011-10-21 00:43:17techtoniksetmessages: + msg146057
2011-10-20 20:26:03vinay.sajipsetmessages: + msg146047
2011-10-20 19:32:49techtoniksetstatus: closed -> open

messages: + msg146045
2011-10-20 18:43:38vinay.sajipsetstatus: open -> closed
resolution: not a bug
messages: + msg146042
2011-10-20 17:49:26ezio.melottisetnosy: + vinay.sajip
2011-10-20 17:48:49techtonikcreate