Mailman 3 June 2018 - docs

[issue30052] URL Quoting page links to function Bytes instead of defintion
by Cheryl Sabella June 21, 2019

June 21, 2019

New submission from Cheryl Sabella: On the URL Quoting page, the following line: `string may be either a str or a bytes.` Has the `str` link to: https://docs.python.org/3/library/stdtypes.html#str But the `bytes` link to: https://docs.python.org/3/library/functions.html#bytes Should the `bytes` link to? https://docs.python.org/3/library/stdtypes.html#bytes ---------- assignee: docs@python components: Documentation messages: 291546 nosy: csabella, docs@python priority: normal severity: normal status: open title: URL Quoting page links to function Bytes instead of defintion versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30052> _______________________________________

6 23

[issue32625] Update the dis module documentation to reflect switch to wordcode
by Alexander Belopolsky June 12, 2019

June 12, 2019

New submission from Alexander Belopolsky <alexander.belopolsky(a)gmail.com>: A switch to wordcode is implemented in Python 3.6, but the documentation in the dis module was mostly left unchanged. See issue 26647, msg266388 and issue 27095, msg268389. ---------- assignee: docs@python components: Documentation messages: 310440 nosy: belopolsky, docs@python priority: normal severity: normal stage: needs patch status: open title: Update the dis module documentation to reflect switch to wordcode versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32625> _______________________________________

6 10

[issue33071] Document that PyPI no longer requires 'register'
by Paul Ganssle June 8, 2019

June 8, 2019

New submission from Paul Ganssle <p.ganssle(a)gmail.com>: I've been asked to post this by @brainwave (who is having some trouble getting an account on bpo due to technical difficulties). Per twine's github issue 311 ( https://github.com/pypa/twine/issues/311 ), it seems that distutil's docs Update setuptools and distutils docs, e.g., https://docs.python.org/3.6/distutils/packageindex.html#the-upload-command should be clarified to indicate that PyPI does not require register anymore, although other package indexes might. ---------- assignee: docs@python components: Distutils, Documentation messages: 313749 nosy: docs@python, dstufft, eric.araujo, p-ganssle priority: normal severity: normal status: open title: Document that PyPI no longer requires 'register' type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33071> _______________________________________

9 15

[issue18355] Merge super() guide into documentation
by Russkel June 7, 2019

June 7, 2019

New submission from Russkel: When looking for documentation on the correct usage on super (http://docs.python.org/2/library/functions.html?highlight=super#super), the documentation links to this rather will written blog post http://rhettinger.wordpress.com/2011/05/26/super-considered-super/ by Mr. Hettinger. I think there is value in merging that blog post into a HOWTO and including in the official documentation. I'm more than willing to create a patch if this is considered a good idea. ---------- assignee: docs@python components: Documentation messages: 192262 nosy: Russkel, docs@python, rhettinger priority: normal severity: normal status: open title: Merge super() guide into documentation _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18355> _______________________________________

5 7

[issue30699] Misleading class names in datetime.tzinfo usage examples
by Robert Tasarz June 4, 2019

June 4, 2019

New submission from Robert Tasarz: https://docs.python.org/3/library/datetime.html#datetime-objects gives in an example two classes named GMT1 and GMT2 subclassing tzinfo, defined with dst(…) methods returning one hour timedelta for summer periods. This is in conflict with naming, as GMT timezone is not defined with any daylight saving time, so any timezone offsetted from it shouldn't be as well. I would suggest renaming them to something like BrusselsTZ and HelsinkiTZ (with a comment that this is simplified implementation, that doesn't account for exact hour when dst switch is made, and maybe mentioning pytz) and tzname(…) to return ('CET', 'CEST')[bool(self.dst(dt))] and ('EET', 'EEST')[bool(self.dst(dt))] accordingly. Also https://docs.python.org/3/library/datetime.html#time-objects has an example with GMT1 class, though this time dst(…) unconditionally returns offset 0 properly, tzname(…) gives 'Europe/Prague' – region that uses dst. IMHO returning any of: "CET", "GMT+1", "Africa/Tunis" would be better here. ---------- assignee: docs@python components: Documentation messages: 296296 nosy: Robert.Tasarz, docs@python priority: normal severity: normal status: open title: Misleading class names in datetime.tzinfo usage examples type: enhancement versions: Python 2.7, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30699> _______________________________________

5 7

[issue19184] dis module has incorrect docs for RAISE_VARARGS
by Ned Batchelder June 2, 2019

June 2, 2019

New submission from Ned Batchelder: The order of values on the stack is backwards for RAISE_VARARGS. The docs say: "Raises an exception. argc indicates the number of parameters to the raise statement, ranging from 0 to 3. The handler will find the traceback as TOS2, the parameter as TOS1, and the exception as TOS." But in fact, the order is reverse of that. In the one-parameter case, the exception is TOS, in the two-parameter case, the value is TOS, and in the three-parameter case, the traceback is TOS. Not sure how to write that concisely, thought. :) ---------- assignee: docs@python components: Documentation keywords: easy messages: 199096 nosy: docs@python, nedbat priority: normal severity: normal status: open title: dis module has incorrect docs for RAISE_VARARGS versions: Python 2.7, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19184> _______________________________________

9 16

[issue32573] sys.argv documentation should include caveat for embedded environments
by Pedro June 2, 2019

June 2, 2019

New submission from Pedro <pgacv2+pythonbugs(a)gmail.com>: Embedded Python interpreters, such as Boost.Python, do not have sys.argv available. (sys itself works fine.) This causes the interpreter to crash with the following exception when you try to access argv: AttributeError: 'module' object has no attribute 'argv' I'm not sure how closely related this is to #15577 or PEP 432. A simple workaround is to manually assign a list with an empty string to argv, as suggested by https://github.com/google/oauth2client/issues/642. However, the documentation for the sys module makes no mention of this special case for argv, and the line at the top that says "It is always available" can easily be interpreted to mean that *all* of sys's attributes will always be available. I suggest adding the following to the documentation for sys.argv: ======== Since `argv` contains the list of **command line** arguments passed to the Python interpreter, `argv` is not available within embedded interpreters, and scripts that run in embedded environments will raise an `AttributeError` when they attempt to access `argv`. As a workaround, assign a list with an empty string manually: ``` import sys if not hasattr(sys, 'argv'): sys.argv = [''] ``` ---------- assignee: docs@python components: Documentation messages: 310105 nosy: docs@python, pgacv2 priority: normal severity: normal status: open title: sys.argv documentation should include caveat for embedded environments type: enhancement versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32573> _______________________________________

6 14

[issue29414] Change 'the for statement is such an iterator' in Tutorial
by Jim Fasarakis-Hilliard June 1, 2019

June 1, 2019

New submission from Jim Fasarakis-Hilliard: The current line is confusing hinting that the for statement is actually an object, it also makes a reference to iterators which the tutorial doesn't disambiguate until the chapter on Classes. I've added a small patch that, in my opinion, makes it clearer by using the terminology of the previous sentence. ---------- assignee: docs@python components: Documentation messages: 286678 nosy: Jim Fasarakis-Hilliard, docs@python priority: normal severity: normal status: open title: Change 'the for statement is such an iterator' in Tutorial versions: 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/issue29414> _______________________________________

6 16

[issue25735] math.factorial doc should mention integer return type
by John Yeung May 31, 2019

May 31, 2019

New submission from John Yeung: The math module docs state Except when explicitly noted otherwise, all return values are floats. But math.factorial isn't what I would call explicit about returning int: math.factorial(x) Return x factorial. Raises ValueError if x is not integral or is negative. At minimum, shouldn't the first sentence be "Return x factorial as an int."? I haven't tested on all Python versions, but math.factorial on 2.7 and 3.2 definitely return int (or long in Python 2 when necessary). ---------- assignee: docs@python components: Documentation messages: 255382 nosy: John.Yeung, docs@python priority: normal severity: normal status: open title: math.factorial doc should mention integer return type versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25735> _______________________________________

7 12

[issue21314] Bizarre help
by Vedran Čačić May 31, 2019

May 31, 2019

New submission from Vedran Čačić: Please look at the output of help(object.__ge__). 1. What's that $ in front of self? lt and gt don't have it. 2. What's that / as a third argument? Many wrapper functions have it (for example, see help(tuple.__len__). 3. What's that -- as the first line of doc? Similar methods don't have it. ---------- assignee: docs@python components: Documentation messages: 216899 nosy: Vedran.Čačić, docs@python priority: normal severity: normal status: open title: Bizarre help versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21314> _______________________________________

18 31