Mailman 3 April 2019 - docs

[issue26303] Shared execution context between doctests in a module
by kernc 06 May '19

06 May '19

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 06 May '19

06 May '19

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

[issue35393] Typo in documentation
by Filip Bengtsson 06 May '19

06 May '19

New submission from Filip Bengtsson <filipbengtsson(a)live.se>: There are 256 characters in the range 0–255. ---------- assignee: docs@python components: Documentation messages: 330975 nosy: autom, docs@python priority: normal pull_requests: 10114 severity: normal status: open title: Typo in documentation _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35393> _______________________________________

3 3

[issue20906] Unicode HOWTO
by Graham Wideman 06 May '19

06 May '19

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

[issue34848] range.index only takes one argument when it's documented as taking the usual 3
by Dan Snider 04 May '19

04 May '19

New submission from Dan Snider <mr.assume.away(a)gmail.com>: Unfortunately, it looks like there's no requirement for an abc.Sequence to implement the 3 argument form of seq.index, so I suppose this is technically just a documentation bug... >>> range(5).index(2, 1) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: index() takes exactly one argument (2 given) >>> help(range.index) Help on method_descriptor: index(...) rangeobject.index(value, [start, [stop]]) -> integer -- return index of value. Raise ValueError if the value is not present. ---------- assignee: docs@python components: Argument Clinic, Documentation messages: 326701 nosy: bup, docs@python, larry priority: normal severity: normal status: open title: range.index only takes one argument when it's documented as taking the usual 3 versions: Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34848> _______________________________________

7 9

[issue27409] List socket.SO_*, SCM_*, MSG_*, IPPROTO_* symbols
by Martin Panter 03 May '19

03 May '19

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

[issue36329] use the right python "make -C Doc/ serve"
by Berker Peksag 01 May '19

01 May '19

Berker Peksag <berker.peksag(a)gmail.com> added the comment: Personally, I'd prefer removing the 'serve' target completely. make -C Doc htmlview should already cover most of its use cases. There is no deprecation period needed and there is already a replacement (and IMO better) for it. ---------- nosy: +berker.peksag _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36329> _______________________________________

2 2

[issue35329] Documentation - capitalization issue
by Hans Strijker 29 Apr '19

29 Apr '19

New submission from Hans Strijker <hans(a)stry.org>: In the documentation I noticed "from Package import specific_submodule". I recon package should be all lowercase in accordance with pep8. (https://www.python.org/dev/peps/pep-0008/#package-and-module-names) It may be far from the most important bug ever, but it's my first bug reported, and gotta start small... :-) https://docs.python.org/3/tutorial/modules.html#importing-from-a-package 6.4.1. Importing * From a Package ... Remember, there is nothing wrong with using from Package import specific_submodule! In fact, this is the recommended notation unless the importing module needs to use submodules with the same name from different packages. ---------- assignee: docs@python components: Documentation messages: 330537 nosy: Strijker, docs@python priority: normal severity: normal status: open title: Documentation - capitalization issue versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35329> _______________________________________

5 8

[issue23297] Clarify error when ‘tokenize.detect_encoding’ receives text
by Berker Peksag 28 Apr '19

28 Apr '19

Berker Peksag <berker.peksag(a)gmail.com> added the comment: The original problem has already been solved by making tokenize.generate_tokens() public in issue 12486. However, the same exception can be raised when tokenize.open() is used with tokenize.tokenize(), because it returns a text stream: https://github.com/python/cpython/blob/da63b321f63b697f75e7ab2f88f55d907f56… hello.py -------- def say_hello(): print("Hello, World!") say_hello() text.py ------- import tokenize with tokenize.open('hello.py') as f: token_gen = tokenize.tokenize(f.readline) for token in token_gen: print(token) When we pass f.readline to tokenize.tokenize(), the second call to detect_encoding() fails, because f.readline() returns str. In Lib/test/test_tokenize.py, it seems like tokenize.open() is only tested to open a file. Its output isn't passed to tokenize.tokenize(). Most of the tests either pass the readline() method of open(..., 'rb') or io.BytesIO() to tokenize.tokenize(). I will submit a documentation PR that suggests to use tokenize.generate_tokens() with tokenize.open(). ---------- assignee: -> docs@python components: +Documentation nosy: +docs@python versions: +Python 3.7, Python 3.8 -Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue23297> _______________________________________

2 1

[issue36715] Dictionary initialization
by Raymond Hettinger 28 Apr '19

28 Apr '19

Change by Raymond Hettinger <raymond.hettinger(a)gmail.com>: ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36715> _______________________________________

1 0