Mailman 3 March 2021 - docs

[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

[issue43649] time.strftime('%z') doesn't return UTC offset in the form ±HHMM
by Patrick Storz 23 Apr '21

23 Apr '21

New submission from Patrick Storz <Eduard.Braun2(a)gmx.de>: This is a follow-up to https://bugs.python.org/issue20010 I'm seeing this very issue in a recent gcc build of Python 3.8 (mingw-w64-x86_64-python 3.8.8-2 from MSYS2 project): Python 3.8.8 (default, Feb 20 2021, 07:16:03) [GCC 10.2.0 64 bit (AMD64)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> import time >>> time.strftime('%z', time.localtime(time.time())) 'Mitteleuropäische Sommerzeit' >>> time.strftime('%Z', time.localtime(time.time())) 'Mitteleuropäische Sommerzeit' If this is indeed fixed in MSVCRT, it seems behavior is still not guaranteed when compiling with mingw-w64 gcc. ---------- components: Library (Lib), Windows messages: 389641 nosy: Aaron.Meurer, Ede123, Václav Dvořák, civalin, docs@python, eryksun, ezio.melotti, kepkin, martin-t, paul.moore, r.david.murray, steve.dower, tim.golden, vstinner, zach.ware priority: normal severity: normal status: open title: time.strftime('%z') doesn't return UTC offset in the form ±HHMM type: behavior versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43649> _______________________________________

3 3

[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

[issue43602] Include Decimal's in numbers.Real
by Sergey B Kirpichev 23 Apr '21

23 Apr '21

New submission from Sergey B Kirpichev <skirpichev(a)gmail.com>: Commit 82417ca9b2 includes Decimal's in the numbers tower, but only as an implementation of the abstract numbers.Number. The mentioned reason is "Decimals are not interoperable with floats" (see comments in the numbers.py as well), i.e. there is no lossless conversion (in general, in both directions). While this seems to be reasonable, there are arguments against: 1) The numbers module docs doesn't assert there should be a lossless conversion for implementations of same abstract type. (Perhaps, it should.) This obviously may be assumed for cases, where does exist an exact representation (integers, rationals and so on) - but not for real numbers (or complex), where representations are inexact (unless we consider some subsets of real numbers, e.g. some real finite extension of rationals - I doubt such class can represent numbers.Real). (Unfortunately, the Scheme distinction of exact/inexact was lost in PEP 3141.) 2) By same reason, I think, neither binary-based multiprecision arithmetics package can represent numbers.Real: i.e. gmpy2.mpfr, mpmath.mpf and so on. (In general, there is no lossless conversion float's, in both directions.) 3) That might confuse users (why 10-th base arbitrary precision floating point arithmetic can't represent real numbers?). 4) Last, but not least, even some parts of stdlib uses both types in an interoperable way, e.g. Fraction constructor: elif isinstance(numerator, (float, Decimal)): # Exact conversion self._numerator, self._denominator = numerator.as_integer_ratio() return self ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 389372 nosy: Sergey.Kirpichev, docs@python priority: normal severity: normal status: open title: Include Decimal's in numbers.Real versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43602> _______________________________________

4 13

[issue39572] [typing] TypedDict's 'total' argument is undocumented
by Brett Cannon 23 Apr '21

23 Apr '21

New submission from Brett Cannon <brett(a)python.org>: The docs mention __total__, but there's no mention of how to actually set that attribute, nor what it actually represents. P.S. https://github.com/python/cpython/blob/master/Lib/typing.py#L16 says TypedDict "may be added soon"; I think that's outdated. ;) ---------- assignee: docs@python components: Documentation messages: 361503 nosy: brett.cannon, docs@python, gvanrossum, levkivskyi priority: normal severity: normal stage: needs patch status: open title: [typing] TypedDict's 'total' argument is undocumented versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39572> _______________________________________

5 16

[issue21352] improve indexing
by bob gailer 22 Apr '21

22 Apr '21

New submission from bob gailer: Inconsistencies / confusion with documentation Index Tab. Example (line numbers added for comments that follow): 1 max 2 built-in function 3 max (datetime.date attribute) 4 (datetime.datetime attribute) 5 (datetime.time attribute) 6 max() built-in function 7 (decimal.Context method) 8 (decimal.Decimal method) 9 (in module audioloop) The following all lead to confusion and frustration: Having 3 rows (1, 3, 6)that begin with max. Having an entry (1) that does nothing when double-clicked. double-clicking (2) takes us to a reference rather than a definition. RECOMMENDATION: change to: max() built-in function (sequence operation) (decimal.Context method) (decimal.Decimal method) max (datetime.date attribute) (datetime.datetime attribute) (datetime.time attribute) where double-clicking the first line goes to the max() definition in 2. Built-in Functions These comments apply, with a number of variations, to most built-in functions index entries. ---------- assignee: docs@python components: Documentation messages: 217170 nosy: bgailer, docs@python priority: normal severity: normal status: open title: improve indexing type: enhancement versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21352> _______________________________________

7 6

[issue19023] ctypes docs: Unimplemented and undocumented features
by Sye van der Veen 20 Apr '21

20 Apr '21

New submission from Sye van der Veen: In the ctypes documentation, there's mention of a BigEndianUnion/LittleEndianUnion that isn't actually implemented, and the "Arrays and pointers" section just reads "Not yet written". The attached patch adds the (Big|Little)EndianUnion classes (with tests), finishes the Array/_Pointer class docs (and adds missing cases to the tests), and makes some stylistic improvements to docs. The patch was made against default, but it's quite likely it could be back-ported all the way to Python 3.1. ---------- assignee: docs@python components: Documentation, Tests, ctypes hgrepos: 209 messages: 197764 nosy: docs@python, syeberman priority: normal severity: normal status: open title: ctypes docs: Unimplemented and undocumented features type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19023> _______________________________________

8 15

[issue43641] Update `ssl.PROTOCOL_TLSv1_2` docs since it is not the newest TLS version
by Illia Volochii 18 Apr '21

18 Apr '21

New submission from Illia Volochii <illia.volochii(a)gmail.com>: Docs say that TLS 1.2 is the most modern version, and probably the best choice for maximum protection, but TLS 1.3 exists. https://docs.python.org/3.10/library/ssl.html#ssl.PROTOCOL_TLSv1_2 ---------- assignee: docs@python components: Documentation messages: 389608 nosy: docs@python, illia-v priority: normal severity: normal status: open title: Update `ssl.PROTOCOL_TLSv1_2` docs since it is not the newest TLS version type: enhancement versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43641> _______________________________________

3 3