[New-bugs-announce] [issue38235] Docs of logging module says argument is named "lvl". TypeError.

[Daniel Andersson]

New submission from Daniel Andersson <daniel.4ndersson at gmail.com>:

How to reproduce:

>>> import logging
>>> logging.disable(lvl=logging.ERROR)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: disable() got an unexpected keyword argument 'lvl'

The correct keyword argument name is `level` as can be seen in the Python code Lib/logging/__init__.py:
---> def disable(level=CRITICAL):

The documentation uses `lvl`, see Doc/library/logging.rst:
---> .. function:: disable(lvl=CRITICAL)

The solution would be to rename the argument from `lvl` to `level` in the documentation.

I also noticed some more cases in the logging module docs where `lvl` is used (and `level` is used in the Python code):

* logging.Logger.isEnabledFor(lvl)
* logging.Logger.log(lvl, msg, *args, **kwargs)
* logging.Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)
* logging.addLevelName(lvl, levelName)
* logging.getLevelName(lvl)

Maybe there are some historical reasons for this that I'm not aware about.

I also found an inconsistency. In the `Handler` class the docs does use `level`:
* logging.Handler.setLevel(level)

I can understand that the English in the documentation might be clearer when written as:
"Associates level `lvl` with text `levelName`"
instead of,
"Associates level `level` with text `levelName`"
- avoids the double-"level".

But at the same time, I usually trust the documentation blindly and was surprised by this error.

In the five listed examples above, `lvl` is only used as a positional argument. Maybe it is more OK to deviate from the actual name in the code in this case compared to keyword arguments, as in logging.disable.

----------
assignee: docs at python
components: Documentation, Library (Lib)
messages: 352866
nosy: docs at python, penlect, vinay.sajip
priority: normal
severity: normal
status: open
title: Docs of logging module says argument is named "lvl". TypeError.
versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue38235>
_______________________________________