Mailman 3 June 2018 - docs

[issue11001] Various obvious errors in cookies documentation
by Luke Plant May 7, 2019

May 7, 2019

New submission from Luke Plant <L.Plant.98(a)cantab.net>: Docs for SimpleCookie, BaseCookie.value_encode and BaseCookie.value_decode are obviously incorrect. Attempt at patch attached. The error has existed in every Python version I've seen, I've tagged the ones I believe can receive fixes, sorry if I've made a mistake. Thanks. ---------- assignee: docs@python components: Documentation files: http_cookies_doc_corrections.diff keywords: patch messages: 126962 nosy: docs@python, spookylukey priority: normal severity: normal status: open title: Various obvious errors in cookies documentation versions: Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file20507/http_cookies_doc_corrections.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11001> _______________________________________

8 12

[issue22630] `concurrent.futures.Future.set_running_or_notify_cancel` does not notify cancel
by Ben Mather May 7, 2019

May 7, 2019

New submission from Ben Mather: The documentation for the `set_running_or_notify_cancel` method on `concurrent.futures.Future` states that it will notify waiting threads and trigger callbacks after the `Future` has been cancelled, however currently this is done immediately by the call to `cancel`. Oddly waiters (private interface used to implement `wait` and `as_completed`) do follow the behaviour documented for callbacks (they are called in `set_running_or_notify_cancel`) which means that they are not equivalent to setting a callback on each future. I have attached three possible patches: 1) "change-callbacks.patch" - this changes the behaviour to match the documentation. 2) "change-docs.patch" - this fixes the documentation to match the current behaviour. 3) "change-docs-and-waiters.patch" - in addition to fixing the documentation, this also fixes the inconsistency between waiters and callbacks by invoking waiters' `add_cancelled` method in `cancel`. I believe moving to the documented behaviour (1) would be a mistake as currently `set_running_or_notify_cancel` and the `RUNNING` state can be skipped entirely allowing Futures to be used just as a way to send results. Should mention that I have a separate patch (which I will submit separately (or here?)) that re-implements `wait` and `as_completed` using only publicly exposed methods. This makes it possible to extend or replace `Future` without having to preserve its private interface. Unfortunately this slightly breaks compatibility due to the difference between waiters and callbacks. I thought it would be best to discuss this issue first as I don't believe the current behaviour is as intended. ---------- assignee: docs@python components: Documentation, Library (Lib) files: change-callbacks.patch keywords: patch messages: 229282 nosy: bwhmather, docs@python priority: normal severity: normal status: open title: `concurrent.futures.Future.set_running_or_notify_cancel` does not notify cancel versions: Python 3.2, Python 3.3, Python 3.4, Python 3.5 Added file: http://bugs.python.org/file36908/change-callbacks.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22630> _______________________________________

4 6

[issue28795] Misleading stating, that SIGINT handler is installed by default
by Jan Velecký May 7, 2019

May 7, 2019

New submission from Jan Velecký: Hello, documentation (https://docs.python.org/2/library/signal.html) states, that Python by default installs SIGINT handler which cause KeyboardInterrupt. This is not true everytime according to implementation. "Python installs a small number of signal handlers by default: SIGPIPE ... and SIGINT is translated into a KeyboardInterrupt exception." It should also mention this "SIGINT is installed only, when default handler is set at startup.". Because user can run python script from non-interative shell as background task and SIGINT handler is not installed, regardless although user does not change Python default behaviour. Related SO: http://stackoverflow.com/questions/40775054/capturing-sigint-using-keyboard… ---------- assignee: docs@python components: Documentation messages: 281664 nosy: Jan Velecký, docs@python priority: normal severity: normal status: open title: Misleading stating, that SIGINT handler is installed by default type: behavior versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28795> _______________________________________

3 10

[issue32971] unittest.TestCase.assertRaises
by NODA, Kai May 6, 2019

May 6, 2019

New submission from NODA, Kai <nodakai(a)gmail.com>: https://docs.python.org/dev/library/unittest.html#unittest.TestCase.assertR… > If only the exception and possibly the msg arguments are given, return a context manager so that the code under test can be written inline rather than as a function: > > with self.assertRaises(SomeException): do_something() > > When used as a context manager, assertRaises() accepts the additional keyword argument msg. Perhaps we don't need the second sentence on the `msg` argument which isn't adding anything new. Ideally it should be more clear when the method operates in context manager mode. ("If only" and "possibly" don't play nicely together.) Maybe along the lines of "If no callable was passed as an argument ..." ? I haven't looked in to the actual implementation yet... ---------- assignee: docs@python components: Documentation messages: 313061 nosy: docs@python, nodakai priority: normal severity: normal status: open title: unittest.TestCase.assertRaises versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32971> _______________________________________

6 7

[issue33971] os.mknod is subject to "umask"
by James Stevens May 6, 2019

May 6, 2019

New submission from James Stevens <james.stevens(a)jrcs.co.uk>: As per the underlying "libc" call, the node created with "mknod" is subjected to the user's current umask setting. This is not made clear in the Python documentation, but the "libc" documentation makes this clear (see attached). ---------- assignee: docs@python components: Documentation files: Selection_2018-06-26_003.png messages: 320490 nosy: docs@python, james_r_c_stevens priority: normal severity: normal status: open title: os.mknod is subject to "umask" versions: Python 3.6 Added file: https://bugs.python.org/file47653/Selection_2018-06-26_003.png _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33971> _______________________________________

2 2

[issue26303] Shared execution context between doctests in a module
by kernc May 6, 2019

May 6, 2019

New submission from kernc: The doctest execution context documentation [0] says the tests get shallow *copies* of module's globals, so one test can't mingle with results of another. This makes it impossible to make literate modules such as: """ This module is about reusable doctests context. Examples -------- Let's prepare something the later examples can work with: >>> import foo >>> result = foo.Something() 2 """ class Bar: """ Class about something. >>> bar = Bar(foo) >>> bar.uses(foo) True """ def baz(self): """ Returns 3. >>> result + bar.baz() 5 """ return 3 I.e. one has to instantiate everything in every single test. The documentation says one can pass their own globals as `glob=your_dict`, but it doesn't mention the dict is *cleared* after the test run. Please acknowledge the use case of doctests in a module sharing their environment and results sometimes legitimately exists, and to make it future-compatible, please amend the final paragraph of the relevant part of documentation [0] like so: You can force use of your own dict as the execution context by passing `globs=your_dict` to `testmod()` or `testfile()` instead, e.g., to have all doctests in a module use the _same_ execution context (sharing variables), define a context like so: class Context(dict): def copy(self): return self def clear(self): pass and use it, optionally prepopulated with `M`'s globals: doctest.testmod(module, glob=Context(module.__dict__.copy())) Thank you! [0]: https://docs.python.org/3/library/doctest.html#what-s-the-execution-context ---------- assignee: docs@python components: Documentation messages: 259731 nosy: docs@python, kernc priority: normal severity: normal status: open title: Shared execution context between doctests in a module type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26303> _______________________________________

2 3

[issue33340] Inaccurate docs on `import` behaviour
by sam_b May 6, 2019

May 6, 2019

New submission from sam_b <sam(a)sambrown.eu>: The docs https://docs.python.org/3/tutorial/modules.html#the-module-search-path describe: > When a module named spam is imported, the interpreter first searches for a built-in module with that name. If not found, it then searches for a file named spam.py in a list of directories given by the variable sys.path. sys.path is initialized from these locations: > - The directory containing the input script (or the current directory when no file is specified). > - PYTHONPATH (a list of directory names, with the same syntax as the shell variable PATH). > - The installation-dependent default. However, it seems like "the directory containing the input script" is checked *before* the standard library: ➜ tmp more logging.py def foo(): print('bar') ➜ tmp python Python 2.7.15rc1 (default, Apr 15 2018, 21:51:34) [GCC 7.3.0] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> import logging >>> logging.foo() bar >>> logging.WARNING Traceback (most recent call last): File "<stdin>", line 1, in <module> AttributeError: 'module' object has no attribute 'WARNING' >>> Am I misunderstanding the docs? ---------- assignee: docs@python components: Documentation messages: 315653 nosy: docs@python, sam_b priority: normal severity: normal status: open title: Inaccurate docs on `import` behaviour type: behavior versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33340> _______________________________________

4 5

[issue20906] Unicode HOWTO
by Graham Wideman May 6, 2019

May 6, 2019

New submission from Graham Wideman: The Unicode HOWTO article is an attempt to help users wrap their minds around Unicode. There are some opportunities for improvement. Issues presented in order of the narrative: http://docs.python.org/3.3/howto/unicode.html History of Character Codes --------------------------- References to the 1980's are a bit off. "In the mid-1980s an Apple II BASIC program..." Assuming the comment is about the state of play in the mid-80's, then: The Apple II appeared in 1977. By 1985 we already had Macs, and PCs running DOS, which were capable of various character sets (not to mention lowercase letters!) "In the 1980s, almost all personal computers were 8-bit" Both the PC (1983) and Mac (1984) had 16-bit processors. Definitions: ------------ "Characters are abstractions": Not helpful unless one already knows what "abstraction" means in this specific context. "the symbol for ohms (Ω) is usually drawn much like the capital letter omega (Ω) in the Greek alphabet [...] but these are two different characters that have different meanings." Omega is a poor example for this concept. Omega is used as the identifier for a unit in the same way as "m" is used for meter, or "A" is used for ampere. Each is a specific use of a character, which, like any specific use, has a particular meaning. However, having a particular meaning doesn't necessarily require a separate character, and in the case of omega, the Unicode standard now says that the separate "ohm" character is deprecated. "The ohm sign is canonically equivalent to the capital omega, and normalization would remove any distinction." http://www.unicode.org/versions/Unicode4.0.0/ch07.pdf#search=%22character%2… A better example might be the roman numerals, code points U+2160 and subsequent. Definitions ------------ "A code point is an integer value, usually denoted in base 16." When trying to convey clearly the distinction between character, code point, and byte representation, the topic of "how it's denoted" is a potential distraction for the reader, so I suggest this point be a bit more explicitly parenthetical, and less confusable with "16 bit". Like: "A code point value is an integer in the range 0 to over 0x10FFFF (about 1.1 million, with some 110 thousand assigned so far). In a narrative such as the current article, a code point value is usually written in hexadecimal. The Unicode standard displays code points with the notation U+265E to mean the character with value 0x265e (9822 decimal; "Black Chess Knight" character)." (Also revise subsequent para to use same example character. I suggest not using "Ethiotic Syllable WI", because it's unfamiliar to most readers, and it muddies the topic by suggesting that Unicode in general captures _syllables_ rather than _characters_.) Encodings: ----------- "This sequence needs to be represented as a set of bytes" --> ""This code point sequence needs to be represented as a sequence of bytes" "4. Many Internet standards are defined in terms of textual data" This is a vague claim. Probably what was intended was: "Many Internet standards define protocols in which the data must contain no zero bytes, or zero bytes have special meaning." Is this actually true? Are there "many" such standards? "Generally people don’t use this encoding," Probably "people" per se don't use any encoding, computers do. --> "Because of these problems, other more efficient and convenient encodings have been devised and are commonly used. For continuity, directly after that para should come the later paras starting with "UTF-8 is one of the most common". "2. A Unicode string is turned into a string of bytes..." --> "2. A Unicode string is turned into a sequence of bytes..." (Ie: don't overload "string" in and article about strings and encodings.). Create a new subhead "Converting from Unicode to non-Unicode encodings", and move under it the paras: "Encodings don't have to..." "Latin-1, also known as..." "Encodings don't have to..." But also revise: "Encodings don’t have to handle every possible Unicode character, and most encodings don’t." --> "Non-Unicode code systems usually don't handle all of the characters to be found in Unicode." ---------- assignee: docs@python components: Documentation messages: 213367 nosy: docs@python, gwideman priority: normal severity: normal status: open title: Unicode HOWTO type: enhancement 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/issue20906> _______________________________________

12 27

[issue27409] List socket.SO_*, SCM_*, MSG_*, IPPROTO_* symbols
by Martin Panter May 3, 2019

May 3, 2019

New submission from Martin Panter: The documentation just says that SO_* etc constants are defined. However when people add new ones, they add them as new features to a specific version (not backported as bug fixes), but do not alter the documentation at all. IMO it is silly adding undocumented features. E.g. Issue 26907 was opened to add (among others) SO_PASSCRED, which was already added, undocumented, as part of Issue 6560. This patch attempts to indicate which symbols are defined by Python (depending on OS availability), and therefore one can deduce if Python does not define a particular symbol. It could be adapted to the 2.7 documentation, but I am not really motivated for that on my own. I also remove a redundant definition in the module, and removed a conditional because SO_REUSEADDR is required to always be defined according to the test suite. These specific changes should only be applied to 3.6. I also found Issue 1732367, which has a patch documenting each AF_* symbol in a little more detail. That patch was never updated nor comitted, but it sounds like this kind of addition might be acceptable. ---------- assignee: docs@python components: Documentation files: socket-const.patch keywords: patch messages: 269460 nosy: docs@python, martin.panter priority: normal severity: normal stage: patch review status: open title: List socket.SO_*, SCM_*, MSG_*, IPPROTO_* symbols versions: Python 3.5, Python 3.6 Added file: http://bugs.python.org/file43573/socket-const.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27409> _______________________________________

4 3

[issue18675] Daemon Threads can seg fault
by Thomas Guettler April 27, 2019

April 27, 2019

New submission from Thomas Guettler: This is a documentation bug: Since #1856 is not solved for Python2, it needs to be documented. Daemon Threads on Python2 can seg fault. Work arounds: http://stackoverflow.com/questions/18098475/detect-interpreter-shut-down-in… ---------- assignee: docs@python components: Documentation messages: 194601 nosy: docs@python, guettli priority: normal severity: normal status: open title: Daemon Threads can seg fault versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18675> _______________________________________

4 5