Mailman 3 April 2015 - docs

[issue12832] The documentation for the print function should explain/point to how to control the sys.stdout encoding
by R. David Murray 25 Oct '20

25 Oct '20

New submission from R. David Murray <rdmurray(a)bitdance.com>: A common problem encountered when using python3 is writing non-ascii to stdout. This will work fine if stdout is a terminal and the terminal encoding handles the characters, but will fail if stdout is later redirected to a pipe. The docs for sys.stdout and for print should contain or point to an explanation of why, and how to solve the problem (ie: how to set the encoding for sys.stdout/sys.stderr). Note that IMO it makes more sense for sys.stdout to default to the LOCALE encoding, but that should be a separate issue. ---------- assignee: docs@python components: Documentation messages: 142880 nosy: docs@python, r.david.murray priority: normal severity: normal status: open title: The documentation for the print function should explain/point to how to control the sys.stdout encoding versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12832> _______________________________________

4 7

[issue12174] Multiprocessing logging levels unclear
by JJeffries 22 Oct '20

22 Oct '20

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

8 15

[issue13047] imp.find_module("") and imp.find_module(".")
by Arfrever Frehtes Taifersar Arahesis 22 Oct '20

22 Oct '20

New submission from Arfrever Frehtes Taifersar Arahesis <Arfrever.FTA(a)GMail.Com>: It's undocumented that imp.find_module("") and imp.find_module(".") try to find __init__.py. There is also a small difference in behavior between them. sys.path by default contains "" as the first element, which is sufficient for imp.find_module("."), but not for imp.find_module(""): $ mkdir /tmp/imp_tests $ cd /tmp/imp_tests $ touch __init__.py $ python3.3 -c 'import imp, sys; print(repr(sys.path[0])); print(imp.find_module("."))' '' (None, '.', ('', '', 5)) $ python3.3 -c 'import imp, sys; print(repr(sys.path[0])); print(imp.find_module(""))' '' Traceback (most recent call last): File "<string>", line 1, in <module> ImportError: No module named '' If sys.path contains path (e.g. "." or absolute path) to directory with __init__.py file, then imp.find_module("") will succeed: $ PYTHONPATH="." python3.3 -c 'import imp, sys; print(repr(sys.path[0:2])); print(imp.find_module("."))' ['', '/tmp/imp_tests'] (None, '.', ('', '', 5)) $ PYTHONPATH="." python3.3 -c 'import imp, sys; print(repr(sys.path[0:2])); print(imp.find_module(""))' ['', '/tmp/imp_tests'] (None, '/tmp/imp_tests/', ('', '', 5)) $ python3.3 -c 'import imp, sys; sys.path.insert(1, "."); print(repr(sys.path[0:2])); print(imp.find_module("."))' ['', '.'] (None, '.', ('', '', 5)) $ python3.3 -c 'import imp, sys; sys.path.insert(1, "."); print(repr(sys.path[0:2])); print(imp.find_module(""))' ['', '.'] (None, './', ('', '', 5)) I think that imp.find_module(".") and imp.find_module("") should have the same behavior, and this behavior should be documented. ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 144531 nosy: Arfrever, docs@python priority: normal severity: normal status: open title: imp.find_module("") and imp.find_module(".") versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13047> _______________________________________

5 5

[issue14979] pdb: Link to source
by anatoly techtonik 22 Oct '20

22 Oct '20

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/library/pdb.html#pdb.Pdb Documentation for pdb says: "The debugger is extensible — it is actually defined as the class Pdb. This is currently undocumented but easily understood by reading the source." There should a link to the source. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 162074 nosy: docs@python, techtonik priority: normal severity: normal status: open title: pdb: Link to source _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14979> _______________________________________

4 5

[issue19438] Where is NoneType in Python 3?
by mpb 21 Oct '20

21 Oct '20

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

5 11

[issue23984] Documentation error: Descriptors
by bjonnh 08 Oct '20

08 Oct '20

New submission from bjonnh: in https://docs.python.org/3.5/howto/descriptor.html#static-methods-and-class-… (same problem in all python 3.x documentations) There is this example where the return of f function is printed and there is already a print in the function: """ >>> class E(object): def f(x): print(x) f = staticmethod(f) >>> print(E.f(3)) 3 >>> print(E().f(3)) 3 """ It should probably be: """ def f(x): return(x) """ or """ >> E.f(3) 3 >> E().f(3) """ ---------- assignee: docs@python components: Documentation messages: 241312 nosy: bjonnh, docs@python priority: normal severity: normal status: open title: Documentation error: Descriptors type: enhancement versions: Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23984> _______________________________________

8 13

[issue18280] Documentation is too personalized
by Serhiy Storchaka 19 Sep '20

19 Sep '20

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

11 17

[issue13828] Further improve casefold documentation
by Jim Jewett 24 Aug '20

24 Aug '20

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 18 Aug '20

18 Aug '20

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 05 Jul '20

05 Jul '20

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