Mailman 3 September 2020 - docs

A suggestion for improving the documentation of chapter 10.9. Data Compression
by Guy Goldner 22 May '24

22 May '24

Hello dear Python gods :) I'm new at Python and was going over the documentation . This useful paragraph : https://docs.python.org/3.7/tutorial/stdlib.html#data-compression provides info for compressing text but IMHO some important additional info is needed, without which I expect nearly all users would get stuck just as I have. Moreover, while looking for a solution I noticed a lot of articles with outdated examples which no longer work - this confused me even more to the point I started suspecting something was amiss on my end... Anyhow, adding this info would do the trick : zlib works only with bytes and in Python 3.x strings are no longer bytes. Example : *>>> zlib.compress('this is a sample string which does not work in zlib because it requires bytes and not unicode')Traceback (most recent call last): File "<stdin>", line 1, in <module>TypeError: a bytes-like object is required, not 'str'>>>* Luckily Python has a very simple solution for this : encode to utf-8, compress, decode back to unicode like so : *>>> text = 'this is a sample string which does not work in zlib because it requires bytes and not unicode with chars like this »שלום '>>> encoded = text.encode()>>> text = 'this is a sample with unicode chars »שלום '>>> encoded = text.encode()>>> compressed = zlib.compress(encoded)>>> decompressed = zlib.decompress(compressed)>>> decoded = decompressed.decode()>>> len(text),len(encoded),len(compressed) #notice that compression of short strings can be larger than the original(42, 47, 54)>>> print(text,'\n',encoded,'\n',compressed)this is a sample with unicode chars »שלום b'this is a sample with unicode chars \xc2\xbb\xd7\xa9\xd7\x9c\xd7\x95\xd7\x9d ' b'x\x9c+\xc9\xc8,V\x00\xa2D\x85\xe2\xc4\xdc\x82\x9cT\x85\xf2\xcc\x92\x0c\x85\xd2\xbc\xcc\xe4\xfc\x94T\x85\xe4\x8c\xc4\xa2b\x85C\xbb\xaf\xaf\xbc>\xe7\xfa\xd4\xebs\x15\x00\xb2K\x14|'>>> text == decodedTrue* Thank you ! You are doing a great thing ! B.R., Guy Goldner

2 2

[issue38352] In typing docs, note explicit import needed for IO and Pattern/Match
by Karl Kornel 04 May '21

04 May '21

New submission from Karl Kornel <karl(a)kornel.us>: Hello! In https://github.com/python/cpython/blob/master/Lib/typing.py#L115-L117, there is a note about the io and re classes not being included in typing.__all__. I am a relatively new user of typing, and I did `from typing import *` in my code. I ran the code through mypy first, which reported no problems, but then running Python 3.6 failed with a NameError (name 'IO' is not defined). Reading through the typing source, it's clear that this was an intentional decision. So, instead of reporting a bug, I'd like to request a documentation enhancement! The docs for typing make no mention of typing.io or typing.re. So, my request is: In the sections for the IO/TextIO/BinaryIO and Pattern/Match classes, include text warning the user that these types are not imported when you do `from typing import *`. ---------- assignee: docs@python components: Documentation messages: 353763 nosy: Karl Kornel, docs@python priority: normal severity: normal status: open title: In typing docs, note explicit import needed for IO and Pattern/Match type: behavior versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38352> _______________________________________

8 12

[issue38291] Unclear status of the typing.io and typing.re pseudo-modules in docs and runtime
by dgelessus 03 May '21

03 May '21

New submission from dgelessus <dgelessus+bugs.python.org(a)me.com>: According to bpo-35089 (and the GitHub issues linked there), the typing.io and typing.re modules should no longer be used. Starting with Python 3.6, the typing documentation no longer mentions the typing.io and typing.re modules, and instead documents their contents as part of the main typing module. However, the typing module at runtime still supports typing.io and typing.re as before. Since these modules are not meant to be used anymore and are no longer documented, I would expect at least a DeprecationWarning when using them at runtime. The documentation on this could also be a bit clearer. As long as the modules are still supported at runtime, I would expect the documentation to mention that they still exist, but shouldn't be used anymore. In its current state, the documentation is confusing when coming from Python 3.5 (where typing.io and typing.re were the only documented way to access IO, Pattern, etc., but accessing typing.IO and typing.Pattern directly also works at runtime). ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 353356 nosy: dgelessus, docs@python priority: normal severity: normal status: open title: Unclear status of the typing.io and typing.re pseudo-modules in docs and runtime type: behavior versions: Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38291> _______________________________________

4 3

[issue32752] no information about accessing typing.Generic type arguments
by Paul Pinterits 02 May '21

02 May '21

New submission from Paul Pinterits <rawing7(a)gmail.com>: The documentation of the typing module explains how to instantiate generic types, but there is no information about how to extract the type arguments from a generic type. Example: >>> list_of_ints = typing.List[int] >>> >>> # how do we get <class 'int'> out of list_of_ints? >>> list_of_ints.??? <class 'int'> Through trial and error I've discovered list_of_ints.__args__, which *seems* to be what I'm looking for, but since it's never mentioned in the docs, it's unclear whether this __args__ attribute is an implementation detail or not. Please document the official/intended way to extract type arguments from a Generic. ---------- assignee: docs@python components: Documentation messages: 311520 nosy: Paul Pinterits, docs@python priority: normal severity: normal status: open title: no information about accessing typing.Generic type arguments type: enhancement versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32752> _______________________________________

6 6

[issue41411] Improve and consolidate f-strings docs
by Ezio Melotti 02 May '21

02 May '21

New submission from Ezio Melotti <ezio.melotti(a)gmail.com>: [Creating a new issue from #41045] I was just just trying to link to someone the documentation for f-strings, but: 1) Searching "fstring" only returns two results about xdrlib[0]; 2) Searching "f-string" returns many unrelated results[1]; 3) The first (and closer) result (string -- Common string operations[2]) yields nothing while using ctrl+f with fstring, f-string, f', f"; 4) at the top of that page there are two links in a "see also": * Text Sequence Type — str[3]: it mentions raw strings at the beginning, but also yields no results for fstring, f-string, f', f"; * String Methods[4]: that is another section of the previous page (so ctrl+f doesn't find anything), but has a link to "Format String Syntax"[5]; 5) The "Format String Syntax" page[5] has another link in the middle of a paragraph that points to "formatted string literals", that eventually brings us to the right page[6]; 6) the "right page"[6] has a wall of text with a block of code containing the grammar, luckily followed by a few examples. I think we should: 1) add index entries for "f-string" and "fstring" in the relevant sections of the docs, so that they appear in the search result; 2) in the Text Sequence Type — str[3] section, have a bullet list for f-strings, raw-strings, and possibly u-strings; 3) possibly use the term "f-string" in addition (or instead) of "formatted string literal", to make the pages more ctrl+f-friendly throughout the docs; 4) possibly have another more newbie-friendly section on f-string (compared to the lexical analysis page) in the tutorial, in the stdtypes page[7] (e.g. before the printf-style String Formatting" section[8]), or in the string page[2] (e.g. after the "Format String Syntax" section[10]); 5) possibly reorganize and consolidate the different sections about strings, string methods, str.format(), the format mini-language, f-strings, raw/unicode-strings, %-style formatting in a single page or two (a page for the docs and one for the grammar), since it seems to me that over the years these sections got a bit scattered around as they were being added. [0]: https://docs.python.org/3/search.html?q=fstring [1]: https://docs.python.org/3/search.html?q=f-string [2]: https://docs.python.org/3/library/string.html [3]: https://docs.python.org/3/library/stdtypes.html#textseq [4]: https://docs.python.org/3/library/stdtypes.html#string-methods [5]: https://docs.python.org/3/library/string.html#formatstrings [6]: https://docs.python.org/3/reference/lexical_analysis.html#f-strings [7]: https://docs.python.org/3/library/stdtypes.html [8]: https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatt… ---------- assignee: docs@python components: Documentation messages: 374398 nosy: docs@python, eric.smith, ezio.melotti priority: normal severity: normal stage: needs patch status: open title: Improve and consolidate f-strings docs type: enhancement versions: Python 3.10, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue41411> _______________________________________

6 13

[issue22167] iglob() has misleading documentation (does indeed store names internally)
by Roy Smith 30 Apr '21

30 Apr '21

New submission from Roy Smith: For background, see: https://mail.python.org/pipermail/python-list/2014-August/676291.html In a nutshell, the iglob() docs say, "Return an iterator which yields the same values as glob() without actually storing them all simultaneously." The problem is, internally, it calls os.listdir(), which apparently *does* store the entire list internally, defeating the whole purpose of iglob() I recognize that iglob() is not going to get fixed in 2.7, but at least the documentation should be updated to point out that it doesn't really do what it says it does. Or rather, it doesn't really not do what it says it doesn't :-) ---------- assignee: docs@python components: Documentation messages: 225048 nosy: docs@python, roysmith priority: normal severity: normal status: open title: iglob() has misleading documentation (does indeed store names internally) type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22167> _______________________________________

8 19

[issue32824] Docs: Using Python on a Macintosh has bad info per Apple site
by Frank Griswold 29 Apr '21

29 Apr '21

New submission from Frank Griswold <py.griswolf(a)spamgourmet.com>: This chunk of docs has bad info in both Python2 and Python3 docs: 4.1.3. Configuration Python on OS X honors all standard Unix environment variables such as PYTHONPATH, but setting these variables for programs started from the Finder is non-standard as the Finder does not read your .profile or .cshrc at startup. You need to create a file ~/.MacOSX/environment.plist. See Apple’s Technical Document QA1067 for details. If you search for QA1067, you are informed that the document is legacy and unsupported, with a suggestion for where to look now. That suggested link leads to a 404. Searching the apple site, I find that at least some thoughtful developers think that configuring the environment isn't even possible, generally; and isn't considered good form even if so. Here: https://forums.developer.apple.com/message/217422 I have no problem setting things for my terminal, as a longtime (unix) user, but for others, this section probably needs a complete examination with an eye toward making it current. quite possibly by reorganizing it. ---------- assignee: docs@python components: Documentation messages: 312023 nosy: docs@python, griswolf priority: normal severity: normal status: open title: Docs: Using Python on a Macintosh has bad info per Apple site type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32824> _______________________________________

7 10

[issue23750] Clarify difference between os.system/subprocess.call in section "Replacing os.system()"
by Andreas Sommer 28 Apr '21

28 Apr '21

New submission from Andreas Sommer: Reading over the section "Replacing os.system()" (https://docs.python.org/2/library/subprocess.html#replacing-os-system), one might assume that the return value of os.system and subprocess.call are equivalent. status = os.system("mycmd" + " myarg") # becomes status = subprocess.call("mycmd" + " myarg", shell=True) However, they are not. Example: import sys import os import subprocess print subprocess.call("false") print os.system("false") gives 1 and 256, respectively. Maybe this could be rephrased for clarity, or a hint added. ---------- assignee: docs@python components: Documentation messages: 239028 nosy: Andreas Sommer, docs@python priority: normal severity: normal status: open title: Clarify difference between os.system/subprocess.call in section "Replacing os.system()" type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23750> _______________________________________

3 3

[issue24475] The docs never define what a pool "task" is
by Zahari Dim 28 Apr '21

28 Apr '21

New submission from Zahari Dim: See: http://stackoverflow.com/questions/30943161/multiprocessing-pool-with-maxta… The documentation never makes clear what a "task" in the context of Pool.map. At best, it says: "This method chops the iterable into a number of chunks which it submits to the process pool as separate tasks. The (approximate) size of these chunks can be specified by setting chunksize to a positive integer." in the map documentation. However it does not say how this chunks are calculated by default, making the maxtasksperchild argument not very useful. The fact that a function evaluated by map is not a "task" should be much clearer in the documentation. Also, in the examples, such as: with multiprocessing.Pool(PROCESSES) as pool: # # Tests # TASKS = [(mul, (i, 7)) for i in range(10)] + \ [(plus, (i, 8)) for i in range(10)] results = [pool.apply_async(calculate, t) for t in TASKS] imap_it = pool.imap(calculatestar, TASKS) imap_unordered_it = pool.imap_unordered(calculatestar, TASKS) TASKS are not actually "tasks" but rather "task groups". ---------- assignee: docs@python components: Documentation messages: 245509 nosy: Zahari.Dim, docs@python priority: normal severity: normal status: open title: The docs never define what a pool "task" is 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/issue24475> _______________________________________

5 4

[issue11975] Fix intersphinx-ing of built-in types (list, int, ...)
by Jonas H. 28 Apr '21

28 Apr '21

New submission from Jonas H. <jonas(a)lophus.org>: Intersphinx-ing of int, list, float, ... should work with ":class:`int`" (list, float, ...). Also, intersphinx-ing list methods, e.g. ":meth:`list.insert`", should work. ---------- assignee: docs@python components: Documentation messages: 134923 nosy: docs@python, jonash priority: normal severity: normal status: open title: Fix intersphinx-ing of built-in types (list, int, ...) _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11975> _______________________________________

11 50