Thank you for the report! Your list of errata is now tracked here: https://github.com/python/cpython/issues/110383 On 22. 02. 23 12:01, Stephan Stiller wrote:
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 <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 <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 <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 <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 <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 <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 <https://docs.python.org/3/library/stdtypes.html#old-string-formatting>
7. https://docs.python.org/3/library/functions.html#open <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 <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 <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-... <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
_______________________________________________ docs mailing list -- docs@python.org To unsubscribe send an email to docs-leave@python.org https://mail.python.org/mailman3/lists/docs.python.org/ Member address: encukou@gmail.com