Mailman 3 March 2017 - docs

[issue27212] Doc for itertools, 'islice()' implementation have unwanted behavior for recipe 'consume()'
by alex0307 April 2, 2018

April 2, 2018

New submission from alex0307: In the doc for itertools, the python implementation of islice() doesn't actually perform the iteration when given an empty slice (e.g. islice(it,3,3)). This is not the expected behavior for 'consume()' in the recipe given below, i.e. consume(it,3) couldn't actually advance the iterator for 3 steps ahead. Instead, the iterator stays at its starting position. As a simple fix, in the implementation of islice(), the length of the slice object should be checked first. If it's zero, the iterator should be advanced (slice.start-1) times, and return (See islice_my.py) ---------- assignee: docs@python components: Documentation files: islice_my.py messages: 267236 nosy: alex0307, docs@python priority: normal severity: normal status: open title: Doc for itertools, 'islice()' implementation have unwanted behavior for recipe 'consume()' type: behavior versions: Python 2.7 Added file: http://bugs.python.org/file43184/islice_my.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27212> _______________________________________

5 16

[issue27428] Document WindowsRegistryFinder inherits from MetaPathFinder
by Brett Cannon March 23, 2018

March 23, 2018

New submission from Brett Cannon: Currently the docs claim it inherits from importlib.abc.Finder. ---------- assignee: docs@python components: Documentation messages: 269633 nosy: brett.cannon, docs@python priority: normal severity: normal status: open title: Document WindowsRegistryFinder inherits from MetaPathFinder versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27428> _______________________________________

4 10

[issue25836] Documentation of MAKE_FUNCTION is still incorrect
by Russell Keith-Magee March 22, 2018

March 22, 2018

New submission from Russell Keith-Magee: Refs Issue16554, Issue13026, Issue14349, and probably others. The documentation for the interpretation of the argc argument to MAKE_FUNCTION in Doc/library/dis.rst is incorrect. As of 13 August 2015, the docs say: """ Pushes a new function object on the stack. From bottom to top, the consumed stack must consist of: * ``argc & 0xFF`` default argument objects in positional order * ``(argc >> 8) & 0xFF`` pairs of name and default argument, with the name just below the object on the stack, for keyword-only parameters * ``(argc >> 16) & 0x7FFF`` parameter annotation objects * a tuple listing the parameter names for the annotations (only if there are ony annotation objects) * the code associated with the function (at TOS1) * the :term:`qualified name` of the function (at TOS) """ However, this doesn't capture the fact that: * if there are annotations, the number of default arguments returned by `argc & 0xFF` must be reduced by `(argc >> 16) & 0x7FFF` * The value `(argc >> 16) & 0x7FFF` for the number of annotations *includes* the "extra" entry for the tuple describing which arguments the annotations apply to. This means that `(argc >> 16) & 0x7FFF` will be either 0, or 2+; it can't be 1 (because if you have one annotation, you must also have a tuple describing which arguments is annotated). ---------- assignee: docs@python components: Documentation messages: 256189 nosy: docs@python, freakboy3742 priority: normal severity: normal status: open title: Documentation of MAKE_FUNCTION is still incorrect versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25836> _______________________________________

2 3

[issue13677] correct docstring for builtin compile
by Jim Jewett March 22, 2018

March 22, 2018

New submission from Jim Jewett <jimjjewett(a)gmail.com>: The current docstring for compile suggests that the flags are strictly for selecting future statements. These are not the only flags. It also suggests that the source must be source code and the result will be bytecode, which isn't quite true. I suggest changing: "The flags argument, if present, controls which future statements influence the compilation of the code." to: "The flags argument, if present, largely controls which future statements influence the compilation of the code. (Additional flags are documented in the AST module.)" ---------- assignee: docs@python components: Documentation files: bltinmodule.c.patch keywords: patch messages: 150337 nosy: Jim.Jewett, docs@python priority: normal severity: normal status: open title: correct docstring for builtin compile type: behavior Added file: http://bugs.python.org/file24105/bltinmodule.c.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13677> _______________________________________

4 6

[issue21611] int() docstring - unclear what number is
by Dmitry Andreychuk March 16, 2018

March 16, 2018

New submission from Dmitry Andreychuk: https://docs.python.org/3.4/library/functions.html?highlight=int#int The docstring for int() function has these sentences: "If x is a number, return x.__int__()." "If x is not a number or if base is given..." Unfortunately the docstring doesn't describe how the function decides if x is a number or not. After searching and experimenting I came to conclusion that it is the presence of x.__int__() method makes int() treat x as a number. But I'm not sure it's a precise requirement or just something that happens to work with current implementation. I think there should be a precise definition of what is considered to be a number there. ---------- assignee: docs@python components: Documentation messages: 219379 nosy: and, docs@python priority: normal severity: normal status: open title: int() docstring - unclear what number is versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21611> _______________________________________

7 9

[issue28612] str.translate needs a mapping example
by Jim Jewett March 13, 2018

March 13, 2018

New submission from Jim Jewett: One commonly needed string transformation is stripping out certain characters (or only keeping certain characters). This is common enough that it might be worth a dedicated method, except, that, as Stephen J. Turnbull wrote in https://mail.python.org/pipermail/python-ideas/2016-November/043501.html """ So really translate with defaultdict is a specialized loop that marries an algorithmic body (which could do things like look up the original script or other character properties to decide on the replacement for the generic case) with a (usually "small") table of exceptions. That seems like inspired design to me. """ Alas, while inspired, it isn't obvious to someone who isn't yet used to the power of python custom classes. The documentation (such as https://docs.python.org/3/library/stdtypes.html?highlight=translate#str.tra… ) should include such an example. One possible example would be a defaultdict that says to discard any characters except lower case ASCII lettersI. ---------- assignee: docs@python components: Documentation keywords: easy messages: 280061 nosy: Jim.Jewett, docs@python priority: normal severity: normal stage: needs patch status: open title: str.translate needs a mapping example type: enhancement versions: Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28612> _______________________________________

7 9

[issue25910] Fixing links in documentation
by SilentGhost March 10, 2018

March 10, 2018

New submission from SilentGhost: I've run 'make linkcheck' on Doc and it highlighted a number of faulty links in documentation. I've tried fixing some of them and here is the resulting patch. It's a bit too long and touches many files, so to summarise: * Most changes are http->https redirect (many from wikipedia and microsoft, but some from independent project) * New domains, sometimes without redirect or any indication of how to find the same information. * Completely new locations, only discoverable via search engine. * Few dead links, that I removed. I'm going to attach output.txt that is produced after running linkcheck with this patch applied, it is about three time smaller than the original one and has this types of issues: * Dead links in licenses * Internal redirects to versioned text * Many python.org links in whatsnew/ that I don't know what to do about * Spurious bad links ---------- assignee: docs@python components: Documentation files: linkcheck.diff keywords: needs review, patch messages: 256728 nosy: SilentGhost, docs@python, r.david.murray, zach.ware priority: normal severity: normal stage: needs patch status: open title: Fixing links in documentation versions: Python 3.5, Python 3.6 Added file: http://bugs.python.org/file41361/linkcheck.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25910> _______________________________________

18 62

[issue22822] IPv6Network constructor docs incorrect about valid input
by Chris PeBenito March 8, 2018

March 8, 2018

New submission from Chris PeBenito: Here: https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv6Network In the constructor documentation, item 1 says: """ A string consisting of an IP address and an optional mask, separated by a slash (/). The IP address is the network address, and the mask can be either a single number, which means it’s a prefix, or a string representation of an IPv6 address. If it’s the latter, the mask is interpreted as a net mask. If no mask is provided, it’s considered to be /128. For example, the following address specifications are equivalent: 2001:db00::0/24 and 2001:db00::0/ffff:ff00::. """ However in issue22800 it has been identified that using the expanded netmask (e.g. ff00::/ff00::) is not supported. ---------- assignee: docs@python components: Documentation messages: 230871 nosy: docs@python, pebenito priority: normal severity: normal status: open title: IPv6Network constructor docs incorrect about valid input type: behavior versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22822> _______________________________________

4 3

[issue25197] Allow documentation switcher to change url to /3/ and /dev/
by Matthias Bussonnier March 6, 2018

March 6, 2018

New submission from Matthias Bussonnier: The current documentation version switcher does not allow to get back to the `python.org/3/..` and `python.org/dev/...` url who permanently track the stable/developement release of Python the attached patch allows that and should permit in the long term less link on the internet to be out of date. ---------- assignee: docs@python components: Documentation files: docp.patch keywords: patch messages: 251177 nosy: docs@python, mbussonn priority: normal severity: normal status: open title: Allow documentation switcher to change url to /3/ and /dev/ type: enhancement Added file: http://bugs.python.org/file40529/docp.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25197> _______________________________________

4 3

[issue18855] Inconsistent README filenames
by Madison May March 1, 2018

March 1, 2018

New submission from Madison May: Is there any reason (other than backwards compatibility) that the names of README files are inconsistent? README: 3 instances - root, /Mac, /Misc, /Tools readme.txt: 2 instances - /PC, /PCbuild README.txt: 1 instance - /Doc ---------- assignee: docs@python components: Documentation messages: 196299 nosy: docs@python, madison.may priority: normal severity: normal status: open title: Inconsistent README filenames _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18855> _______________________________________

11 11