Mailman 3 November 2017 - docs

[issue20722] newline is (partially) independent of universal newlines; needs to be made more clear in docs
by Devin Jeanpierre 03 May '18

03 May '18

New submission from Devin Jeanpierre: http://docs.python.org/3.4/library/functions.html#open says "newline controls how universal newlines mode works (it only applies to text mode)." My reading of this when I saw it was that newline= doesn't do anything unless universal newlines mode is enabled. This is untrue, and you can infer it's untrue from the following lines, but then the docs appear to contradict themselves. Please fix to say something more along the lines of "newline controls how newlines are read and written. It only applies to text mode." The interactions with universal newlines mode are explained in the following text, so they don't need to be called out upfront. newline does more than just that. ---------- assignee: docs@python components: Documentation messages: 211854 nosy: Devin Jeanpierre, docs@python priority: normal severity: normal status: open title: newline is (partially) independent of universal newlines; needs to be made more clear in docs versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20722> _______________________________________

3 2

[issue24027] IMAP library lacks documentation about expected parameter types
by Pablo 21 Apr '18

21 Apr '18

New submission from Pablo: I used the IMAP library and I feel it lacks a lot of documentation regarding types and encoding. Example: IMAP4.list([directory[, pattern]]): It doesn't state if it expects the directory argument to be an string (unicode) or a imap_utf7 encoded string or bytes. It also expects names with spaces to be between double quotation marks and it doesn't state that it returns a bytes raw output. This is valid for every function that receives a directory or mailbox argument. Also for most return values. Documentation aside, I think it would be a nice improvement in the implementation to add an imap_utf7 convertion function, and check every directory or mailbox argument to see if it has characters outside the imap_utf7 charset and attempts to convert them automatically. ---------- assignee: docs@python components: Documentation messages: 241812 nosy: docs@python, pmoleri priority: normal severity: normal status: open title: IMAP library lacks documentation about expected parameter types type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24027> _______________________________________

3 2

[issue27544] Document checking dict types
by hannah 14 Apr '18

14 Apr '18

New submission from hannah: While there is documentation that dict.keys(), dict.values(), and dict.items() are now view objects(https://docs.python.org/3/library/stdtypes.html#dict-views), there's no mention dictviews, dict_keys, dict_values, and dict_items not being built-ins. This is confusing because type(dict.keys()) returns dict_keys, type(dict.values()) returns dict_values, etc., and the documentation uses `dictview` as the object signature, and so it's unclear how to do object introspection on dictview objects. The #python-dev channel suggested that the canonical way to do the object introspection is to use the collections.abc.mapview types; the documentation for dicts should reflect this (and that dictview and the rest are not __builtin__ types/in the python namspace). ---------- assignee: docs@python components: Documentation messages: 270672 nosy: docs@python, story645 priority: normal severity: normal status: open title: Document checking dict types type: enhancement versions: 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/issue27544> _______________________________________

4 5

[issue31584] Documentation Language mixed up
by asl 10 Apr '18

10 Apr '18

New submission from asl: Some of the documentation language are mixed up. eg: Japanese on the English page https://docs.python.org/2.7/faq/design.html French on the Japanese https://docs.python.org/ja/2.7/faq/design.html It seem to affect multiple pages: https://docs.python.org/2.7/bugs.html https://docs.python.org/2.7/distributing/index.html https://docs.python.org/2.7/extending/index.html https://docs.python.org/2.7/extending/extending.html The c-api pages https://docs.python.org/2.7/c-api/index.html The faq pages https://docs.python.org/2.7/faq/index.html And possibly others. ---------- assignee: docs@python components: Documentation messages: 303004 nosy: asl, docs@python priority: normal severity: normal status: open title: Documentation Language mixed up versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31584> _______________________________________

5 20

[issue28393] Update encoding lookup docs wrt #27938
by Ville Skyttä 04 Apr '18

04 Apr '18

New submission from Ville Skyttä: The attached patch brings codecs docs up to date with respect to changes in #27938. ---------- assignee: docs@python components: Documentation files: codecs-doc.patch keywords: patch messages: 278354 nosy: docs@python, haypo, scop priority: normal severity: normal status: open title: Update encoding lookup docs wrt #27938 type: enhancement Added file: http://bugs.python.org/file45030/codecs-doc.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28393> _______________________________________

5 12

[issue27212] Doc for itertools, 'islice()' implementation have unwanted behavior for recipe 'consume()'
by alex0307 02 Apr '18

02 Apr '18

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 24 Mar '18

24 Mar '18

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 22 Mar '18

22 Mar '18

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 22 Mar '18

22 Mar '18

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 16 Mar '18

16 Mar '18

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