docs February 2016

docs@python.org

27 participants
533 discussions

[issue18280] Documentation is too personalized

by Serhiy Storchaka

New submission from Serhiy Storchaka: Some documentation files contain a number of I/my/me. Looks like they grew from personal modules and personal articles. Perhaps the official documentation needs more depersonalized style. Here is full list of such files: Doc/c-api/exceptions.rst Doc/c-api/long.rst Doc/distutils/builtdist.rst Doc/extending/extending.rst Doc/extending/windows.rst Doc/howto/argparse.rst Doc/howto/curses.rst Doc/howto/functional.rst Doc/howto/regex.rst Doc/howto/sockets.rst Doc/howto/urllib2.rst Doc/install/index.rst Doc/library/audioop.rst Doc/library/ctypes.rst Doc/library/doctest.rst Doc/library/heapq.rst Doc/library/numbers.rst Doc/library/ossaudiodev.rst Doc/library/tk.rst Doc/library/unittest.mock-examples.rst Doc/library/unittest.mock.rst Doc/reference/introduction.rst Doc/tutorial/classes.rst The list doesn't include FAQs where it may be appropriate and whatsnew files. Andrew Kuchling recently has fixed Doc/howto/unicode.rst for this issue (as part of issue4153). ---------- assignee: docs@python components: Documentation messages: 191636 nosy: akuchling, docs@python, eric.araujo, ezio.melotti, georg.brandl, serhiy.storchaka priority: normal severity: normal status: open title: Documentation is too personalized versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18280> _______________________________________

1 week, 4 days

[issue23802] patch: __deepcopy__ memo dict argument usage

by Daniel Shahaf

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 weeks, 1 day

[issue26205] Inconsistency concerning nested scopes

by Roscoe R.Higgins

New submission from Roscoe R.Higgins: In chapter 9. Classes of the Python3.5 documentation it says: "At any time during execution, there are at least three nested scopes whose namespaces are directly accessible:", followed by a list containing 4 items. Further down a middle scope is mentioned (although mentioned by name). This was confusing for a while. ---------- assignee: docs@python components: Documentation messages: 258941 nosy: Roscoe R. Higgins, docs@python priority: normal severity: normal status: open title: Inconsistency concerning nested scopes type: behavior versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26205> _______________________________________

1 month

[issue17576] PyNumber_Index() is not int-subclass friendly

by Barry A. Warsaw

New submission from Barry A. Warsaw: operator.index() is just a thin wrapper around PyNumber_Index(). The documentation for operator.index() claims that it is equivalent to calling obj.__index__() but for subclasses of int, this is not true. In fact, PyNumber_Index() first does (e.g. in Python 3.3) a PyLong_Check() and if that succeeds, the original object is returned *without* doing the moral equivalent in C of calling obj.__index__(). An example: class myint(int): def __index__(self): return int(self) + 1 >>> x = myint(7) >>> x.__index__() 8 >>> from operator import index >>> index(x) 7 The C API documents PyNumber_Index() as: "Returns the o converted to a Python int on success or NULL with a TypeError exception raised on failure." Because this has been the behavior of PyNumber_Index() since at least 2.7 (I didn't check farther back), this probably cannot be classified as a bug deserving to be fixed in the code for older Pythons. It might be worth fixing for Python 3.4, i.e. by moving the index check before the type check. In the meantime, this is probably a documentation bug. The C API implies, but should be clearer that if o is an int subtype (int and long in Python 2), it is returned unchanged. The operator.index() documentation should be amended to describe this behavior for int/long subclasses. A different alternative would be to leave PyNumber_Index() unchanged, but with the doco fix, and to augment operator.index() to do the PyIndex_Check() first, before calling PyNumber_Index(). That's a little more redundant, but would provide the documented behavior without changing the C API. ---------- assignee: docs@python components: Documentation messages: 185522 nosy: barry, docs@python priority: normal severity: normal status: open title: PyNumber_Index() is not int-subclass friendly type: behavior versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17576> _______________________________________

1 month

[issue21333] Document recommended exception for objects that shouldn't be pickled

by Stefan Schwarzer

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> _______________________________________

1 month

[issue14189] Documentation for some C APIs is missing clear specification of the type of reference they return

by Baruch Sterin

New submission from Baruch Sterin <python(a)bsterin.com>: In addition to the description text, most C API functions have a one-line, emphasized specification whether they return a new or a borrowed reference. (e.g. 'Return value: New reference.'). The following API functions are missing that. Some of them, like PyMemoryView_FromBuffer(), have descriptions that are clear, but it would still be nice to have an unambiguous statement like most other API functions have. The list has been generated automatically, so it might contain some errors. Doc/c-api/arg.rst: Py_VaBuildValue Doc/c-api/buffer.rst: PyMemoryView_FromBuffer Doc/c-api/buffer.rst: PyMemoryView_FromObject Doc/c-api/buffer.rst: PyMemoryView_GetContiguous Doc/c-api/bytearray.rst: PyByteArray_Concat Doc/c-api/bytearray.rst: PyByteArray_FromObject Doc/c-api/bytearray.rst: PyByteArray_FromStringAndSize Doc/c-api/code.rst: PyCode_New Doc/c-api/codec.rst: PyCodec_BackslashReplaceErrors Doc/c-api/codec.rst: PyCodec_Decode Doc/c-api/codec.rst: PyCodec_Decoder Doc/c-api/codec.rst: PyCodec_Encode Doc/c-api/codec.rst: PyCodec_Encoder Doc/c-api/codec.rst: PyCodec_IgnoreErrors Doc/c-api/codec.rst: PyCodec_IncrementalDecoder Doc/c-api/codec.rst: PyCodec_IncrementalEncoder Doc/c-api/codec.rst: PyCodec_LookupError Doc/c-api/codec.rst: PyCodec_ReplaceErrors Doc/c-api/codec.rst: PyCodec_StreamReader Doc/c-api/codec.rst: PyCodec_StreamWriter Doc/c-api/codec.rst: PyCodec_StrictErrors Doc/c-api/codec.rst: PyCodec_XMLCharRefReplaceErrors Doc/c-api/exceptions.rst: PyUnicodeDecodeError_Create Doc/c-api/exceptions.rst: PyUnicodeDecodeError_GetEncoding Doc/c-api/exceptions.rst: PyUnicodeDecodeError_GetObject Doc/c-api/exceptions.rst: PyUnicodeDecodeError_GetReason Doc/c-api/exceptions.rst: PyUnicodeEncodeError_Create Doc/c-api/exceptions.rst: PyUnicodeTranslateError_Create Doc/c-api/float.rst: PyFloat_GetInfo Doc/c-api/import.rst: PyImport_GetImporter Doc/c-api/import.rst: PyImport_ImportModuleNoBlock Doc/c-api/import.rst: _PyImport_FindExtension Doc/c-api/import.rst: _PyImport_FixupExtension Doc/c-api/init.rst: PyEval_GetCallStats Doc/c-api/int.rst: PyInt_FromSize_t Doc/c-api/long.rst: PyLong_FromSize_t Doc/c-api/long.rst: PyLong_FromSsize_t Doc/c-api/number.rst: PyNumber_Index Doc/c-api/number.rst: PyNumber_ToBase Doc/c-api/object.rst: PyObject_Bytes Doc/c-api/object.rst: PyObject_GenericGetAttr Doc/c-api/unicode.rst: PyUnicode_AsUTF32String Doc/c-api/unicode.rst: PyUnicode_DecodeMBCSStateful Doc/c-api/unicode.rst: PyUnicode_DecodeUTF32 Doc/c-api/unicode.rst: PyUnicode_DecodeUTF32Stateful Doc/c-api/unicode.rst: PyUnicode_DecodeUTF7 Doc/c-api/unicode.rst: PyUnicode_DecodeUTF7Stateful Doc/c-api/unicode.rst: PyUnicode_EncodeUTF32 Doc/c-api/unicode.rst: PyUnicode_EncodeUTF7 Doc/c-api/veryhigh.rst: PyEval_EvalCodeEx Doc/c-api/veryhigh.rst: PyEval_EvalFrame Doc/c-api/veryhigh.rst: PyEval_EvalFrameEx ---------- assignee: docs@python components: Documentation messages: 154877 nosy: baruch.sterin, docs@python priority: normal severity: normal status: open title: Documentation for some C APIs is missing clear specification of the type of reference they return type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14189> _______________________________________

1 month

[issue17805] No such class: multiprocessing.pool.AsyncResult

by Takafumi Arakaki

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> _______________________________________

1 month

[issue23427] Python should expose command when invoked with -c

by Jan-Philip Gehrcke

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> _______________________________________

1 month, 1 week

[issue17589] Make documentation about macros in C API explicit about rvalue vs statement

by Larry Hastings

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> _______________________________________

1 month, 1 week

[issue21508] C API PyArg_ParseTuple doc is innacurate

by Steve

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> _______________________________________

1 month, 1 week

Jump to page:

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

docs February 2016