Mailman 3 March 2019 - docs

[issue35880] math.sin has no backward error; this isn't documented
by Jurjen N.E. Bos March 8, 2019

March 8, 2019

New submission from Jurjen N.E. Bos <jneb(a)users.sourceforge.net>: The documentation of math.sin (and related trig functions) doesn't speak about backward error. In cPython, as far as I can see, there is no backward error at all, which is quite uncommon. This may vary between implementations; many math libraries of other languages have a backward error, resulting in large errors for large arguments. e.g. sin(1<<500) is correctly computed as 0.42925739234242827, where a backward error as small as 1e-150 can give a completely wrong result. Some text could be added (which I am happy to produce) that explains what backward error means, and under which circumstances you can expect an accurate result. ---------- assignee: docs@python components: Documentation messages: 334672 nosy: docs@python, jneb priority: normal severity: normal status: open title: math.sin has no backward error; this isn't documented versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35880> _______________________________________

5 7

[issue36203] PyWeakref_NewRef docs are misleading
by Roundup Robot March 8, 2019

March 8, 2019

Change by Roundup Robot <devnull(a)psf.upfronthosting.co.za>: ---------- keywords: +patch pull_requests: +12232 stage: -> patch review _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36203> _______________________________________

1 0

[issue35843] importlib.util docs for namespace packages innaccurate
by Anthony Sottile March 8, 2019

March 8, 2019

New submission from Anthony Sottile <asottile(a)umich.edu>: For instance: # `a` is an empty directory, a PEP 420 namespace package >>> import importlib.util >>> importlib.util.find_spec('a') ModuleSpec(name='a', loader=None, origin='namespace', submodule_search_locations=_NamespacePath(['/tmp/x/a'])) https://docs.python.org/3/library/importlib.html#importlib.machinery.Module… > ... Normally “origin” should be set, but it may be None (the default) which indicates it is unspecified (e.g. for namespace packages). above the `origin` is `'namespace'` https://docs.python.org/3/library/importlib.html#importlib.machinery.Module… > List of strings for where to find submodules, if a package (None otherwise). However the `_NamespacePath` object above is not indexable: >>> x = importlib.util.find_spec('a').submodule_search_locations >>> x[0] Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: '_NamespacePath' object does not support indexing I can work around however with: >>> next(iter(x)) '/tmp/x/a' ====================== so I guess a few things can/should come out of this: - Document the `'namespace'` origin - Document that `submodule_search_paths` is a Sized[str] instead - Add `__getitem__` to `_NamespacePath` such that it implements the full `Sized` protocol ---------- assignee: docs@python components: Documentation messages: 334484 nosy: Anthony Sottile, docs@python priority: normal severity: normal status: open title: importlib.util docs for namespace packages innaccurate versions: Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35843> _______________________________________

6 11

[issue35435] Documentation of 3.3 is available
by Stéphane Wirtel March 8, 2019

March 8, 2019

New submission from Stéphane Wirtel <stephane(a)wirtel.be>: Today, I was looking for the doc of unittest.mock and the result from DuckDuckGo was this link: https://docs.python.org/3.3/library/unittest.mock-examples.html In the devguide, we stopped the support and everything about this version, in the bug tracker, 3.3 is not available. Maybe we could remove the doc from the server. ---------- assignee: docs@python components: Documentation messages: 331271 nosy: docs@python, matrixise, mdk priority: normal severity: normal status: open title: Documentation of 3.3 is available _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35435> _______________________________________

6 9

[issue36237] data_files / Install Additional Files written unclearly such that it's not obvious what parameter is what
by jt March 8, 2019

March 8, 2019

New submission from jt <jonas(a)thiem.email>: I find the following doc section found at https://docs.python.org/3.7/distutils/setupscript.html#installing-additiona… about data_files somewhat unclear: ``` setup(..., data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), ('config', ['cfg/data.cfg']), ('/etc/init.d', ['init-script'])] ) Each (directory, files) pair in the sequence specifies the installation directory and the files to install there. ... The directory should be a relative path. It is interpreted relative to the installation prefix (Python’s sys.prefix for system installations; site.USER_BASE for user installations). ``` This gives me no clue what the installation actually is relative to, since e.g. sys.prefix is just `/usr` - surely I'm not supposed to specify "lib64/python3.7/site-packages/<mypackage-name>/file" as a target? That is probably not how that text is supposed to be read and I'm sure packaging expert understand what sort of prefix is actually meant, but could this be more elaborated on, maybe an actual example for a fake package of whether this is e.g. the package folder root after the install inside the site packages, or the site packages folder itself, or ...? ---------- assignee: docs@python components: Documentation messages: 337471 nosy: docs@python, jt priority: normal severity: normal status: open title: data_files / Install Additional Files written unclearly such that it's not obvious what parameter is what versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36237> _______________________________________

1 1

[issue30831] Inconsistent or wrong documentation around Asynchronous Context Manager
by Daisuke Miyakawa March 7, 2019

March 7, 2019

New submission from Daisuke Miyakawa: I was reading the following doc and got confused. https://docs.python.org/3.7/reference/datamodel.html#object.__aenter__ According to the API doc itself (and original PEP 492), __aenter__() "is semantically similar to the __enter__(), with only difference that it must return an awaitable." __aexit__() has similar sentence that confuses me too. PEP 492 also implies the (awaitable) object returned from obj.__aenter__() will be awaited immediately. In same manner, the (awaitable) object returned from obj.__aexit__() will be awaited too. (From PEP 492) > async with EXPR as VAR: > BLOCK > > which is semantically equivalent to: > > mgr = (EXPR) > aexit = type(mgr).__aexit__ > aenter = type(mgr).__aenter__(mgr) > exc = True > > VAR = await aenter > try: > BLOCK > except: > if not await aexit(mgr, *sys.exc_info()): > raise > else: > await aexit(mgr, None, None, None) On the other hand, actual CPython implementation won't do that; it won't await the returned objects. Moreover, the example shown in the API doc (AsyncContextManager) does NOT return awaitable as the doc itself suggests, but just await inside __aenter__() (and __aexit__()). > class AsyncContextManager: > async def __aenter__(self): > await log('entering context') > > async def __aexit__(self, exc_type, exc, tb): > await log('exiting context') I'm not sure which is true; the doc saying "__aenter__() must return awaitable" is just incorrect, or CPython implementation has a bug. Actual source implies former. _ContextManagerMixin in asyncio.locks does not return awaitable at all, for example. Anyway, I believe there are inconsistencies around here. ---------- assignee: docs@python components: Documentation messages: 297542 nosy: dmiyakawa, docs@python priority: normal severity: normal status: open title: Inconsistent or wrong documentation around Asynchronous Context Manager versions: Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30831> _______________________________________

3 3

[issue36203] PyWeakref_NewRef docs are misleading
by Windson Yang March 7, 2019

March 7, 2019

Windson Yang <wiwindson(a)outlook.com> added the comment: It looks to me the fix is easy, we just will return NULL and raise TypeError when the callback is not callable, None, or NULL. I'm not an expert in C, but I would love to create a PR for it if you don't have time. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36203> _______________________________________

2 1

[issue36185] [EASY DOC] typo: Doc/c-api/objbuffer.rst: There is a typo in "corresponding"
by STINNER Victor March 6, 2019

March 6, 2019

New submission from STINNER Victor <vstinner(a)redhat.com>: Issue reported at: https://github.com/python/cpython/pull/11119/files/650ed79e9dcd6f12b2cd0adc… > There is a typo in "corresponding" Does someone want to write a PR? ---------- assignee: docs@python components: Documentation keywords: easy messages: 337122 nosy: docs@python, vstinner priority: normal severity: normal status: open title: [EASY DOC] typo: Doc/c-api/objbuffer.rst: There is a typo in "corresponding" versions: Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36185> _______________________________________

5 6

[issue36203] PyWeakref_NewRef docs are misleading
by Windson Yang March 6, 2019

March 6, 2019

Windson Yang <wiwindson(a)outlook.com> added the comment: Yes, Maxwell. I guess the docs are misleading, the code locate in https://github.com/python/cpython/blob/master/Objects/weakrefobject.c#L748 if (callback == Py_None) callback = NULL; if (callback == NULL) /* return existing weak reference if it exists */ result = ref; if (result != NULL) Py_INCREF(result); else { ... } However, I'm not sure we should fix the docs or the code here. ---------- nosy: +Windson Yang _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36203> _______________________________________

2 1

[issue36209] [EASY Doc] Typo in hashlib error message
by STINNER Victor March 6, 2019

March 6, 2019

New submission from STINNER Victor <vstinner(a)redhat.com>: Seen on a custom builder: BUILDSTDERR: ====================================================================== BUILDSTDERR: ERROR: test_scrypt (test.test_hashlib.KDFTests) BUILDSTDERR: ---------------------------------------------------------------------- BUILDSTDERR: Traceback (most recent call last): BUILDSTDERR: File "/builddir/build/BUILD/Python-3.7.2/Lib/test/test_hashlib.py", line 942, in test_scrypt BUILDSTDERR: result = hashlib.scrypt(password, salt=salt, n=n, r=r, p=p) BUILDSTDERR: ValueError: Invalid paramemter combination for n, r, p, maxmem. There is a typo in "paramemter". ---------- assignee: docs@python components: Documentation keywords: easy messages: 337290 nosy: docs@python, vstinner priority: normal severity: normal status: open title: [EASY Doc] Typo in hashlib error message versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36209> _______________________________________

4 7