Mailman 3 September 2020 - docs

[issue20692] Tutorial section 9.4
by Jon Shemitz 28 Apr '21

28 Apr '21

New submission from Jon Shemitz: The tutorial says "Each value is an object, and therefore has a class (also called its type). It is stored as object.__class__." So, I tried >>> 3.__class__ File "<stdin>", line 1 3.__class__ ^ SyntaxError: invalid syntax Yet, "foo".__class__ worked, as did 3j.__class__ and 3.5.__class__. When my son (!) suggested that I try (3).__class__, I did indeed get <type 'int'>, while (3,).__class__ gave <type 'tuple'>. This *looks like* a minor error in the parser, where seeing \d+\. puts it in a state where it expects \d+ and it can't handle \w+ This may be the sort of thing that only a newbie would even think to try, so may not be worth fixing. If so, it may be worth mentioning in the tutorial. ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 211670 nosy: Jon.Shemitz, docs@python priority: normal severity: normal status: open title: Tutorial section 9.4 type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20692> _______________________________________

10 18

[issue26629] Need an ability to build standard DLLs with distutils
by Buraddin Ibn-Karlo 27 Apr '21

27 Apr '21

New submission from Buraddin Ibn-Karlo: I want to make a a dynamic library to run its function with ctypes. Also I want to build the library from sources with distutils (the C++ sources are distributed with my Python code). But alas! Our distutils fails, if the library doesn't have initialization function (something like init_<module_name>). Even if the module does not need any initialization. I did a quick and dirty solution: added a dummy function: void init_<module_name>(){} It somehow works, but I don't think that it is a good idea. Cannot you add the possibility to tell distutils, that this extention module is just a simple DLL, that will be used via ctypes (or somehow else) and it does not need any extra init script? Also, cannot you add an extra section to ctypes documentation? With a description how to build such extensions via distutils? ---------- assignee: docs@python components: Build, Documentation, Extension Modules, Windows, ctypes messages: 262308 nosy: Buraddin Ibn-Karlo, docs@python, paul.moore, steve.dower, tim.golden, zach.ware priority: normal severity: normal status: open title: Need an ability to build standard DLLs with distutils type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26629> _______________________________________

3 3

[issue41661] os.path.relpath does not document ValueError on Windows with different drives
by Andy Maier 26 Apr '21

26 Apr '21

New submission from Andy Maier <andreas.r.maier(a)gmx.de>: I found that os.path.relpath() on Windows raises ValueError when the path and the start path are on different drives. This is to be expected, as there is no single root on Windows. On Python 3.7, the behavior is: >>> os.path.relpath('c:/abc', 'a:/') Traceback (most recent call last): File "<stdin>", line 1, in <module> File "...\Python\Python37\lib\ntpath.py", line 564, in relpath path_drive, start_drive)) ValueError: path is on mount 'c:', start on mount 'a:' The issue is that this ValueError and the reasons for it are not mentioned at all in the documentation for os.path.relpath(). Other os.path functions do document specific behaviors for different drives on Windows, for example os.path.commonpath(), so there is a precedence for documenting this. Also, it should be normal to document the possible exceptions that can be raised. I did read https://bugs.python.org/issue7195 from 2009 where the original issue discussed also lead to a request to update the documentation of os.path.relpath() to show the ValueError for this case, but that angle of the issue ended up being ignored back then, unfortunately. My suggestion is to add something like the following sentence the documentation: "On Windows, ValueError is raised when path and start are on different drives." ---------- assignee: docs@python components: Documentation messages: 376057 nosy: andymaier, docs@python priority: normal severity: normal status: open title: os.path.relpath does not document ValueError on Windows with different drives versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue41661> _______________________________________

7 9

[issue31055] All Sphinx generated pages could have a new "Edit This Page" link adjacent to the existing "Show Source"
by Paul Hammant 25 Apr '21

25 Apr '21

New submission from Paul Hammant: Show Source links to: https://github.com/python/cpython/blob/path/to/resource.rst Edit This Page would link to https://github.com/python/cpython/edit/path/to/resource.rst And yes, GitHub does the right thing if you're not ordinarily permitted to change python/cpython ---------- assignee: docs@python components: Documentation messages: 299306 nosy: Paul Hammant, docs@python priority: normal severity: normal status: open title: All Sphinx generated pages could have a new "Edit This Page" link adjacent to the existing "Show Source" versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue31055> _______________________________________

6 6

[issue27420] Docs for os.link - say what happens if link already exists
by Niall Mansfield 25 Apr '21

25 Apr '21

New submission from Niall Mansfield: In os.link(source, link_name) Change Create a hard link pointing to source named link_name. to Create a hard link pointing to source named link_name. If link_name already exists, OSError is raised. ---------- assignee: docs@python components: Documentation messages: 269572 nosy: docs@python, python-bugs-uit priority: normal severity: normal status: open title: Docs for os.link - say what happens if link already exists type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27420> _______________________________________

2 1

[issue35676] class TestCase: docs are not correct
by אורי רודברג 25 Apr '21

25 Apr '21

New submission from אורי רודברג <uri(a)speedy.net>: I think some functions of `class TestCase` are not documented correctly in the docs. For example in https://docs.python.org/3.5/library/unittest.html and also https://docs.python.org/3.6/library/unittest.html and https://docs.python.org/3.7/library/unittest.html. Some of the functions which are not documented correctly: assertListEqual assertSetEqual assertDictEqual assertIsNone And many other functions. You can see some more details on https://github.com/python/typeshed/issues/2716. ---------- assignee: docs@python components: Documentation messages: 333137 nosy: docs@python, אורי רודברג priority: normal severity: normal status: open title: class TestCase: docs are not correct versions: Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35676> _______________________________________

4 5

[issue16386] imp.find_module does not specify registry key it searches on windows
by Jan Duzinkiewicz 24 Apr '21

24 Apr '21

New submission from Jan Duzinkiewicz: quote from http://docs.python.org/3/library/imp.html#imp.find_module: "...on some systems some other places are looked in as well (on Windows, it looks in the registry which may point to a specific file)." I actually didn't know the registry key is listed in "using Python on Window" guide until I grepped for PythonCore (which kind of requires to know the key already) - so I'm submitting a patch that cross references find_module docs and using Python on Windows guide. ---------- assignee: docs@python components: Documentation files: import_nt_reg.patch keywords: patch messages: 174508 nosy: dhgmgn, docs@python priority: normal severity: normal status: open title: imp.find_module does not specify registry key it searches on windows versions: Python 2.7, Python 3.3 Added file: http://bugs.python.org/file27843/import_nt_reg.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16386> _______________________________________

4 5

[issue35114] ssl.RAND_status docs describe it as returning True/False; actually returns 1/0
by Josh Rosenberg 23 Apr '21

23 Apr '21

New submission from Josh Rosenberg <shadowranger+python(a)gmail.com>: The ssl.RAND_status online docs say (with code format on True/False): "Return True if the SSL pseudo-random number generator has been seeded with ‘enough’ randomness, and False otherwise." This is incorrect; the function actually returns 1 or 0 (and the docstring agrees). Fix can be one of: 1. Update docs to be less specific about the return type (use true/false, not True/False) 2. Update docs to match docstring (which specifically says 1/0, not True/False) 3. Update implementation and docstring to actually return True/False (replacing PyLong_FromLong with PyBool_FromLong and changing docstring to use True/False to match online docs) #3 involves a small amount of code churn, but it also means we're not needlessly replicating a C API's use of int return values when the function is logically bool (there is no error status for the C API AFAICT, so it's not like returning int gains us anything on flexibility). bool would be mathematically equivalent to the original 1/0 return value in the rare cases someone uses it mathematically. ---------- assignee: docs@python components: Documentation, SSL messages: 328917 nosy: docs@python, josh.r priority: low severity: normal status: open title: ssl.RAND_status docs describe it as returning True/False; actually returns 1/0 type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35114> _______________________________________

4 4

[issue11977] Document int.conjugate, .denominator, ...
by Jonas H. 23 Apr '21

23 Apr '21

New submission from Jonas H. <jonas(a)lophus.org>: Various `int` attributes and methods seem undocumented (at least it does not work to intersphinx them): * .conjugate * .denominator * .imag * .numerator * .real ---------- assignee: docs@python components: Documentation messages: 134926 nosy: docs@python, jonash priority: normal severity: normal status: open title: Document int.conjugate, .denominator, ... versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

6 8

[issue32133] documentation: numbers module nitpick
by abcdef 23 Apr '21

23 Apr '21

New submission from abcdef <x(a)mailinator.com>: Documentation of the numbers module: https://docs.python.org/3/library/numbers.html states "None of the types defined in this module can be instantiated." This is true for Complex, Real, Rational, Integral but not for Number: >>> numbers.Number() <numbers.Number object at 0x7fcccc71f3c0> >>> numbers.Real() Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: Can't instantiate abstract class Real... Since Number doesn't have any abstract methods, the correct fix seems to be changing the documentation. I would try to convey something like this: "The types defined in this module can be used for subclassing and checking whether a specific class is in the numeric hierarchy; they are not used directly for instantiation. For this, you can use types such as `complex` or `fractions.Fraction`". ---------- assignee: docs@python components: Documentation messages: 306970 nosy: abcdef, docs@python priority: normal severity: normal status: open title: documentation: numbers module nitpick type: enhancement versions: Python 2.7, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32133> _______________________________________

2 1