classification
Title: few discrepancy between source and docs in logging
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Michal Plichta, docs@python, r.david.murray, vinay.sajip
Priority: normal Keywords: easy, patch

Created on 2017-12-04 10:12 by Michal Plichta, last changed 2017-12-09 12:51 by vinay.sajip. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 4765 merged vinay.sajip, 2017-12-09 10:54
PR 4767 merged vinay.sajip, 2017-12-09 12:06
PR 4768 merged vinay.sajip, 2017-12-09 12:26
Messages (10)
msg307547 - (view) Author: Michal Plichta (Michal Plichta) Date: 2017-12-04 10:12
my code:

logger = logging.getLogger(name)
logger.setLevel(level=logging.DEBUG)
...
stream_handler = logging.StreamHandler(stream=stdout)
stream_handler.setLevel(logging_level)
stream_handler.setFormatter(fmt=formatter)

and mypy-0.550 complains about fmt vs. form parameter in setFormatter method and level vs. lvl in setLevel method.

ta_cc/cc_logger.py: note: In function "_get_stream_handler":
ta_cc/cc_logger.py:34: error: Unexpected keyword argument "fmt" for "setFormatter" of "Handler"
/usr/local/lib/mypy/typeshed/stdlib/2and3/logging/__init__.pyi:147: note: "setFormatter" of "Handler" defined here
ta_cc/cc_logger.py:109: error: Unexpected keyword argument "level" for "setLevel" of "Logger"
/usr/local/lib/mypy/typeshed/stdlib/2and3/logging/__init__.pyi:46: note: "setLevel" of "Logger" defined here

I see in online documentation that indeed there are lvl and form parameters for all 2.7, 3.5 and 3.6 python version. However my Pycharm suggest level and fmt for all my installed python interpreters.

I use:
Pycharm-2017.3
Python 2.7.12
Python 3.5.2
Python 3.6.3

This is copy of my issue of: https://github.com/python/typeshed/issues/1619
msg307561 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-12-04 12:54
I don't understand what the bug is that you are reporting here.  Can you clarify?  mypy isn't part of the stdlib, so an explanation in terms of what's in the stdlib would be helpful.
msg307565 - (view) Author: Michal Plichta (Michal Plichta) Date: 2017-12-04 13:29
see at typeshed:
https://github.com/python/typeshed/blob/master/stdlib/2and3/logging/__init__.pyi#L147

    def setLevel(self, lvl: Union[int, str]) -> None: ...
    def setFormatter(self, form: 'Formatter') -> None: ...

this match python documentation:
Handler.setLevel(lvl)
Handler.setFormatter(form)

but is source code (logging/__init__.py):
    def setFormatter(self, fmt):
        self.formatter = f

    def setLevel(self, level):
        self.level = _checkLevel(level)

This is not big deal but keyworded arguments have different names fmt, form and level, lvl.

Some tools which perform static code verification are base of *.pyi from typeshed repo and some form source code.
msg307567 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-12-04 13:48
Ah.  I'm guessing Vinay will probably want to fix the docs, then, since that's less disruptive backward compatibility wise.
msg307568 - (view) Author: Michal Plichta (Michal Plichta) Date: 2017-12-04 14:28
Nice, btw maybe other parameters in logging's docs needs to be corrected.
msg307766 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2017-12-06 20:22
I don't have a problem with tweaking the documentation where discrepancies are found between source and doc for keyword arguments, but in both the examples you give, the arguments are positional, not keyword. Therefore in my opinion your code should be e.g.

logger.setLevel(logging.DEBUG)

and

stream_handler.setFormatter(formatter)

without using keyword arguments. For positionals, as I see it, the name shouldn't matter, nor should any minor discrepancy between doc and source.
msg307789 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-12-07 05:10
It does matter, though, because in Python you can specify a positional argument as if it were a keyword argument if you use the name from the source rather than the documented name.  We have made other doc corrections along these lines.  We've even done it for C functions where you can't specify the argument as if it were a keyword argument, though that is considerably more rare.

That's a different question from the question of whether typing/linters should care, though.  Arguably they should recommend specifying them as positionals.
msg307890 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2017-12-09 11:09
New changeset a9f8df646aac7fc94ced0aefd1ed2c8566d14d10 by Vinay Sajip in branch 'master':
bpo-32212: Updated logging documentation to make parameter names more consistent with source. (GH-4765)
https://github.com/python/cpython/commit/a9f8df646aac7fc94ced0aefd1ed2c8566d14d10
msg307895 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2017-12-09 12:28
New changeset 63868181a904c844d8d01e3badfdd5b134acc5fa by Vinay Sajip in branch '3.6':
bpo-32212: Updated logging documentation to make parameter names more consistent with source. (GH-4765) (GH-4767)
https://github.com/python/cpython/commit/63868181a904c844d8d01e3badfdd5b134acc5fa
msg307897 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2017-12-09 12:49
New changeset 292fce9934280867ca9a65870495f83fca37751e by Vinay Sajip in branch '2.7':
bpo-32212: Updated logging documentation to make parameter names more consistent with source. (GH-4765) (GH-4768)
https://github.com/python/cpython/commit/292fce9934280867ca9a65870495f83fca37751e
History
Date User Action Args
2017-12-09 12:51:16vinay.sajipsetstatus: open -> closed
type: enhancement
resolution: not a bug -> fixed
stage: patch review -> resolved
2017-12-09 12:49:14vinay.sajipsetmessages: + msg307897
2017-12-09 12:28:18vinay.sajipsetmessages: + msg307895
2017-12-09 12:26:31vinay.sajipsetpull_requests: + pull_request4671
2017-12-09 12:06:11vinay.sajipsetpull_requests: + pull_request4670
2017-12-09 11:09:06vinay.sajipsetmessages: + msg307890
2017-12-09 10:54:31vinay.sajipsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request4668
2017-12-08 17:45:26eric.araujosetkeywords: + easy
2017-12-07 05:10:37r.david.murraysetstatus: pending -> open

messages: + msg307789
2017-12-06 20:22:26vinay.sajipsetstatus: open -> pending
resolution: not a bug
messages: + msg307766
2017-12-04 14:28:26Michal Plichtasetmessages: + msg307568
2017-12-04 13:50:26r.david.murraysetstage: needs patch
versions: + Python 3.7, - Python 3.4, Python 3.5
2017-12-04 13:48:55r.david.murraysetnosy: + vinay.sajip
messages: + msg307567
2017-12-04 13:29:07Michal Plichtasetmessages: + msg307565
2017-12-04 12:54:29r.david.murraysetnosy: + r.david.murray
messages: + msg307561
2017-12-04 10:12:27Michal Plichtacreate