Skip to content

logging.warn() is not documented #57444

Closed
Closed
logging.warn() is not documented#57444
Labels
docsDocumentation in the Doc dir

Description

@techtonik
techtonik
mannequin
opened on Oct 20, 2011
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

  1. techtonik commented on Oct 20, 2011

    @techtonik
    techtonikmannequin
    on Oct 20, 2011
    MannequinAuthor

    No docs for logging.warn() alias.

  2. techtonik
    assigned
    docspython
    on Oct 20, 2011
  3. techtonik
    added
    docsDocumentation in the Doc dir
    on Oct 20, 2011

  4. vsajip commented on Oct 20, 2011

    @vsajip
    vsajip
    on Oct 20, 2011
    Member

    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.

  5. vsajip
    closed this as completedon Oct 20, 2011
  6. vsajip
    added
    invalid
    on Oct 20, 2011

  7. techtonik commented on Oct 20, 2011

    @techtonik
    techtonikmannequin
    on Oct 20, 2011
    MannequinAuthor

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

  8. techtonik
    reopened this on Oct 20, 2011

  9. vsajip commented on Oct 20, 2011

    @vsajip
    vsajip
    on Oct 20, 2011
    Member

    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: [bpo-13235] 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\>

  10. techtonik commented on Oct 21, 2011

    @techtonik
    techtonikmannequin
    on Oct 21, 2011
    MannequinAuthor

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

  11. ezio-melotti commented on Oct 21, 2011

    @ezio-melotti
    ezio-melotti
    on Oct 21, 2011
    Member

    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.

  12. ezio-melotti
    removed
    invalid
    on Oct 21, 2011

  13. python-dev commented on Oct 21, 2011

    @python-dev
    python-devmannequin
    on Oct 21, 2011
    Mannequin

    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

  14. python-dev
    closed this as completedon Oct 21, 2011

  15. techtonik commented on Oct 22, 2011

    @techtonik
    techtonikmannequin
    on Oct 22, 2011
    MannequinAuthor

    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.

  16. techtonik
    reopened this on Oct 22, 2011

  17. ezio-melotti commented on Oct 22, 2011

    @ezio-melotti
    ezio-melotti
    on Oct 22, 2011
    Member

    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.

  18. vsajip commented on Oct 22, 2011

    @vsajip
    vsajip
    on Oct 22, 2011
    Member

    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.

  19. vsajip commented on Oct 22, 2011

    @vsajip
    vsajip
    on Oct 22, 2011
    Member

    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.

  20. ezio-melotti commented on Oct 22, 2011

    @ezio-melotti
    ezio-melotti
    on Oct 22, 2011
    Member

    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.

  21. vsajip commented on Oct 22, 2011

    @vsajip
    vsajip
    on Oct 22, 2011
    Member

    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.

  22. python-dev commented on Oct 22, 2011

    @python-dev
    python-devmannequin
    on Oct 22, 2011
    Mannequin

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

  23. python-dev
    closed this as completedon Oct 22, 2011
  24. ezio-melotti
    transferred this issue fromon Apr 10, 2022
  25. zsxwing
    added a commit that references this issue on Sep 14, 2022

    Replace deprecated logging.warn with logging.warning (#165)

    8742cf1
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation in the Doc dir

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions