Mailman 3 April 2021 - 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

error in docs
by guyrenebongers71 04 Jun '21

04 Jun '21

Hello I start off this email with wishing everybody a good health. The documentation python tutorial release 3.6.10 has got an error. paragraph 2.1.1 Argument parsing it reads : when no script and no arguments are given, sys.argv[0] is an empty string. When the script name is given as '-' (meaning standard input), sys.argv[0] is set to '-'. When -c command is used, sys.argv[0] is set to '-c'. When -m module is used, sys.argv[0] is set to the full name of the located module. Options found after -c command or -m module are not consumed by the Python interpreter’s option processing but left in sys.argv for the command or module to handle. That should be sys.argv[1]. sys.argv[0] gives the full path of the interpreted used. An example: In [2]: print(sys.argv) ['/usr/bin/ipython3', '-c', 'print("data")', '-i'] I used python 3.8.5 ------------------------------------------------------ Sent with [ProtonMail](https://protonmail.com) Secure Email.

2 1

[issue43354] xmlrpc.client: Fault.faultCode erroneously documented to be a string, should be int
by Jürgen Gmach 05 May '21

05 May '21

New submission from Jürgen Gmach <juergen.gmach(a)googlemail.com>: I created a XMLRPC API (via Zope), which gets consumed by a C# application. C#'s XMLRPC lib expects an `int` for the `faultCode` but I currently return a string, as this is the type which is currently documented in the official docs https://docs.python.org/3/library/xmlrpc.client.html#xmlrpc.client.Fault.fa… This leads to a `TypeMismatch` error on the client's side. The documentation for `faultCode` is pretty much unchanged since 2007, when `xmlrpc.client.rst` was first created (at least at that place) by Georg Brandl. The docs are most probably older, but I do not know where they were managed before. I had a look at the cpython source code, and at least the tests all use ints for `faultCode` (both of them :-) ) eg https://github.com/python/cpython/blob/255f53bdb54a64b93035374ca4484ba0cc1b… Having a look at the XMLRPC spec at http://xmlrpc.com/spec.md it is clearly shown that `faultCode` has to be an int. Typeshed recently added type hints for xmlrpc lib, and they used string for `faultCode` - but I guess this is just an aftereffect from the faulty documentation. https://github.com/python/typeshed/pull/3834 I suggest to both update cpython's documentation and to create a PR for typeshed in order to fix the type issue. If any core dev agrees on this, I'd like to prepare the pull requests. Thanks for taking your time to look into this! ---------- assignee: docs@python components: Documentation messages: 387866 nosy: docs@python, jugmac00 priority: normal severity: normal status: open title: xmlrpc.client: Fault.faultCode erroneously documented to be a string, should be int versions: Python 3.10, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43354> _______________________________________

4 6

[issue43978] Incorrect "versionadded" info in typing.NoReturn documentation
by Mariatta 04 May '21

04 May '21

New submission from Mariatta <mariatta(a)python.org>: We received a documentation bug report in docs mailing list. https://mail.python.org/archives/list/docs@python.org/thread/BLANNZUPUEOJ4L… It looks like the doc currently says that, typing.NoReturn was added in both 3.5.4 and 3.6.2 It appeared from this change, that it was originally added in 3.6.5 (https://github.com/python/cpython/pull/7107/files) However, during a refactoring effort, in https://github.com/python/cpython/commit/ab72fdeb82c3ab045b480cd4bb4f928c12…, the 3.5.4 and 3.6.2 info were added, perhaps due to copy-pasting. I think it should be changed into .. versionadded:: 3.6.5 However, I'm curious to know whether there are other parts in the doc, where this info is wrong. So perhaps there was other parts of the doc that was added in 3.5.4, but somehow we moved that to the typing.NoReturn section. For now, I think we can just fix it by adding .. versionadded: 3.6.5 And maybe someone else can look into other parts of the doc to see if the version info are correct. ---------- assignee: docs@python components: Documentation keywords: easy, newcomer friendly messages: 392341 nosy: Mariatta, docs@python priority: normal severity: normal stage: needs patch status: open title: Incorrect "versionadded" info in typing.NoReturn documentation versions: Python 3.10, Python 3.11, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43978> _______________________________________

4 7

[issue43349] [doc] incorrect tuning(7) manpage link
by Erlend Egeberg Aasland 04 May '21

04 May '21

New submission from Erlend Egeberg Aasland <erlend.aasland(a)innova.no>: In https://docs.python.org/3.10/library/resource.html#resource.RLIMIT_SWAP, tuning(7) points to https://manpages.debian.org/tuning(7), however this is a FreeBSD only (?) system call, so the link is incorrect. I suggest linking to either: - https://docs.freebsd.org/en/books/handbook/config/ - https://www.freebsd.org/cgi/man.cgi?query=tuning&sektion=7&format=html ---------- assignee: docs@python components: Documentation messages: 387845 nosy: docs@python, erlendaasland priority: normal severity: normal status: open title: [doc] incorrect tuning(7) manpage link versions: Python 3.10, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43349> _______________________________________

4 8

[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

Error in documentation of "6.14 Evaluation order"
by Oliver Biwer 03 May '21

03 May '21

https://docs.python.org/3.8/reference/expressions.html#evaluation-order the example states "expressions will be evaluated in the arithmetic order of their suffixes" but for the line: `expr1(expr2, expr3, *expr4, **expr5)` this is not true - or at least misleading. this error goes way back until version 2.5: https://documentation.help/Python-2.5/evalorder.html were the outer 'expr1' was labeled 'func' the actual order should be (if I'm not totally mistaken): expr5(expr1, expr2, *expr3, **expr4) the simple program: def expr(*args, **kwargs): print(*args, *(zip(kwargs.keys(), kwargs.values()))) expr(expr("1"), expr("2"), expr("3"), d=expr("4")) returns: 1 2 3 4 None None None ('d', None)

2 1

[issue43990] In documentation Section 6.17, Operator precedence, footnotes 5 & 6 are reversed
by Webb Scales 03 May '21

03 May '21

New submission from Webb Scales <wscales(a)redhat.com>: In Section 6.17 ("Operator precedence"; https://docs.python.org/3/reference/expressions.html#operator-precedence) of the documentation, footnote 5 (https://docs.python.org/3/reference/expressions.html#id15) refers to text (https://docs.python.org/3/reference/expressions.html#id21) which applies to reference 6, while footnote 6 refers to text which applies to reference 5. ---------- assignee: docs@python components: Documentation messages: 392481 nosy: docs@python, webbnh priority: normal severity: normal status: open title: In documentation Section 6.17, Operator precedence, footnotes 5 & 6 are reversed versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43990> _______________________________________

4 7

[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