Mailman 3 July 2016 - docs

[issue25467] Put “deprecated” warnings first
by Tony R. Sept. 19, 2020

Sept. 19, 2020

New submission from Tony R.: Python has wonderful, detailed documentation. I love it! Unfortunately, I have often found myself reading the otherwise-excellent documentation on a class/function/whatever, only to find out at the END of my reading that it is deprecated. This is frustrating, and counter-intuitive. If something is deprecated, I want to know it before I read any further. I have attached a patch with the relevant changes. I hope it helps! ---------- assignee: docs@python components: Documentation files: 0001-Move-deprecated-blocks-to-the-beginning-of-their-doc.patch keywords: patch messages: 253391 nosy: Tony R., docs@python priority: normal severity: normal status: open title: Put “deprecated” warnings first type: enhancement Added file: http://bugs.python.org/file40851/0001-Move-deprecated-blocks-to-the-beginni… _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25467> _______________________________________

5 13

[issue25912] Use __spec__.__name__ instead of __name__ in the docs where appropriate
by Antony Lee Sept. 11, 2020

Sept. 11, 2020

New submission from Antony Lee: There are a couple of places in the docs where it would be appropriate to replace __name__ by __spec__.__name__ in order to support the case where the module is executed as the __main__ module: - logging.getLogger should certainly use __spec__.__name__ so that the logger hierarchy be respected (otherwise, when running "python -mpkg.subpkg", the logger of pkg.subpkg is named "__main__" and thus not a child of the "pkg" logger). - examples for argparse.ArgumentParser (e.g. in the docs for venv) should use __spec__.__name__ instead of __name__ for the "prog=" argument. (not guaranteed to be exhaustive) ---------- assignee: docs@python components: Documentation messages: 256743 nosy: Antony.Lee, docs@python priority: normal severity: normal status: open title: Use __spec__.__name__ instead of __name__ in the docs where appropriate versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25912> _______________________________________

2 3

[issue13828] Further improve casefold documentation
by Jim Jewett Aug. 24, 2020

Aug. 24, 2020

New submission from Jim Jewett <jimjjewett(a)gmail.com>: > http://hg.python.org/cpython/rev/0b5ce36a7a24 > changeset: 74515:0b5ce36a7a24 > + Casefolding is similar to lowercasing but more aggressive because it is > + intended to remove all case distinctions in a string. For example, the German > + lowercase letter ``'ß'`` is equivalent to ``"ss"``. Since it is already > + lowercase, :meth:`lower` would do nothing to ``'ß'``; :meth:`casefold` > + converts it to ``"ss"``. Perhaps add the recommendation to canonicalize as well. A complete, but possibly too long, try is below: Casefolding is similar to lowercasing but more aggressive because it is intended to remove all case distinctions in a string. For example, the German lowercase letter ``'ß'`` is equivalent to ``"ss"``. Since it is already lowercase, :meth:`lower` would do nothing to ``'ß'``; :meth:`casefold` converts it to ``"ss"``. Note that most case-insensitive matches should also match compatibility equivalent characters. The casefolding algorithm is described in section 3.13 of the Unicode Standard. Per D146, a compatibility caseless match can be achieved by from unicodedata import normalize def caseless_compat(string): nfd_string = normalize("NFD", string) nfkd1_string = normalize("NFKD", nfd_string.casefold()) return normalize("NFKD", nfkd1_string.casefold()) ---------- assignee: docs@python components: Documentation messages: 151644 nosy: Jim.Jewett, benjamin.peterson, docs@python priority: normal severity: normal status: open title: Further improve casefold documentation versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13828> _______________________________________

7 10

[issue23802] patch: __deepcopy__ memo dict argument usage
by Daniel Shahaf Aug. 18, 2020

Aug. 18, 2020

New submission from Daniel Shahaf: In the 'copy' module documentation, it wasn't fully clear to me how __deepcopy__ implementations should treat the memo dict argument. The attached patch clarifies that __deepcopy__ implementations should treat the memo dict argument as an opaque type. ---------- assignee: docs@python components: Documentation files: opaque.diff keywords: patch messages: 239473 nosy: danielsh, docs@python priority: normal severity: normal status: open title: patch: __deepcopy__ memo dict argument usage type: enhancement Added file: http://bugs.python.org/file38723/opaque.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23802> _______________________________________

4 6

[issue21333] Document recommended exception for objects that shouldn't be pickled
by Stefan Schwarzer July 5, 2020

July 5, 2020

New submission from Stefan Schwarzer: I recently was confused whether to raise a `PicklingError` or `TypeError` in `__getstate__` if objects of my class can't and shouldn't be pickled. [1] Terry Reedy advised I should use `TypeError`. [2] I wonder if the `pickle` module documention should explicitly recommend using `TypeError` if a class wants to say that its objects can't be pickled. What do you think? [1] https://mail.python.org/pipermail/python-list/2014-April/670987.html [2] https://mail.python.org/pipermail/python-list/2014-April/671002.html ---------- assignee: docs@python components: Documentation messages: 217054 nosy: docs@python, sschwarzer priority: normal severity: normal status: open title: Document recommended exception for objects that shouldn't be pickled type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21333> _______________________________________

5 4

[issue17805] No such class: multiprocessing.pool.AsyncResult
by Takafumi Arakaki July 3, 2020

July 3, 2020

New submission from Takafumi Arakaki: Document mentions AsyncResult but there is no such class. http://docs.python.org/2/library/multiprocessing.html#multiprocessing.pool.… You can check it by simply running: python -c 'from multiprocessing.pool import AsyncResult' I think it means ApplyResult so I made a patch (attached). Note that there managers.py also uses name 'AsyncResult': % hg grep AsyncResult Doc/library/multiprocessing.rst:83232:.. class:: AsyncResult Lib/multiprocessing/managers.py:81039: 'apply_async': 'AsyncResult', Lib/multiprocessing/managers.py:81039: 'map_async': 'AsyncResult', Lib/multiprocessing/managers.py:81039: 'starmap_async': 'AsyncResult', Lib/multiprocessing/managers.py:81039:SyncManager.register('AsyncResult', create_method=False) Probably renaming them would be better? ---------- assignee: docs@python components: Documentation files: ApplyResult.patch keywords: patch messages: 187466 nosy: docs@python, tkf priority: normal severity: normal status: open title: No such class: multiprocessing.pool.AsyncResult versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 Added file: http://bugs.python.org/file29954/ApplyResult.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17805> _______________________________________

6 8

[issue23427] Python should expose command when invoked with -c
by Jan-Philip Gehrcke June 29, 2020

June 29, 2020

New submission from Jan-Philip Gehrcke: When Python is invoked with the `-c command` switch, the command string does not get exposed in sys.argv: $ python -c "import sys; print(sys.argv)" ['-c'] $ python -c "import sys; print(sys.argv)" arg1 ['-c', 'arg1'] The command string does not get exposed anywhere, AFAIK, so it is inaccessible from within Python programs. There might be application scenarios in which it is useful to access the command string, such as for debugging purposes. One scenario is when a Python session should be able to "re-spawn" itself in a subprocess (I came across this question on StackOverflow: http://stackoverflow.com/q/28412903/145400) I propose to make the command string accessible. If you agree that it might make sense, the question is *how/where* to expose it. One possible way is to retain it in sys.argv, as in this example: $ python -c "import sys; print(sys.argv)" "arg1" ['-c', 'import sys; print(sys.argv)', 'arg1'] The current sys.argv docs say > If the command was executed using the -c command line option to > the interpreter, argv[0] is set to the string '-c'. This sentence could then be adjusted to "[...], argv[0] is set to the string '-c', and argv[1] contains the command." This method breaks existing applications that are started with the -c method and that consume command line arguments in a sys.argv[1:] fashion. The tests in Lib/test/test_cmd_line.py all pass, however. A second method would be to change sys.argv[0] from '-c' to '-c command'. This would break existing applications that check for sys.argv[0] == 'c'. A third method would be to leave sys.argv as it is, and expose the command with a new attribute in the sys module. I have attached a patch for variant 1 (passes all tests in Lib/test/test_cmd_line.py), to demonstrate which code is affected: the translation from the "real" argv to sys' argv is triggered in Modules/main.c. The patch does not change behavior of '-m' (it's funny, however, that the current version of main.c at first replaces the module string with '-m', whereas the runpy module later on replaces '-m' with the path to the module file anyway.). As a side node, I figure that the sys.argv documentation should be adjusted to properly reflect the -m behavior, which is: $ ./python -m testmodule foo testmodule sys.argv: ['/data/local/pythondev/pythontip/cpython/testmodule.py', 'foo'] Let me hear your comments, and I am willing to work on code and doc patches, thanks! ---------- assignee: docs@python components: Documentation, Interpreter Core files: sys_argv_cmd.patch keywords: patch messages: 235633 nosy: docs@python, georg.brandl, haypo, jgehrcke, pitrou priority: normal severity: normal status: open title: Python should expose command when invoked with -c type: enhancement versions: Python 3.5, Python 3.6 Added file: http://bugs.python.org/file38065/sys_argv_cmd.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23427> _______________________________________

7 20

[issue17589] Make documentation about macros in C API explicit about rvalue vs statement
by Larry Hastings June 25, 2020

June 25, 2020

New submission from Larry Hastings: CPython API "functions" implemented as macros can expand into either rvalues or statements. Most expand into statements (often using the do {} while (0) syntactic sugar trick), but occasionally they're legal as rvalues. As of this writing Py_INCREF works as an rvalue. But discussion on another tracker issue (#17206) proposes changing the implementation in such a way that it will only be usable as a statement. Although it's mildly unlikely, it's certainly possible that this will break somebody's code. I propose that the documentation make an explicit ruling on whether macros are usable as rvalues or as statements. Perhaps a blanket statement would suffice, "all macros are only supported for use as statements except where explicitly noted", then annotate specific macros that are supported for use as rvalues. Though that raises the question of acknowledging in the documentation that some things are macros--I think the documentation glosses over that fact right now. Note: I added you three (Georg, Mark, Martin) as I thought you might have an opinion on this one way or the other. If you're not interested, my apologies. ---------- assignee: docs@python components: Documentation messages: 185646 nosy: Mark.Shannon, docs@python, georg.brandl, larry, loewis priority: normal severity: normal stage: needs patch status: open title: Make documentation about macros in C API explicit about rvalue vs statement type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17589> _______________________________________

7 9

[issue21508] C API PyArg_ParseTuple doc is innacurate
by Steve June 25, 2020

June 25, 2020

New submission from Steve: PyArg_ParseTuple is defined as returning an "int", but the documentation talks about returning a true/false value, and failling on false. In addition to being inaccurate, considering that most other functions fail on !=0 ("true"), it can lead to confusion. Doc: int PyArg_ParseTuple(PyObject *args, const char *format, ...) Parse the parameters of a function that takes only positional parameters into local variables. Returns true on success; on failure, it returns false and raises the appropriate exception. ---------- assignee: docs@python components: Documentation messages: 218536 nosy: Banger, docs@python priority: normal severity: normal status: open title: C API PyArg_ParseTuple doc is innacurate type: enhancement versions: Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21508> _______________________________________

3 4

[issue20224] C API docs need a clear "defining custom extension types" section
by Nick Coghlan June 25, 2020

June 25, 2020

New submission from Nick Coghlan: The main C API docs don't clearly explain how to define new types, so people almost always cargo cult an existing legacy type definition instead (I know I do). The extending and embedding docs have a guide (http://docs.python.org/3/extending/newtypes.html), but that describes the old legacy method based on static type declarations. New code should instead use the dynamic mechanism defined in PEP 384 (http://www.python.org/dev/peps/pep-0384/#type-objects). See also http://docs.python.org/3/c-api/type.html#PyType_FromSpec Note that PyType_Spec isn't defined in the C API docs *at all*. ---------- assignee: docs@python components: Documentation messages: 207927 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: C API docs need a clear "defining custom extension types" section type: enhancement versions: Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20224> _______________________________________

2 1