Mailman 3 July 2020 - docs

[issue41420] Academic Free License v. 2.1 link is not found and is obsolete
by Dmytro Litvinov 22 Sep '20

22 Sep '20

New submission from Dmytro Litvinov <litvinov.dmytro.it(a)gmail.com>: Link to Acamedic Free License v. 2.1(https://www.samurajdata.se/opensource/mirror/licenses/afl-2.1.php) at https://www.python.org/psf/contrib/ is not found. Also, Guido mentioned that version 2.1 seems obsolete and we may need to review that with the lawyer (https://bugs.python.org/issue41328#msg374495). ---------- assignee: docs@python components: Documentation messages: 374501 nosy: DmytroLitvinov, docs@python priority: normal severity: normal status: open title: Academic Free License v. 2.1 link is not found and is obsolete type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue41420> _______________________________________

3 6

[issue18280] Documentation is too personalized
by Serhiy Storchaka 19 Sep '20

19 Sep '20

New submission from Serhiy Storchaka: Some documentation files contain a number of I/my/me. Looks like they grew from personal modules and personal articles. Perhaps the official documentation needs more depersonalized style. Here is full list of such files: Doc/c-api/exceptions.rst Doc/c-api/long.rst Doc/distutils/builtdist.rst Doc/extending/extending.rst Doc/extending/windows.rst Doc/howto/argparse.rst Doc/howto/curses.rst Doc/howto/functional.rst Doc/howto/regex.rst Doc/howto/sockets.rst Doc/howto/urllib2.rst Doc/install/index.rst Doc/library/audioop.rst Doc/library/ctypes.rst Doc/library/doctest.rst Doc/library/heapq.rst Doc/library/numbers.rst Doc/library/ossaudiodev.rst Doc/library/tk.rst Doc/library/unittest.mock-examples.rst Doc/library/unittest.mock.rst Doc/reference/introduction.rst Doc/tutorial/classes.rst The list doesn't include FAQs where it may be appropriate and whatsnew files. Andrew Kuchling recently has fixed Doc/howto/unicode.rst for this issue (as part of issue4153). ---------- assignee: docs@python components: Documentation messages: 191636 nosy: akuchling, docs@python, eric.araujo, ezio.melotti, georg.brandl, serhiy.storchaka priority: normal severity: normal status: open title: Documentation is too personalized versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18280> _______________________________________

11 17

[issue25467] Put “deprecated” warnings first
by Tony R. 19 Sep '20

19 Sep '20

New submission from Tony R.: Python has wonderful, detailed documentation. I love it! Unfortunately, I have often found myself reading the otherwise-excellent documentation on a class/function/whatever, only to find out at the END of my reading that it is deprecated. This is frustrating, and counter-intuitive. If something is deprecated, I want to know it before I read any further. I have attached a patch with the relevant changes. I hope it helps! ---------- assignee: docs@python components: Documentation files: 0001-Move-deprecated-blocks-to-the-beginning-of-their-doc.patch keywords: patch messages: 253391 nosy: Tony R., docs@python priority: normal severity: normal status: open title: Put “deprecated” warnings first type: enhancement Added file: http://bugs.python.org/file40851/0001-Move-deprecated-blocks-to-the-beginni… _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25467> _______________________________________

5 13

[issue37575] Python Documentation on strings ( section 3.1.2.)
by Srikanth 18 Sep '20

18 Sep '20

New submission from Srikanth <s4srikanth(a)gmail.com>: In section 3.1.2 of the python documentation, its mentioned as below: Two or more string literals (i.e. the ones enclosed between quotes) next to each other are automatically concatenated. This feature is particularly useful when you want to break long strings: This only works with two literals though, not with variables or expressions: However, the concatination operation works on variables and expressions also. Please find the below python code snippet and the output: Python Code: ------------- s1='Hello' s2=' World ' s3=' How are you ? ' print(s1, s2, "\n", s3, "\n") print('---------------------------') print('Long time ' 'No see mate ') print("Hope ", 'All is ' "good") print('---------------------------') print(s1, 'World'," !!") print((s1+s2+s3)*2," there ?") Output: -------- Hello World How are you ? --------------------------- Long time No see mate Hope All is good --------------------------- Hello World !! Hello World How are you ? Hello World How are you ? there ? ---------- assignee: docs@python components: Documentation files: Python_Docs_3.1.2_String_Concatination.py messages: 347754 nosy: Deshpande, docs@python priority: normal severity: normal status: open title: Python Documentation on strings ( section 3.1.2.) type: resource usage Added file: https://bugs.python.org/file48474/Python_Docs_3.1.2_String_Concatination.py _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37575> _______________________________________

4 5

[issue39452] Improve the __main__ module documentation
by Géry 17 Sep '20

17 Sep '20

New submission from Géry <gery.ogam(a)gmail.com>: This PR will apply the following changes on the [`__main__` module documentation](https://docs.python.org/3.7/library/__main__.html): - correct the phrase "run as script" by "run from the file system" (as used in the [`runpy`](https://docs.python.org/3/library/runpy.html) documentation) since "run as script" does not mean the intended `python foo.py` but `python -m foo` (cf. [PEP 338](https://www.python.org/dev/peps/pep-0338/)); - replace the phrase "run with `-m`" by "run from the module namespace" (as used in the [`runpy`](https://docs.python.org/3/library/runpy.html) documentation) since the module can be equivalently run with `runpy.run_module('foo')` instead of `python -m foo`; - make the block comment [PEP 8](https://www.python.org/dev/peps/pep-0008/#comments)-compliant (located before the `if` block, capital initialised, period ended); - add a missing case for which a package's \_\_main\_\_.py is executed (when the package is run from the file system: `python foo/`). ---------- assignee: docs@python components: Documentation messages: 360682 nosy: docs@python, maggyero priority: normal pull_requests: 17565 severity: normal status: open title: Improve the __main__ module documentation type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39452> _______________________________________

3 4

[issue40025] enum: _generate_next_value_ is not called if its definition occurs after calls to auto()
by Luis E. 16 Sep '20

16 Sep '20

New submission from Luis E. <edd(a)asustin.net>: I ran into this issue when attempting to add a custom _generate_next_value_ method to an existing Enum. Adding the method definition to the bottom of the class causes it to not be called at all: from enum import Enum, auto class E(Enum): A = auto() B = auto() def _generate_next_value_(name, *args): return name E.B.value # Returns 2, E._generate_next_value_ is not called class F(Enum): def _generate_next_value_(name, *args): return name A = auto() B = auto() F.B.value # Returns 'B', as intended I do not believe that the order of method/attribute definition should affect the behavior of the class, or at least it should be mentioned in the documentation. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 364665 nosy: docs@python, edd07 priority: normal severity: normal status: open title: enum: _generate_next_value_ is not called if its definition occurs after calls to auto() type: behavior versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue40025> _______________________________________

9 22

[issue40721] PEP0435 (enums) -- there is no standard on enum item letters case
by Марк Коренберг 14 Sep '20

14 Sep '20

New submission from Марк Коренберг <socketpair(a)gmail.com>: Example from PEP0435: (https://www.python.org/dev/peps/pep-0435) >>> from enum import Enum >>> class Color(Enum): ... red = 1 ... green = 2 ... blue = 3 Example from Python documentation: (https://docs.python.org/3/library/enum.html) >>> from enum import Enum >>> class Color(Enum): ... RED = 1 ... GREEN = 2 ... BLUE = 3 ... So, what are the rules for naming enum members? CamelCase ? snake_case ? ALL_CAPS ? Someone should explain how should we format sources. So various linters may check for that. ---------- assignee: docs@python components: Documentation messages: 369544 nosy: docs@python, socketpair priority: normal severity: normal status: open title: PEP0435 (enums) -- there is no standard on enum item letters case versions: Python 3.10, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue40721> _______________________________________

6 12

[issue39883] Use BSD0 license for code in docs
by Todd Jennings 14 Sep '20

14 Sep '20

New submission from Todd Jennings <toddrjen(a)gmail.com>: Currently using code examples and recipes from the documentation is complicated by the fact that they are all under the Python 2.0 license. Putting them under a more permissive license, particular the BSD0 license, would make them much easier to use in other projects. ---------- assignee: docs@python components: Documentation messages: 363573 nosy: docs@python, toddrjen priority: normal pull_requests: 18180 severity: normal status: open title: Use BSD0 license for code in docs type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39883> _______________________________________

6 19

[issue33953] The DEFAULT_ENTROPY variable used to store the current default random bytes value should be documented for `secrets` module
by Serge Matveenko 14 Sep '20

14 Sep '20

New submission from Serge Matveenko <serge(a)matveenko.ru>: There is the corresponding section on the topic here https://github.com/python/cpython/blob/3.6/Doc/library/secrets.rst#how-many… The current value of 32 bytes is mentioned there correctly. Unfortunately, there is no way to know which constant in the `secrets` stores this value. It is easy to imagine a use case to use say `DEFAULT_ENTROPY * 4` in the code and stay updated with the default entropy being increased over time. Thus, it looks reasonable to document the `secrets.DEFAULT_ENTROPY` constant in the module docs. ---------- assignee: docs@python components: Documentation messages: 320402 nosy: docs@python, lig priority: normal severity: normal status: open title: The DEFAULT_ENTROPY variable used to store the current default random bytes value should be documented for `secrets` module type: enhancement versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33953> _______________________________________

3 5

[issue37149] link to official documentation tkinter failed !!!
by Guilloux 14 Sep '20

14 Sep '20

New submission from Guilloux <bugs.python.org(a)guilloux-fr.net>: On the page https://docs.python.org/3/library/tkinter.html there is a link to "Tkinter reference: a GUI for Python" which is "https://infohost.nmt.edu/tcc/help/pubs/tkinter/web/index.html". BIG PROBLEM : Since several days this link doesn't work any more !!! It's really important to fix it because most of official online documentation about tkinter was provided by this way !!! Fortunately i have a copy of the documentation (cf pdf file). I have downloaded this file thanks to the website above just before the link was failed ! (Yes, i know, i'm lucky...) Unfortunately I can't send you this pdf because I have a message "request entity too large" :-( ---------- assignee: docs@python components: Documentation, Tkinter messages: 344549 nosy: docs@python, xameridu priority: normal severity: normal status: open title: link to official documentation tkinter failed !!! versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37149> _______________________________________

9 37