Mailman 3 January 2020 - docs

[issue39426] Pickler docstring misstates default and highest protocols
by Mark Dickinson 24 Jan '20

24 Jan '20

New submission from Mark Dickinson <dickinsm(a)gmail.com>: >From the pickle.Pickler docstring: > The optional *protocol* argument tells the pickler to use the given > protocol; supported protocols are 0, 1, 2, 3 and 4. The default > protocol is 3; a backward-incompatible protocol designed for Python 3. That's out of date since Python 3.8, where the default protocol is 4 and the highest available is 5. For future-proofing, it may be worth rewording the docstring to refer directly to the DEFAULT_PROTOCOL and HIGHEST_PROTOCOL constants. ---------- assignee: docs@python components: Documentation messages: 360497 nosy: docs@python, mark.dickinson, pitrou priority: normal severity: normal status: open title: Pickler docstring misstates default and highest protocols versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39426> _______________________________________

3 8

[issue39429] Add a new "Python Development Mode" page to the documentation
by STINNER Victor 24 Jan '20

24 Jan '20

New submission from STINNER Victor <vstinner(a)python.org>: Currently, the Python Development Mode is under-documented. The documentation lives in the documentation of the -X command line option which doesn't give much space to elaborate on effects of the development mode, how it should be used, suggest ways to get more information, etc. Attached PR adds a new "Python Development Mode" page to the documentation to suggest more advices and add examples. ---------- assignee: docs@python components: Documentation messages: 360527 nosy: docs@python, vstinner priority: normal severity: normal status: open title: Add a new "Python Development Mode" page to the documentation versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39429> _______________________________________

1 3

[issue39431] Mention nonlocal too in assignment quirk
by Shanavas M 23 Jan '20

23 Jan '20

New submission from Shanavas M <shanavas.m2(a)gmail.com>: Doc says "A special quirk of Python is that -- if no :keyword:`global` statement is in A special quirk of Python is that -- if no :keyword:`global` or :keyword:`nonlocal` effect -- assignments to names always go into the innermost scope." nonlocal should also be mentioned along with global ---------- assignee: docs@python components: Documentation messages: 360553 nosy: docs@python, shanavasm priority: normal pull_requests: 17528 severity: normal status: open title: Mention nonlocal too in assignment quirk versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39431> _______________________________________

3 7

[issue39402] Consistent use of terms
by Raymond Leiter 21 Jan '20

21 Jan '20

New submission from Raymond Leiter <rayrleiter(a)gmail.com>: This is my idea of an improvement to the documentation, but I doubt anyone would agree with me. Nevertheless, here it is: There are at least 4 commonly used characters used to group other constructs to clearly call attention to their meaning. 1. [] Brackets 2. {} Braces 3. () Parentheses 4. <> Less than/Greater than The problem I have with the way these symbols are spoken of (in writing as well as oral discourse) is the lack of consistent names for them. Brackets are often referred to as square Brackets, even though there is apparently no alternative such as rectangular Brackets, etc. Braces are often referred to as curly Braces or some times curly Brackets. Parentheses are usually called, correctly, Parentheses, but also referred to as round Brackets. I've never encountered 'round Braces', but I'm hopeful. Less then and Greater then symbols are referred to correctly when they are used in mathematics speak. However, when they are used as a 'grouping' mechanism, they are usually called Angle Brackets -- not Angle Braces. My proposal is this: The most consistent way I can think of for referring to these 4 symbols when used as a 'grouping' mechanism is: 1. [] SQUARE BRACKETS 2. {} CURLY BRACKETS 3. () ROUND BRACKETS 4. <> ANGLE BRACKETS There will be no more Braces, since that term is apparently quite unpopular with most programmers today. The 'shape' modifiers (SQUARE, CURLY, ROUND, ANGLE), applied to the common term BRACKETS, would appear to be much more consistent than current usage. I'm well aware of the difficulty in garnering support for this kind of an 'improvement', but I felt it needed said. ---------- assignee: docs@python components: Documentation messages: 360349 nosy: Raymond Leiter, docs@python priority: normal severity: normal status: open title: Consistent use of terms type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39402> _______________________________________

2 2

[issue39383] Mention Darwin as a potential value for platform.system()
by Peter Bittner 20 Jan '20

20 Jan '20

New submission from Peter Bittner <peter.bittner(a)gmx.net>: The platform module's documentation mentions 'Linux', 'Windows' and 'Java' explicitly as values for `platform.system()`. https://docs.python.org/3/library/platform.html#platform.system Given the popularity of macOS among developers, this gives the impression that the module won't detect 'Darwin' as a separate system type; developers may suspect this will be identified also as a "Linux-y" system (or so). Hence, 'Darwin' should be mentioned explicitly as one of the possible values. ---------- assignee: docs@python components: Documentation messages: 360248 nosy: bittner, docs@python priority: normal pull_requests: 17448 severity: normal status: open title: Mention Darwin as a potential value for platform.system() type: enhancement versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39383> _______________________________________

4 7

[issue29258] __init__.py required for pkgutil.walk_packages in python3
by Inada Naoki 20 Jan '20

20 Jan '20

Inada Naoki <songofacandy(a)gmail.com> added the comment: I am totally agree with Wolfgang: > they make it impossible to know whether a directory found on the filesystem is *intended* as a Python package or not. I think we shouldn't treat normal directory as namespace package until some portion in the directory is imported, or it is specified explicitly. So walk_packages() should be used like: walk_packages("/path/to/namespace", "namespace") I already rejected similar issue: #29642. If you can not agree with me, please make an thread in python-dev ML or discuss.python.org. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue29258> _______________________________________

1 0

[issue29258] __init__.py required for pkgutil.walk_packages in python3
by Inada Naoki 20 Jan '20

20 Jan '20

Change by Inada Naoki <songofacandy(a)gmail.com>: ---------- assignee: -> docs@python components: +Documentation -Library (Lib) nosy: +docs@python resolution: rejected -> stage: resolved -> needs patch status: closed -> open versions: +Python 3.8, Python 3.9 -Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue29258> _______________________________________

1 0

[issue36892] "Modules" section in Tutorial contains incorrect description about __init__.py
by musou1500 20 Jan '20

20 Jan '20

New submission from musou1500 <musou1500(a)gmail.com>: "Modules" section in the tutorial says that https://docs.python.org/3/tutorial/modules.html "The __init__.py files are required to make Python treat directories containing the file as packages. " But, thanks to PEP 420, __init__.py is not required after Python 3.3. https://www.python.org/dev/peps/pep-0420/ ---------- assignee: docs@python components: Documentation messages: 342228 nosy: docs@python, musou1500 priority: normal severity: normal status: open title: "Modules" section in Tutorial contains incorrect description about __init__.py type: enhancement 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/issue36892> _______________________________________

4 3

[issue36417] unicode.isdecimal bug in online Python 2 documentation
by PEW's Corner 19 Jan '20

19 Jan '20

New submission from PEW's Corner <pewscorner(a)gmail.com>: The online Python 2 documentation for unicode.isdecimal (https://docs.python.org/2/library/stdtypes.html#unicode.isdecimal) incorrectly states: "Decimal characters include digit characters". This is wrong (decimal characters are actually a subset of digit characters), and u'\u00b3' is an example of a character that is a digit but not a decimal. Issue 26483 (https://bugs.python.org/issue26483) corrected the same bug in the Python 3 documentation, and a similar correction should be applied to the Python 2 documentation. ---------- assignee: docs@python components: Documentation messages: 338736 nosy: docs@python, pewscorner priority: normal severity: normal status: open title: unicode.isdecimal bug in online Python 2 documentation type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36417> _______________________________________

4 4

[issue39364] Automatically tabulate module contents in the docs
by alex c 17 Jan '20

17 Jan '20

New submission from alex c <alexchandel(a)gmail.com>: By default, the docs.python.org page for a module does not list or tabulate the contents of that module. This makes it difficult to browse a module's functions or get a bird's-eye view. For example, the logging module (https://docs.python.org/3/library/logging.html) has almost 70 functions, methods, and attributes. But it's impossible to scan them without scrolling the entire length of the entry (~18 pages of US letter). Compare to the browsability of itertools (https://docs.python.org/3/library/itertools.html), which manually tabulates its functions in the first section. docs.python.org should automatically generate a TOC of the module's contents (classes, functions, etc) in the navigation sidebar, below the existing sidebar sections (perhaps in a collapsible section). Rust's documentation does this (example: https://doc.rust-lang.org/std/time/struct.Duration.html), and doc.rust-lang.org also effectively allows the entire page to function as a TOC by providing a "collapse page" button. ---------- assignee: docs@python components: Documentation messages: 360148 nosy: alexchandel, docs@python priority: normal severity: normal status: open title: Automatically tabulate module contents in the docs type: enhancement versions: Python 2.7, 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/issue39364> _______________________________________

2 1