Mailman 3 February 2017 - docs

[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

[issue27635] pickle documentation says that unpickling may not call __new__
by July Tikhonov 11 Oct '20

11 Oct '20

New submission from July Tikhonov: A note just below object.__setstate__() documentation https://docs.python.org/3.6/library/pickle.html#object.__setstate__ says that """ … the type should implement __getnewargs__() or __getnewargs_ex__() to establish such an invariant; otherwise, neither __new__() nor __init__() will be called. """ I believe that note about not calling __new__() was relevant in python2. I could not find case in python3 in which __new__() would not be called. And __init__() is not called anyway, as far as I understand (unless explicitly by __setstate__() or something). Python 3.6.0a3+ (default:da9898e7e90d, Jul 27 2016, 19:51:12) [GCC 4.9.3] on linux Type "help", "copyright", "credits" or "license" for more information. >>> class C: ... def __getstate__(self): return {'foo' : self.foo} ... def __setstate__(self, state): self.foo = state['foo'] ... def __new__(cls): ... print('__new__ is called'); return super().__new__(cls) ... def __init__(self): ... print('__init__ is called'); self.foo = None; super().__init__() ... >>> c = C(); c.foo = 'bar' __new__ is called __init__ is called >>> import pickle >>> c2 = pickle.loads(pickle.dumps(c)) __new__ is called >>> c2.foo 'bar' ---------- assignee: docs@python components: Documentation messages: 271465 nosy: docs@python, july priority: normal severity: normal status: open title: pickle documentation says that unpickling may not call __new__ versions: Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27635> _______________________________________

6 11

[issue26964] Incorrect documentation for `-u`-flag
by Olav Morken 11 Oct '20

11 Oct '20

New submission from Olav Morken: The documentation for the `-u`-flag (https://docs.python.org/3/using/cmdline.html#cmdoption-u) contains: > The text I/O layer will still be line-buffered if writing to the console, or block-buffered if redirected to a non-interactive file. This does not appear to be the case -- instead it is always line-buffered: https://hg.python.org/cpython/file/v3.5.1/Python/pylifecycle.c#l1041 Attached is a trivial patch that simply removes everything after "line-buffered". ---------- assignee: docs@python components: Documentation files: fix-doc-unbuffered.patch keywords: patch messages: 264910 nosy: docs@python, olavmrk priority: normal severity: normal status: open title: Incorrect documentation for `-u`-flag Added file: http://bugs.python.org/file42736/fix-doc-unbuffered.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26964> _______________________________________

4 3

[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

[issue29127] Incorrect reference names in asyncio.subprocess documentation
by Eric Ahn 02 Oct '20

02 Oct '20

New submission from Eric Ahn: On this page of the documentation https://docs.python.org/3/library/asyncio-subprocess.html it seems that some of the reference names are incorrect. Namely, asyncio.subprocess.PIPE is referred to as asyncio.asyncio.subprocess.PIPE (along with STDOUT and DEVNULL), plus asyncio.subprocess.Process is referred to as asyncio.asyncio.subprocess.Process. This is reflected in the permalinks as well as when one tries to reference these via intersphinx (which is how I discovered it; I was trying to link to this page and was failing). ---------- assignee: docs@python components: Documentation messages: 284418 nosy: Eric Ahn, docs@python priority: normal severity: normal status: open title: Incorrect reference names in asyncio.subprocess documentation versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29127> _______________________________________

3 2

[issue24757] Installing Py on Windows: Need to restart or logout for path to be added
by John Palermo 24 Sep '20

24 Sep '20

New submission from John Palermo: Something I suppose many new users could stumble over: After installing Python and trying out "pip" or "python" on the command line nothing is found. You have to re-start Windows or re-log into your account. I suggest adding this information to the documentation here https://docs.python.org/2/using/windows.html#installing-python and also adding it to the Windows installer description for the "add Python to your path" option. ---------- assignee: docs@python components: Documentation messages: 247688 nosy: John Palermo, docs@python priority: normal severity: normal status: open title: Installing Py on Windows: Need to restart or logout for path to be added type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24757> _______________________________________

6 6

[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

[issue25467] Put “deprecated” warnings first
by Tony R. 19 Sep '20

19 Sep '20

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

[issue28499] Logging module documentation needs a rework.
by Pierre Bousquie 13 Sep '20

13 Sep '20

New submission from Pierre Bousquie: At pyconf-fr 2016 Florian Strzelecki (@Exirel) made a great talk on how to make good documentation. At one time he asked "python logging doc?, did you realy found it clear and helpfull?" clear answer from the crowd: not at all. Stephane Wirtel ask us (the unhappy folks) : Hey send a bug request, then the pull request and... i'll be there to help :). So i'm here for first step: fill the bug issue. I'm willing to fix this doc! ---------- assignee: docs@python components: Documentation messages: 279141 nosy: Pierre Bousquie, docs@python priority: normal severity: normal status: open title: Logging module documentation needs a rework. type: enhancement versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28499> _______________________________________

5 10

[issue25912] Use __spec__.__name__ instead of __name__ in the docs where appropriate
by Antony Lee 11 Sep '20

11 Sep '20

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