Mailman 3 August 2023 - docs

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

May 22, 2024

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

Potential typo in Profiler docs?
by 2dfkit Nov. 9, 2023

Nov. 9, 2023

In the[profiler docs](https://docs.python.org/3/library/profile.html), under the first profiler output example, it says > ... The next line:Ordered by: cumulative time, indicates that the text string in the far right column was used to sort the output. This doesn't appear to make sense, and indeed the example output is sorted by the "cumtime" column, and not by the text string column at the far right. Am I misreading this or is this a typo? Thanks! PS. Sorry I didn't raise a ticket, I'm new and shy about posting in public forums

3 5

about deprecated document
by SUN Guonian Nov. 9, 2023

Nov. 9, 2023

hi, When I browse subprocess document on (https://docs.python.org/3.11/library/subprocess.html) I find some piece about "Replacing os.popen(), os.popen2(), os.popen3()", but I can't find any popen3() in module os, untill I search the document to version 2.7. Maybe the content related to the deprecated document should be cleaned in the latest version. Best Regards, SUN Guonian

2 1

Problem in help for str().rsplit()
by Alan Brogan Nov. 9, 2023

Nov. 9, 2023

Greetings to the list Not sure where this report should be sent, so I’m hoping the good people on this list can help to forward it on. The docs suggest I should distinguish a bug as being either of the docs, or of the implementation, but this one is in the docstring of the function, so which does that count as??? What I would call "the docs” (https://docs.python.org/3/library/stdtypes.html?highlight=rsplit#str.rsplit <https://docs.python.org/3/library/stdtypes.html?highlight=rsplit#str.rsplit>) explains the function differently, and is (AFAICT) correct Problem is in docstring for the str().rsplit() method: >>> help(str().rsplit) Help on built-in function rsplit: rsplit(sep=None, maxsplit=-1) method of builtins.str instance Return a list of the substrings in the string, using sep as the separator string. sep The separator used to split the string. When set to None (the default value), will split on any whitespace character (including \\n \\r \\t \\f and spaces) and will discard empty strings from the result. maxsplit Maximum number of splits (starting from the left). -1 (the default value) means no limit. Splitting starts at the end of the string and works to the front. Problem is at the phrase "(starting from the left)” I think that should actually say “starting from the right”, because >>> s = "alan was here today" >>> s.rsplit(" ", 1) ['alan was here', 'today'] -- Alan

2 1

Errors in 3.11.4 EPUB version
by Ranjith B Nov. 9, 2023

Nov. 9, 2023

Dear Python community, The EPUB version for 3.11.4 is not readable. Each page contains errors like the following: “This page contains the following errors: error on line 22 at column 19: Specification mandates value for attribute defer Below is a rendering of the page up to the first error.” Please fix the issue. Thank you, Best Regards, Ranjith

2 1

EPUB version of documenation
by Glenn Street Nov. 9, 2023

Nov. 9, 2023

Hi! When I try to open the EPUB version of the Python documentation from Download Python 3.11.4 Documentation <https://docs.python.org/3/archives/python-3.11.4-docs.epub> using Apple’s Books program, i get the following error on every page. Please advise. Best wishes, Glenn Street

2 1

Data type range printed wrong ?
by Shivansh Verma Nov. 9, 2023

Nov. 9, 2023

https://docs.python.org/3/library/array.html In the above given url which lead to a page of array module in documentation, on that page a table regarding the typecodes of the array is given, in that table the size range of the signed and unsigned int of typecode "i" is given as 2 bytes which I think should be 4 bytes instead, as even using that data type on an array and using function itemsize() on it also return 4 bytes. Though I do have some confusion regarding the column 'minimum size in bytes' of the table, does minimum size in bytes means something other than the range of that data type in bytes? If in case that is actually an error and minimum size in bytes means the range of data types in bytes than I would request you to please have a look at it, else I apologise for this mail and wasting your time in advance, but please let me know what does the minimum data size in bytes actually mean then, and why it is 2 bytes instead of 4 bytes for signed and unsigned int of typecode "i".

2 1

bug reports for the documentation (mainly the tutorial)
by Stephan Stiller Oct. 30, 2023

Oct. 30, 2023

Dear list, I recently read through the entire Python tutorial and FAQ (v3.11.2) and took notes on things that I believe to be errata. Here is my list: 1. https://docs.python.org/3/tutorial/controlflow.html I think it would be better if there were a pastable space after "144 233 377 610 987 1597" (and in some other places in the tutorial). My guess is that the present formatting has to do with the way these pages are generated. 2. https://docs.python.org/3/library/stdtypes.html#dict.get I think "get(key[, default=None])" would be better than "change get(key[, default]). 3. https://docs.python.org/3/library/stdtypes.html#mapping-types-dict It seems that "sorted(d)" is missing from the documentation, at least on this page. The output (sorted list of all keys) is not predictable for a beginner, so it might be better to be explicit. 4. https://docs.python.org/3/tutorial/modules.html About the instruction for loading "fibo" ("Now enter the Python interpreter and import this module with the following command:"): Many beginners will be using IDLE. If on Windows, one needs to import the file like this: import sys sys.path.append(r'C:\path_to_directory_with_fibo') import fibo Adding a remark like this will help the reader. 5. https://docs.python.org/3/tutorial/inputoutput.html The '{:-9} YES votes {:2.2%}'.format(yes_votes, percentage) example will slow a careful first-time reader down. I suggest explaining the two expressions in curly braces briefly on the side, in one sentence each. 6. https://docs.python.org/3/tutorial/inputoutput.html#old-string-formatting I would replace the second sentence by something like the following For the expression "format % values", "%" conversion specifications in "format" are replaced with zero or more elements of "values". or something similar adapted from here: https://docs.python.org/3/library/stdtypes.html#old-string-formatting 7. https://docs.python.org/3/library/functions.html#open I strongly suggest replacing "buffering=- 1" by "buffering= -1". I suspect this might be a systematic bug generated by a formatter. Similarly, here https://docs.python.org/3/library/stdtypes.html#str.split I would replace "str.split(sep=None, maxsplit=- 1)" by "str.split(sep=None, maxsplit= -1)". In both cases, deleting the space entirely is an alternative option. 8. https://docs.python.org/3/tutorial/errors.html#exceptions If I understand correctly, I believe it will be clearer if "and execution stops with a message as shown above" is shortened to simply "and execution stops". 9. https://docs.python.org/3/faq/extending.html#how-do-i-extract-c-values-from… "PyListSize()" should probably read "PyList_Size()". General comments: I believe that a HOWTO on "object-oriented programming" best practices in Python would be useful. Perhaps there is one, but I couldn't find it. Best regards, Stephan Stiller

2 1

https://docs.python.org/3/library/timeit.html
by Goldberg, Arthur P Oct. 30, 2023

Oct. 30, 2023

Hello In this section This is a convenience function that calls timeit()<https://docs.python.org/3/library/timeit.html#timeit.Timer.timeit> repeatedly so that the total time >= 0.2 second, returning the eventual (number of loops, time taken for that number of loops). It calls timeit()<https://docs.python.org/3/library/timeit.html#timeit.Timer.timeit> with increasing numbers from the sequence 1, 2, 5, 10, 20, 50, … until the time taken is at least 0.2 second. s/second/seconds/ two times. “seconds” is properly plural elsewhere on the page. Thanks A -- Arthur Goldberg, PhD Mount Sinai Data Warehouse<https://labs.icahn.mssm.edu/msdw/> Scientific Computing and Data<https://labs.icahn.mssm.edu/minervalab/scientific-computing-and-data> Associate Professor of Genetics and Genomic Sciences Institute for Data Science and Genomic Technology Mount Sinai School of Medicine Arthur.Goldberg(a)mssm.edu<mailto:Arthur.Goldberg@mssm.edu> 646 526 5020 Zoom<https://mssm.zoom.us/my/arthur.goldberg?pwd=LzByMGJOZC9wM3A2aHV6OU94eUtSQT09>

2 1

Howto/regex omits the simplest {n} case
by Derek Mead Oct. 30, 2023

Oct. 30, 2023

Hi, https://docs.python.org/3/howto/regex.html#repeating-things states: *You can omit either m or n; in that case, a reasonable value is assumed for the missing value. Omitting m is interpreted as a lower limit of 0, while omitting n results in an upper bound of infinity.* This is correct, for the cases of {m,} and {,n}. What isn't covered is the simplest case {m} which matches the preceding item exactly m times. Regards, Derek PS https://docs.python.org/3/howto/regex.html is generally one of the best bits of software documentation I have come across: it's a model of simplicity and clarity, on a notoriously difficult topic.

2 1

Typo in code snippet
by Nuraly Oct. 30, 2023

Oct. 30, 2023

https://docs.python.org/3/library/asyncio-task.html#shielding-from-cancella… In this endpoint there is a typo Namely, The statement: task = asyncio.create_task(something()) res = await shield(task) is equivalent to: res = await something() should be The statement: task = asyncio.create_task(something()) res = await shield(task) is equivalent to: res = await shield(something()) Respectfully, Dyussenov Nuraly

2 1

Document bug
by deblake60 Aug. 29, 2023

Aug. 29, 2023

Hi, I am trying to learn python. I started to read page on of your doc, but when I was ready to go to the next page, it wouldn't respond. I refreshed my browser and received the same issue. I attempted this with MS Edge, FireFox and Chrome, all with the same results. Is there any possible way I could receive a copy of the document file, please? I really want to learn python (3.11.5) I appreciate your efforts, thank you. Sincerely, David Blake

2 1

Python Interpreter Compatibility with Windows 7
by Nagib Attiê Aug. 27, 2023

Aug. 27, 2023

Hello, I hope this email finds you well. I am currently facing an issue with the Python interpreter on my Windows 7 system. It seems that the current version is not compatible with this operating system. I was wondering if there is an earlier version of the Python interpreter that supports Windows 7? If so, could you kindly provide me with the download link or any instructions on how to obtain it? Thank you very much for your assistance. I look forward to your prompt response. Best regards, Nagib

2 1

the python library reference
by Luis Jose Mota Vegas Aug. 25, 2023

Aug. 25, 2023

good evening my cordial greetings, I am the software engineer Luis Mota I am writing to the python software foundation, to please request that they send me the latest publication The Python Library Reference as the release 3.8 made in 2020. Thank you for your greater understanding to do aid. I say goodbye without further ado -- [image: twitter] <https://codemasteer/> [image: instagram] <https://codemasteer/> Luis José Mota Vegas Ingeniero I Administración de Personal | Gobernación Programación, Administración Avanzada G.N.U/Linux, Mantenimiento del Computador 02877211795 | 04249399758 luis19jose98(a)gmail.com Delta Amacuro, Tucupita, Hacienda del Medio

1 0

REQUEST FOR COMPLETE DOCUMENTATION
by Dr. Sanjay Mohan Sharma Aug. 17, 2023

Aug. 17, 2023

Dear Team, If possible, kindly send me the complete documentation of Python. Thanks -- Sanjay Mohan Assistant Professor School of Mechanical Engineering Shri Mata Vaishno Devi University Katra-182320(Udhampur) Jammu Jammu & Kashmir India 01991-285535,285573 Ext:2354 Mob: 9797301889 Website: www.smvdu.ac.in

2 1

Typo in the docs for `struct`?
by Lampe2020 Aug. 14, 2023

Aug. 14, 2023

1 0

A HUMBLE REQUEST
by Ayodeji Adeoye Aug. 14, 2023

Aug. 14, 2023

Dear Sir/ ma, Great to have you there! I am Ayodeji ADEOYE. I am a beginner at learning Python Programming Language with keen interest. Right now, I am confused with getting the right material to learn this course with a lots here and there in the Web. Can you please lend me some assistance by sending me the link to source for the right material. Better still, can you please send to me the e-materials to put me through in time. I bounced into this email account online. In anticipation of your response sir/ma, I say thank you very much and God bless you Ayodeji ADEOYE

1 0

An error in documentation
by Maksym Nikulyak Aug. 11, 2023

Aug. 11, 2023

Hi, On the https://docs.python.org/3/library/stdtypes.html#mutable-sequence-types page, in the "Mutable Sequence Types" section, there is a table having the following row: s.insert(i, x) inserts *x* into *s* at the index given by *i* (same as s[i:i] = [x]) The text in the parentheses is incorrect there: the two commands have not the same but different effects. Thank you for your work! Maksym

1 0

documentation in azw3 and mobi format
by Bruno Prado Aug. 8, 2023

Aug. 8, 2023

Hi ! Could you provide a version of the documentation in .mobi or .azw3 format ? I will be better to read on kindle Best Bruno

1 0

Error from the EPUB Format (Python 3.11.4 Documentation)
by seunghan ryoo Aug. 4, 2023

Aug. 4, 2023

When I open the file, It shows the same error message through all pages of it. ========================================================================================= “This page contains the following errors:error on line 22 at column 19: Specification mandates value for attribute defer Below is a rendering of the page up to the first error.” Excerpt From Python Python Documentation Authors This material may be protected by copyright. ========================================================================================= For your consideration, I’m using iMac 27 2020 / macOS Monterey v12.6.3. Thank you.

2 1

New translation coordinators for Chinese (Simplified)
by Nyuan Zhang Aug. 3, 2023

Aug. 3, 2023

Hi all, Thanks for your kind attention and support. he agreed to make me and @Dumeng (alphanow(a)gmail.com) the new translation coordinators for Chinese (Simplified). He also tried to email this list directly to check if there was anything else left in the procedure, but his emails bounced back. Anyway, now we have granted access to the GitHub repository and transifex projects, and we hope to push the completeness of the translation further. Best regards, Nyuan Zhang

1 0

We need a new coordinator for Simplified Chinese translation
by alphanow＠foxmail.com Aug. 1, 2023

Aug. 1, 2023

Hi WG members, Hope you all are well. I'm writing this email to ask for help, as the sync pipeline for Simplified Chinese document translations has been broken for a long time. The workflow is hosted on GitHub Action(https://github.com/python/python-docs-zh-cn/tree/master). And its last success was already 8 months ago(https://github.com/python/python-docs-zh-cn/actions?query=is%3Asuccess+…. Our contributors have prepared a fix for the workflow. However, we cannot reach out to the current maintainer of this repo to merge it. And we have tried to ask in the translation mail list (https://mail.python.org/archives/list/translation@python.org/thread/YOPHUNQ…), but it seems there is no response. So, would you like to assign a new coordinator or maintainer for the repo? Then we can work together to fix the issue. Thx & B.Rgds Du, Meng

4 6