Mailman 3 August 2019 - docs

[issue37004] SequenceMatcher.ratio() noncommutativity not well-documented
by Dennis Sweeney Aug. 7, 2019

Aug. 7, 2019

New submission from Dennis Sweeney <sweeney.dennis650(a)gmail.com>: I understand that the SequenceMatcher's ratio method does not guarantee that SequenceMatcher(None, a, b).ratio() == SequenceMatcher(None, b, a).ratio(). Below is a counterexample: # Example from https://mail.python.org/pipermail/python-list/2010-November/593063.html >>> SequenceMatcher(None, 'BRADY', 'BYRD').ratio() 0.6666666666666666 >>> SequenceMatcher(None, 'BYRD', 'BRADY').ratio() 0.4444444444444444 I was recently solving a problem that required a textual similarity ratio function and I wrongly assumed that SequenceMatcher treated both input strings symmetrically, which was an extremely difficult bug to find, especially because for many simple tests, the ratio IS symmetric: >>> SequenceMatcher(None, 'apple', 'banana').ratio() 0.18181818181818182 >>> SequenceMatcher(None, 'banana', 'apple').ratio() 0.18181818181818182 I would like to see a clearer warning of this asymmetry in the documentation for the difflib module. Perhaps something like .. note:: Caution: The result of a :meth:`ratio` call is *NOT* symmetric with respect to the order of the arguments. For instance:: >>> SequenceMatcher(None, 'brady', 'byrd').ratio() 0.6666666666666666 >>> SequenceMatcher(None, 'byrd', 'brady').ratio() 0.4444444444444444 Without such a note near the ratio methods' documentations, it is far too easy to google for a Python stdlib functionality for computing text similarity, skip straight to the ratio method, look at the examples given, try some of your own simple examples, and accidentally convince oneself that this symmetry exists. ---------- messages: 343138 nosy: Dennis Sweeney, docs@python priority: normal severity: normal status: open title: SequenceMatcher.ratio() noncommutativity not well-documented _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37004> _______________________________________

6 9

[issue37438] ConfigParser.set() docs should mention allow_no_value
by Nick Coghlan Aug. 7, 2019

Aug. 7, 2019

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: Reviewing some code today, I came across a ConfigParser.set() call that only specified the section and key, with the value argument missing. If you look at the ConfigParser.set() docs, this seems like incorrect code, as those docs indicate that the value argument is a required parameter: https://docs.python.org/3/library/configparser.html#configparser.ConfigPars… However, checking the code shows that: 1. "value" has a default value of None 2. if "allow_no_value" is passed to the constructor, passing "None" as the value will be interpreted as a request to add a key-only entry to the section with no equals sign ---------- assignee: docs@python components: Documentation messages: 346813 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: ConfigParser.set() docs should mention allow_no_value type: enhancement versions: Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37438> _______________________________________

3 2

[issue37779] configparser: add documentation about several read() behaviour
by Joannah Nanjekye Aug. 7, 2019

Aug. 7, 2019

Joannah Nanjekye <nanjekyejoannah(a)gmail.com> added the comment: I think you can build on the story in the quick start section. You can build on from the last section that starts with the paragraph: Now that we have created and saved a configuration file, let’s read it back and explore the data it holds. As it has some examples on read(). ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37779> _______________________________________

1 0

[issue37779] configparser: add documentation about several read() behaviour
by Joannah Nanjekye Aug. 7, 2019

Aug. 7, 2019

Joannah Nanjekye <nanjekyejoannah(a)gmail.com> added the comment: @Stéphane, thanks for suggesting the above documentation. Feel free to open a pull request here: https://github.com/python/cpython with this draft for review. ---------- nosy: +nanjekyejoannah _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37779> _______________________________________

1 0

[issue37779] configparser: add documentation about several read() behaviour
by SilentGhost Aug. 7, 2019

Aug. 7, 2019

Change by SilentGhost <ghost.adh(a)runbox.com>: ---------- assignee: -> docs@python components: +Documentation -Cross-Build nosy: +docs@python -Alex.Willmer _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37779> _______________________________________

1 0

[issue37646] eval() in a list comprehension
by Raymond Hettinger Aug. 7, 2019

Aug. 7, 2019

Change by Raymond Hettinger <raymond.hettinger(a)gmail.com>: ---------- assignee: -> docs@python components: +Documentation -Interpreter Core nosy: +docs@python resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37646> _______________________________________

1 0

[issue37730] NotImplemented is used instead of NotImplementedError in docs
by Serhiy Storchaka Aug. 5, 2019

Aug. 5, 2019

New submission from Serhiy Storchaka <storchaka+cpython(a)gmail.com>: In some places in the documentation NotImplemented is used instead of correct NotImplementedError. All occurrences of NotImplemented should be manually checked and wrong spelling should be corrected. ---------- assignee: docs@python components: Documentation keywords: easy, newcomer friendly messages: 348801 nosy: docs@python, serhiy.storchaka priority: normal severity: normal status: open title: NotImplemented is used instead of NotImplementedError in docs versions: Python 2.7, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37730> _______________________________________

4 13

[issue37761] Inaccurate explanation of ArgumentParser.add_argument()'s name-or-flags in JA
by Tatsuo Sekine Aug. 5, 2019

Aug. 5, 2019

New submission from Tatsuo Sekine <sekine.t(a)gmail.com>: Second sentence of name-or-flags explanation of argparse.ArgumentParser.add_argument() in ja lang. is: > そのため、add_argument() の第1引数は、フラグのリストか、シンプルな引数名のどちらかになります。 #[1] while its original English is: > The first arguments passed to add_argument() must therefore be either a series of flags, or a simple argument name. # [2] If I translate Japanese language one back to English, it'd be something: The first argument passed to add_argument() must therefore be either a list of flags, or a simple argument name. Japanese one's explanation means, name-or-flags could be either - "name" - ["-f", "--flag"] So, Japanese translation could be improved to clarify that name-of-flags (i.e. first argument*s*) could be either name or *series* (not list) of flags. Note that, following sentences in the doc have many supporting explanations, and also, there is argparse HOWTO doc with many examples, so this is not critical issue at all. [1] https://docs.python.org/ja/3/library/argparse.html#name-or-flags [2] https://docs.python.org/3/library/argparse.html#name-or-flags ---------- assignee: docs@python components: Documentation messages: 349031 nosy: Tatsuo Sekine, docs@python priority: normal severity: normal status: open title: Inaccurate explanation of ArgumentParser.add_argument()'s name-or-flags in JA type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37761> _______________________________________

3 2

[issue37750] PyBuffer_FromContiguous not documented
by hai shi Aug. 3, 2019

Aug. 3, 2019

Change by hai shi <shihai1991(a)126.com>: ---------- assignee: docs@python components: Documentation nosy: docs@python, shihai1991 priority: normal severity: normal status: open title: PyBuffer_FromContiguous not documented _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37750> _______________________________________

1 0

[issue30974] Update os.samefile docstring to match documentation
by miss-islington Aug. 2, 2019

Aug. 2, 2019

miss-islington <mariatta.wijaya+miss-islington(a)gmail.com> added the comment: New changeset a49f203e052c6fb1244d4e55c3fccc439dda0e2e by Miss Islington (bot) in branch '3.7': bpo-30974: Change os.path.samefile docstring to match docs (GH-7337) https://github.com/python/cpython/commit/a49f203e052c6fb1244d4e55c3fccc439d… ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue30974> _______________________________________

1 0