docs November 2015

docs@python.org

28 participants
531 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> _______________________________________

2 days, 11 hours

[issue25467] Put “deprecated” warnings first

by Tony R.

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

2 days, 11 hours

[issue12174] Multiprocessing logging levels unclear

by JJeffries

New submission from JJeffries <jamesjeffries1(a)gmail.com>: It is unclear without reference to the logging module where the multiprocessing logging levels fit in the normal logging provided by the logging module, even though it says above the table "The table below illustrates where theses fit in the normal level hierarchy. +----------------+----------------+ | Level | Numeric value | +================+================+ | ``SUBWARNING`` | 25 | +----------------+----------------+ | ``SUBDEBUG`` | 5 | +----------------+----------------+" I propose adding further values from the logging module for clarification. ---------- assignee: docs@python components: Documentation messages: 136839 nosy: JJeffries, docs@python priority: normal severity: normal status: open title: Multiprocessing logging levels unclear versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12174> _______________________________________

1 week, 1 day

[issue25509] PyImport_ImportModule inaccurately described

by Memeplex

New submission from Memeplex: The documentation (for 3.5) states that "[PyImport_ImportModule] is a simplified interface to PyImport_ImportModuleEx()" but the current implementation calls PyImport_Import instead, which is a higher level interface that takes into account import hooks. Older versions of PyImport_ImportModule (say 2.0) did call PyImport_ImportModuleEx, but that's no longer the case. The PyImport_Import* naming convention got a bit messy with the years and maybe I'm not understanding the intention quite well, but it seems to me that the documentation is outdated and that there is a change in semantics for PyImport_ImportModule. ---------- assignee: docs@python components: Documentation messages: 253674 nosy: docs@python, memeplex priority: normal severity: normal status: open title: PyImport_ImportModule inaccurately described versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25509> _______________________________________

1 week, 3 days

[issue19438] Where is NoneType in Python 3?

by mpb

New submission from mpb: types.NoneType seems to have disappeared in Python 3. This is probably intentional, but I cannot figure out how to test if a variable is of type NoneType in Python 3. Specifically, I want to write: assert type (v) in ( bytes, types.NoneType ) Yes, I could write: assert v is None or type (v) is bytes But the first assert statement is easier to read (IMO). Here are links to various Python 3 documentation about None: [1] http://docs.python.org/3/library/stdtypes.html#index-2 [2] http://docs.python.org/3/library/constants.html#None Link [2] says: "None The sole value of the type NoneType." However, NoneType is not listed in the Python 3 documentation index. (As compared with the Python 2 index, where NoneType is listed.) [3] http://docs.python.org/3/library/types.html If NoneType is gone in Python 3, mention of NoneType should probably be removed from link [2]. If NoneType is present in Python 3, the docs (presumably at least one of the above links, and hopefully also the index) should tell me how to use it. Here is another link: [4] http://docs.python.org/3/library/stdtypes.html#bltin-type-objects "The standard module types defines names for all standard built-in types." (Except <class 'NoneType'> ???) None is a built-in constant. It has a type. If None's type is not considered to be a "standard built-in type", then IMO this is surprising(!!) and should be documented somewhere (for example, at link [4], and possibly elsewhere as well.) Thanks! ---------- assignee: docs@python components: Documentation messages: 201666 nosy: docs@python, mpb priority: normal severity: normal status: open title: Where is NoneType in Python 3? versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19438> _______________________________________

1 week, 5 days

[issue13828] Further improve casefold documentation

by Jim Jewett

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

4 weeks

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

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

2 months, 2 weeks

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

2 months, 2 weeks

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

2 months, 2 weeks

Jump to page:

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

docs November 2015