Mailman 3 February 2022 - 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

SMTPHandler secure argument without credentials
by William Edwards 15 Sep '22

15 Sep '22

logging.handlers.SMTPHandler only uses the 'secure' argument when credentials are specified. https://docs.python.org/3/library/logging.handlers.html#logging.handlers.SM… says: "To specify the use of a secure protocol (TLS), pass in a tuple to the secure argument. This will only be used when authentication credentials are supplied." The docstring confirms this, but I can't find an explanation of the intent behind this behaviour. Perhaps it would be a good idea to describe this as well.

1 1

correction proposed for Index in Strings 3.1.2
by Samuel DUNCAN 28 Feb '22

28 Feb '22

One way to remember how slices work is to think of the indices as pointing between characters, with the left edge of the first character numbered 0. Then the right edge of the last character of a string of n characters has index n, for example: +---+---+---+---+---+---+ | P | y | t | h | o | n | +---+---+---+---+---+---+ 0 1 2 3 4 5 6 -6 -5 -4 -3 -2 -1 However, the index of the last character is 5 not 6, granted the way it is stated the right edge of the last character has the number 6, but that is mixing index and count. You could say “Then the left edge of the last character of a string of n characters has index n-1, where n is the count of characters beginning at 1 (one)…” >>> y = ['P', 'y', 't', 'h', 'o', 'n'] >>> x = y.index("P") >>> print(x) 0 >>> x = y.index("o") >>> print(x) 4 >>> x = y.index("n") >>> print(x) 5 Sam Duncan Sent from Mail<https://go.microsoft.com/fwlink/?LinkId=550986> for Windows

1 0

A very minor proposed improvement to readability of 3.1.2. Strings - section on Slice
by Samuel DUNCAN 28 Feb '22

28 Feb '22

Currently reads: Note how the start is always included, and the end always excluded. This makes sure that s[:i] + s[i:] is always equal to s: >>> >>> word[:2] + word[2:] 'Python' >>> word[:4] + word[4:] 'Python' The statement “…and the end always excluded.” Is not true. If the end was excluded then s[:i] + s[i:] would never equal to s. If it excluded the end of the example “Python” then s would be “Pytho”, not “Python”. I was going to say “You could say “Note how the start is always included, and since an omitted first index defaults to zero, the end is always excluded. However, if you add “s[i:]” which defaults to the count (starting at 1) of the number of characters in the string being sliced, the end would also always be included.” >>> word[:2] 'Py' >>> word[2:] 'thon' Should a mention be made that including any number larger than the count (starting at 1) will always include the last character in the string with no error message? >>> word[2:6] 'thon' >>> word[2:7] 'thon' >>> word[2:8] 'thon' Sam Duncan Sent from Mail<https://go.microsoft.com/fwlink/?LinkId=550986> for Windows

1 0

A very minor proposed improvement to readability of 3.1.2. Strings - 2nd paragraph
by Samuel DUNCAN 28 Feb '22

28 Feb '22

“3.1.2. Strings” currently reads like this (emphasis added): In the interactive interpreter, the output string is enclosed in quotes and special characters are escaped with backslashes. While this might sometimes look different from the input (the enclosing quotes could change), the two strings are equivalent. The string is enclosed in double quotes if the string contains a single quote and no double quotes, otherwise it is enclosed in single quotes. The print() function produces a more readable output, by omitting the enclosing quotes and by printing escaped and special characters: Note: the beginning of the paragraph states,” special characters are escaped with backslashes”. This means the characters used to escape special characters escape special characters, the backslashes are not special characters when used to escape special characters. This is shown in the example (the special character is printed because print was used and the backslash was used to escape the special character): >>> print('"Isn\'t," they said.') "Isn't," they said. Please note the special character which is escaped is the “ ‘ “ (single quote). The character used to escape the special character is the “backslash” and, as shown in the example, the backslash is not printed. The suggestion is: The print() function produces a more readable output, by omitting the enclosing quotes, by printing escaped special characters, and by not printing the backslashes used to escape special characters: Or The print() function produces a more readable output, by omitting the enclosing quotes, the backslashes used to escape special characters, and by printing escaped special characters: Having it read as it is currently makes it sound like using print then prints escaped and special characters when the only characters which need to be escaped are special characters. Sam Duncan Sent from Mail<https://go.microsoft.com/fwlink/?LinkId=550986> for Windows

1 0

"..." instead of ">>>" in tutorial docs
by Carl 22 Feb '22

22 Feb '22

https://github.com/python/cpython/blob/main/Doc/tutorial/controlflow.rst#ke… 2nd code block of "for Statements" On line 2, "... words" (truncated) should be replaced with ">>> words" Full original block: >>> # Measure some strings: ... words = ['cat', 'window', 'defenestrate'] >>> for w in words: ... print(w, len(w)) ... cat 3 window 6 defenestrate 12 Full corrected block: >>> # Measure some strings: >>> words = ['cat', 'window', 'defenestrate'] >>> for w in words: ... print(w, len(w)) ... cat 3 window 6 defenestrate 12

1 0

doc translation fault
by 鄢龙翔 21 Feb '22

21 Feb '22

The Simplified Chinese translation has some faults. https://docs.python.org/zh-cn/3/tutorial/classes.html#python-scopes-and-nam… here, (Actually, forgetting would be a better way to describe what actually happens.) is wrongly translated to（事实上，比起描述到底发生了什么，忘掉它更好。） the English doc: [cid:image003.png@01D823E6.AFCE9030] The wrongly translated Simplified Chinese doc: [cid:image005.png@01D823E6.AFCE9030] Right translation should be like “实际上，用“遗忘”来描述实际发生的情况会更好。”

2 1

Error in Lists for heterogenous
by kid games 17 Feb '22

17 Feb '22

Hi Team, Type Error in doc for Lists can also store heterogenous items along with homogenous items. [image: image.png] Kind Regards, Ajay Takur ✆ : +91-8801282523 ````````````````````````````` Use what you know. Do what you've always imagined.

2 1

[Bug Report] List comprehension using variable in a Class raises NameError
by Wing Hong Wong 15 Feb '22

15 Feb '22

Hi, I have met the following bugs (Python version: 3.9.7). When I type the following code, it is complete fine. class ABC: a = 'a' b = [f'{a}'] However, when I write this code, it gives me error. Similar error happens not only for f-string, but also for addition of integer. class ABC: a = 'a' b = [f'{a}' for _ in range(1)] Traceback (most recent call last): File "C:\Users\user\AppData\Local\Temp/ipykernel_1384/2533654419.py", line 1, in <module> class ABC: File "C:\Users\user\AppData\Local\Temp/ipykernel_1384/2533654419.py", line 3, in ABC b = [f'{a}' for _ in range(1)] File "C:\Users\user\AppData\Local\Temp/ipykernel_1384/2533654419.py", line 3, in <listcomp> b = [f'{a}' for _ in range(1)] NameError: name 'a' is not defined Best, Hong

1 0

Documentation Bug: bitwise-operations-on-integer-types
by Fernando Santos 11 Feb '22

11 Feb '22

In the link https://docs.python.org/3.11/library/stdtypes.html#bitwise-operations-on-in… In the table, in the line ~x: I suggest to change "the bits of x inverted" by "Add the bit one to bits of x, and invert the most significant bit (negative indicator)" Add note (5) to ~x line Note 5: if "x" is an integer number then "~x" is equivalent to "(x + 1) * -1" and "~(~x)" is equivalent to "x"

1 0