classification
Title: Docs of logging module says argument is named "lvl". TypeError.
Type: Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: vinay.sajip Nosy List: docs@python, ned.deily, penlect, rhettinger, vinay.sajip
Priority: normal Keywords: patch

Created on 2019-09-20 16:26 by penlect, last changed 2019-10-15 07:30 by ned.deily. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 16571 merged AWhetter, 2019-10-03 22:34
PR 16576 merged miss-islington, 2019-10-04 08:00
PR 16577 merged miss-islington, 2019-10-04 08:00
PR 16586 closed AWhetter, 2019-10-04 16:04
Messages (5)
msg352866 - (view) Author: Daniel Andersson (penlect) * Date: 2019-09-20 16:26
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.
msg353902 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2019-10-04 07:55
New changeset 3142c667b50254daaa28f22c79bdda177136bd03 by Vinay Sajip (Ashley Whetter) in branch 'master':
bpo-38235: Correct some arguments names in logging documentation (GH-16571)
https://github.com/python/cpython/commit/3142c667b50254daaa28f22c79bdda177136bd03
msg353904 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2019-10-04 08:14
New changeset 3af2733a8265a2685b2c0466a58a66e544a81c64 by Vinay Sajip (Miss Islington (bot)) in branch '3.8':
bpo-38235: Correct some arguments names in logging documentation (GH-16571) (GH-16576)
https://github.com/python/cpython/commit/3af2733a8265a2685b2c0466a58a66e544a81c64
msg353905 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2019-10-04 08:14
New changeset 4f82a53c5d34df00bf2d563c2417f5e2638d1004 by Vinay Sajip (Miss Islington (bot)) in branch '3.7':
bpo-38235: Correct some arguments names in logging documentation (GH-16571) (GH-16577)
https://github.com/python/cpython/commit/4f82a53c5d34df00bf2d563c2417f5e2638d1004
msg354695 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2019-10-15 07:30
New changeset 6eb554583218cda9a145982a41c30612968a942f by Ned Deily (Miss Islington (bot)) in branch '3.7':
bpo-38235: Correct some arguments names in logging documentation (GH-16571) (GH-16577)
https://github.com/python/cpython/commit/6eb554583218cda9a145982a41c30612968a942f
History
Date User Action Args
2019-10-15 07:30:25ned.deilysetnosy: + ned.deily
messages: + msg354695
2019-10-04 16:04:57AWhettersetpull_requests: + pull_request16177
2019-10-04 08:15:04vinay.sajipsetstatus: open -> closed
stage: patch review -> resolved
resolution: fixed
versions: - Python 2.7
2019-10-04 08:14:31vinay.sajipsetmessages: + msg353905
2019-10-04 08:14:04vinay.sajipsetmessages: + msg353904
2019-10-04 08:00:21miss-islingtonsetpull_requests: + pull_request16169
2019-10-04 08:00:07miss-islingtonsetpull_requests: + pull_request16168
2019-10-04 07:55:19vinay.sajipsetmessages: + msg353902
2019-10-04 06:40:32rhettingersetassignee: rhettinger -> vinay.sajip
2019-10-03 22:34:54AWhettersetkeywords: + patch
stage: patch review
pull_requests: + pull_request16162
2019-09-20 17:24:31rhettingersetassignee: docs@python -> rhettinger

nosy: + rhettinger
versions: - Python 3.5, Python 3.6
2019-09-20 16:26:57penlectcreate