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

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

Documentation?
by Mark Reese April 15, 2023

April 15, 2023

Hello, I was consulting the documentation section of the python site (for example https://docs.python.org/release/3.11.1/download.html) and when attempting to download the documentation for any file type of any version, it turns out none are available. Where can I get the documentation for the versions I seek. If you do not intend to host documentation on the site, there's no point in having such a section in the first place; it's important you remove it as it misleads visitors. Regards, - Mark

3 3

(no subject)
by Zhao Babycat March 23, 2023

March 23, 2023

Hello~ I found all the download link on Download �� Python 3.11.1 documentation<https://docs.python.org/release/3.11.1/download.html> web page will show 404��. Do the documents cannot be download now? If it is possible, would you please help me? Thank you very much! Windows �� `��<https://go.microsoft.com/fwlink/?LinkId=550986> ��

2 1

Documentation by Version Not Downloadable
by Julian Fortune March 23, 2023

March 23, 2023

Hey wonderful python docs maintainers, I noticed that from the Python Documentation by Version page <https://www.python.org/doc/versions/> if I navigate to a specific version of documentation—even a stable version—, e.g., `3.10.9`, when I go to *Download these documents* all the download links result in a 404 error. Example: https://docs.python.org/ftp/python/doc/3.10.9/python-3.10.9-docs-pdf-letter… *404 — Archive Not Found* > The archive you're trying to download has not been built yet. > Please try again later. Happy holidays and New Year; Thanks! Julian

3 3

Raw String Bug?
by garfield＠garfieldhudson.com March 7, 2023

March 7, 2023

Hi guys, Is this a bug with raw strings? If the last character of the string is a backslash, I get an unterminated string error. If I add another character, the error goes away. I thought that the r prefix rendered everything within the quotes as literals. Thanks, Garfield.

2 4

Unable to open the Python document with EPUB format
by Jae Wong March 1, 2023

March 1, 2023

Hi Python Document Team, I would like to let you know that the EPUB version of the Python document seems to have some file format issues. I used multiple readers and verifiers to test the EPUB file that is downloaded from https://docs.python.org/3/download.html, and all of them encountered some errors while parsing it. It is greatly appreciated if the errors in the file will be fixed. I really like the tutorial section of the Python document a lot and the EPUB format makes reading documents on small devices much easier. Thank you. Sincerely, Jae

2 1

Attention Required Vulnerability Founded
by Manpreet Singh Feb. 28, 2023

Feb. 28, 2023

Hello Team , I have founded vulnerability in your domain . Vulnerability :- Sensitive Information Disclosure Affected URL :- https://www.python.org/ftp/ Qualitative Severity Information :- HIGH Vulnerability Descriptions :- Directory Traversal To Python Mail servers By FTP. Steps To Reproduce :- 1. Open this URL :- https://www.python.org/ftp/python/ 2. In this you will see many directories that are disclosing . 3. Open Mail Directory you will find many mails , this is the URL :- https://www.python.org/ftp/python/mail/ 4. Click on any mail , it will automatically download the mail in gunzip format. 5. For Kali Users , type this command :- gunzip filename 6. After gunzip type this command in kali konsole :- leafpad filename , you will now see your python company mails that are hosted on FTP Protocol . Note :- If you can't understand how to do it , you can mail me i will then send POC video . Remediation :- Prevent this information from being displayed to the user. Thanking You, Manpreet Singh (Security Researcher)

2 1

Python 3.11, 3.10, 3.7 - all available on Google Android as Mobile Apps
by Mohee Feb. 25, 2023

Feb. 25, 2023

Dear, Kindly asking you to add my free Google Android mobile apps links at your Download website (https://docs.python.org/3/download.html), to enable all Python developers to download for free an offline version of Python complete documentation, for all Android devices and for all Android OS even the latest ones. For example, I made these Google Android mobile apps for Python offline documentations: 1. Python 3.11.1 offline docs app - link at Google Play: https://play.google.com/store/apps/details?id=com.mohee.jarada.python_3_11_… 2. Python 3.10 offline docs app - link at Google Play: https://play.google.com/store/apps/details?id=com.mohee.jarada.java.pythonc… 3. Python 3.7.4 offline docs app - link at Google Play: https://play.google.com/store/apps/details?id=hu.budapest.python.mohi1stapp… Much appreciated in advance, Best regards, Mohee Jarada Budapest - Hungary

1 0

Re: [Libguestfs] [PATCH 1/2] python: Avoid crash if callback parameters cannot be built
by Eric Blake Feb. 21, 2023

Feb. 21, 2023

From: Eric Blake <eblake(a)redhat.com> To: Laszlo Ersek <lersek(a)redhat.com>, docs(a)python.org Cc: Nir Soffer <nsoffer(a)redhat.com>, aryeyur(a)google.com, libguestfs(a)redhat.com, shtarkman(a)google.com Bcc: Subject: Re: [Libguestfs] [PATCH 1/2] python: Avoid crash if callback parameters cannot be built Reply-To: In-Reply-To: <c8259881-9fac-5987-8ac1-3286ff35adc1(a)redhat.com> [adding docs(a)python.org, in the hopes that this conversation can spur an improvement in Python's documentation] I'm trimming to just context on the doc issue at hand (this question spawned deep within a thread [1] to libguestfs reference counting bug in its Python bindings) [1] https://listman.redhat.com/archives/libguestfs/2023-February/030663.html On Tue, Feb 21, 2023 at 03:06:47PM +0100, Laszlo Ersek wrote: > On 2/20/23 21:52, Eric Blake wrote: > > On Mon, Feb 20, 2023 at 09:08:08PM +0200, Nir Soffer wrote: > >> On Mon, Feb 20, 2023 at 10:45 AM Laszlo Ersek <lersek(a)redhat.com> wrote: > >>> > >>> On 2/17/23 17:52, Eric Blake wrote: > >>>> On Thu, Feb 16, 2023 at 03:09:02PM +0100, Laszlo Ersek wrote: > >>> > >>>>> - Py_BuildValue with the "O" format specifier transfers the new list's > >>>>> *sole* reference (= ownership) to the just-built higher-level object "args" > >>>> > >>>> Reference transfer is done with "N", not "O". That would be an > >>>> alternative to decreasing the refcount of py_array on success, but not > >>>> eliminate the need to decrease the refcount on Py_BuildValue failure. > >>>> > >>>>> > >>>>> - when "args" is killed (decref'd), it takes care of "py_array". > >>>>> > >>>>> Consequently, if Py_BuildValue fails, "py_array" continues owning the > >>>>> new list -- and I believe that, if we take the new error branch, we leak > >>>>> the object pointed-to by "py_array". Is that the case? > >>>> > >>>> Not quite. "O" is different than "N". > >>> > >>> I agree with you *now*, looking up the "O" specification at > >>> <https://docs.python.org/3/c-api/arg.html#building-values>. > >>> > >>> However, when I was writing my email, I looked up Py_BuildValue at that > >>> time as well, just elsewhere. I don't know where. Really. And then that > >>> documentation said that the reference count would *not* be increased. I > >>> distinctly remember that, because it surprised me -- I actually recalled > >>> an *even earlier* experience reading the documentation, which had again > >>> stated that "O" would increase the reference count. > >> > >> Maybe here: > >> https://docs.python.org/2/c-api/arg.html#building-values > >> > >> Looks like another incompatibility between python 2 and 3. > > > > Or maybe misreading the wrong part of the page. PyArg_ParseTuple() > > and Py_BuildValue() are listed on the same page, and intentionally use > > similar-looking format strings, so you have to check _which_ part of > > the page the "O" you are reading about is associated with. The first > > "O" is under PyArg_ParseTuple() and friends, and intentionally does > > not increase reference count (the usesr passed us an Object, we are > > parsing it into a placeholder where we don't need to clean up after > > ourselves unless we want to add a reference to the object to make it > > last beyond the caller), the latter says that "O" does increase the > > reference count (we are building up a larger object that will now be > > an additional reference path into the object we are passing in). > > > > Yea, I'll just go ahead and call myself an idiot. :) > > (Please, please, make documentation fool-proof! I'm not an unrelenting, > unrepentant, principled fool, but still a fool.) > In short, the issue is that the Python documentation (even in the latest version at https://docs.python.org/3/c-api/arg.html) has TWO separate paradigms on the SAME page, and so many format characters that you can easily get lost in a wall of X (foo) [bar] designators that you can easily lose track of whether you are reading the docs for PyArg_ParseTuple() and friends with paradigm "X (Python source) [C destination]", or the docs for Py_BuildValue() with paradigm "X (Python destination) [C source]". When it comes to reference counting, there is a HUGE and IMPORTANT difference between the former: O (object) [PyObject *] Store a Python object (without any conversion) in a C object pointer. The C program thus receives the actual object that was passed. The object’s reference count is not increased. The pointer stored is not NULL. and the latter: O (object) [PyObject *] Pass a Python object untouched (except for its reference count, which is incremented by one). If the object passed in is a NULL pointer, it is assumed that this was caused because the call producing the argument found an error and set an exception. Therefore, Py_BuildValue() will return NULL but won’t raise an exception. If no exception has been raised yet, SystemError is set. But as neither instance of "O (object) [PyObject *]" is on the screen at the same time as the functions to which that format specifier is documenting, it is EASY for a novice coder to read the wrong one, and then get the wrong ideas about reference counting when using the "O" format specifier. My suggestion: a simple swap of the order of the Py_BuildValue() notations to: PyArg_ParseValue()... X (Python source) [C destination] Py_BuildValue()... X [C source] (Python destination] so that it is always source before destination, and always [] for the C counterpart and () for the Python counterpart. Another idea might be splitting the page into two, so that the two walls of format specifier text cannot be mistaken for one another when rapidly scrolling through the page looking for a given format letter; but I personally like both on the same page as the two sets of format specifiers are (intentionally) related, even if subtly different depending on direction. -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3266 Virtualization: qemu.org | libvirt.org

1 0