Mailman 3 January 2024 - 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

doc bug re float() OverflowError?
by Andrew Booth 30 Jan '24

30 Jan '24

Hi, In https://docs.python.org/3/library/functions.html#float I see: If the argument is outside the range of a Python float, an OverflowError will be raised. but when I try to produce an OverflowError, instead the float is rounded to inf. I'm not clear if this is a doc bug, an error with the implementation of Ubuntu python 3.11.6, or an error with my test. Note that my observed behaviour is consistent with https://en.wikipedia.org/wiki/IEEE_754: Overflow: a finite result is too large to be represented accurately (*i.e.*, its exponent with an unbounded exponent range would be larger than *emax*). By default, returns ±infinity for the round-to-nearest modes (and follows the rounding rules for the directed rounding modes). To reproduce: andrew@andrew-gs:~/Documents/100daysPython/misc$ cat o2.py import sys s="10e310" try: v=float( s ) except ValueError as e: print( f"Caught ValueError \"{e}\"" ) sys.exit(1) except: print( f"Caught unknown exception. Exiting." ) sys.exit(2) print( f"\nstring \"{s}\" becomes {v}\n" ) print( sys.float_info ) andrew@andrew-gs:~/Documents/100daysPython/misc$ python3 ./o2.py string "10e310" becomes inf sys.float_info(max=1.7976931348623157e+308, max_exp=1024, max_10_exp=308, min=2.2250738585072014e-308, min_exp=-1021, min_10_exp=-307, dig=15, mant_dig=53, epsilon=2.220446049250313e-16, radix=2, rounds=1) andrew@andrew-gs:~/Documents/100daysPython/misc$ Does this look like a doc bug, an implementation bug, or something else? Thanks for any information, Andrew

1 0

Suggestion: link from UserList docs to the collections classes list of methods
by Seebs 25 Jan '24

25 Jan '24

Hi! My exposure to Python is sporadic so I am functionally a complete newbie here, and maybe this is just really obvious to more experienced people, but I couldn't find a thing I wanted in the UserList documentation, and "an experienced programmer who doesn't know this language is confused by the documentation" feels like a thing potentially worth reporting. I started here: https://docs.python.org/3/library/collections.html#collections.UserList > In addition to supporting the methods and operations of mutable > sequences, UserList instances provide the following attribute: As a naive user, I don't know what are the "methods and operations of mutable sequences", or where to look for them. So when I was contemplating subclassing UserList and attempting to wrap its methods, I found that I did not know what those methods would be, or how to find those methods. A helpful user with more experience pointed me to: https://docs.python.org/3/library/collections.abc.html#collections-abstract… And from this I have concluded that, if I wanted to override behavior such that my wrapped list would intercept every list operation, I would need to define: __getitem__, __setitem__, __delitem__, __len__, insert And... I think that's it? I think if I understand correctly, the "mixin methods" such as __iadd__ would be defined in terms of these. I think. But I think it would be better if, as a naive user encountering the UserList documentation, I could figure this out without asking other people. Possible enhancements: 1. UserList actually provides the list directly inline. 2. The "methods and operations of mutable sequences" could be or also provide a link directly to that list of methods and operations. -s

3 2

Docs Accessibility Concerns
by Muskula Rahul 25 Jan '24

25 Jan '24

Subject: Request for Improved Accessibility in Python Documentation PDFs Dear Python Community Support Team, I hope this message finds you well. I appreciate the wealth of information in the Python documentation but have encountered challenges with the *PDF format. Specifically, the code sample readability is hindered, making it hard to highlight* and annotate effectively. *Please have a look at the picture attached , you will find the code sample hard to read.* To enhance accessibility, I suggest optimizing code sample color contrast. This improvement would benefit users across preferences and ensure a more user-friendly experience. [image: image.png] Thank you for considering these suggestions. I believe these adjustments will enhance the overall accessibility of the Python documentation. Best regards, Muskula Rahul.

2 1

Problems in Python tutorial
by Todd Hoatson 25 Jan '24

25 Jan '24

In 7.1. Fancier Output Formatting I read: > >>> '{:-9} YES votes {:2.2%}'.format(yes_votes, percentage) But the use of a negative number in the formatting string is not explained here, and the use of the decimal point is left to the reader to infer from the output. In 7.1.2. The String format() Method I read: > This is particularly useful in combination with the built-in function vars(), which returns a dictionary containing all local variables. > > As an example, the following lines produce a tidily aligned set of columns giving integers and their squares and cubes: But this is not an example of using the vars() function or even a dictionary. an example of the use of vars() is needed here. Todd Hoatson Mobile: 763-291-3312 Email: todd_hoatson(a)sil.org

2 1

About documentation
by Samyak Neupane 25 Jan '24

25 Jan '24

Hello sir/Mam, I am in beginning phase of learning Python language. And this is awesome. This is really simple and just so fantastic language for beginners to taste how a coding really looks like. As am in learning the beginner part in python I really wanna master on it . And I have found the documentation of it. But I am lost there looking those documentation. I really don't know which topic to look for and start with . I know we need to start from tutorial but the library and language reference, I just don't get it. If you could elaborate on it little bit,I would really appreciate it. Thank you for your time and consideration. Best regards, Samyak Neupane, Kathmandu Nepal

2 1

typo
by Роман Филимонов 25 Jan '24

25 Jan '24

slipped "s" at https://docs.python.org/3/library/dataclasses.html

2 1

How to Localize to Hindi
by Himanshu 25 Jan '24

25 Jan '24

Hi, Are there any efforts for localizing the docs to Hindi? I am looking to contribute. Thanks Himanshu github.com/himanshugarg -- +91 9650175105

2 1

Re: docs@python.org post "Documentation Python 3.10.13 unavailable"
by Zachary Ware 24 Jan '24

24 Jan '24

Hi Michael, I misclicked and accidentally rejected your post after it had sat in the moderation queue for two months; sorry about all of that! The original message: > By trying to download the documentation for Python 3.10.13, I am getting back the 404 error message. This has since been resolved; I suspect you were just trying before those docs were actually built. Regards, Zach

1 0

Getting tkinter...
by Steve Philcox 08 Jan '24

08 Jan '24

Hi, I'm at https://docs.python.org/3.8/library/tkinter.html#:~:text=Running%20python%2… . There's a helpful paragraph that explains how to check/confirm that tkinter is present. I clearly don't have it. My suggestion is to add something to guide the unfortunate to where/how to get it! I arrived at that page via google - 'python can't find tkinter' I'm running ubuntu and python3. My knowledge of managing python is limited but I have tried 'pip install tkinter' and that hasn't worked. It said success but python didn't find tkinter. I have since tried 'sudo apt install python3.8-tk' and that said: Note, selecting 'python3-tk' instead of 'python3.8-tk' So, I now have a working tkinter. You could make it a bit easier! Regards, Steve Philcox

2 1