Mailman 3 November 2015 - docs

[issue11015] Bring test.support docs up to date
by Nick Coghlan 11 Feb '18

11 Feb '18

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: The test.support docs are there to help CPython devs with writing good unit tests more easily. There are a few additions we've made in recent years that haven't made it into the .rst file, so it is easy to miss useful tools if you don't go looking through the module source code. There are some other helper modules (such as test.script_helper) that could also stand to be made easier to find. Fixing this is just a matter of doing a pass through test.support and the test directory looking for things that might be worth mentioning in the test package docs. ---------- assignee: docs@python keywords: easy messages: 127086 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Bring test.support docs up to date type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11015> _______________________________________

11 36

[issue8722] Documentation for __getattr__
by Paul Davis 04 Feb '18

04 Feb '18

New submission from Paul Davis <paul.joseph.davis(a)gmail.com>: The docs for __getattr__ in the object model section could be more specific on the behavior when a @property raises an AttributeError and there is a custom __getattr__ defined. Specifically, it wasn't exactly clear that __getattr__ would be invoked after a @property was found and evaluated. The attached script demonstrates the issue on OS X 10.6, Python 2.6.1 I'm thinking something along the lines of: If the attribute search encounters an AttributeError (perhaps due to a @property raising the error) the search is considered a failure and __getattr__ is invoked. ---------- assignee: docs@python components: Documentation files: example.py messages: 105790 nosy: Paul.Davis, docs@python priority: normal severity: normal status: open title: Documentation for __getattr__ type: feature request versions: Python 2.6 Added file: http://bugs.python.org/file17349/example.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8722> _______________________________________

8 23

[issue11023] pep 227 missing text
by Alan Isaac 25 Jan '18

25 Jan '18

New submission from Alan Isaac <alan.isaac(a)gmail.com>: In PEP 227 missing text is marked with XXX. Most of this is just calls for examples and elaboration. However under the Implementation section XXX marks a substantive question about the documentation. Fixing this may be low priority, but a tracker search suggested it is currently not even being tracked ... ---------- assignee: docs@python components: Documentation messages: 127184 nosy: aisaac, docs@python priority: normal severity: normal status: open title: pep 227 missing text type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11023> _______________________________________

4 3

[issue12706] timeout sentinel in ftplib and poplib
by Senthil Kumaran 25 Jan '18

25 Jan '18

New submission from Senthil Kumaran <senthil(a)uthcode.com>: - ftplib and poplib, has them as timeout=None, while they default to socket._GLOBAL_DEFAULT_TIMEOUT object. This is wrong; someone may pass None thinking it will trigger the default behaviour, and have nasty surprises. ---------- assignee: docs@python messages: 141740 nosy: docs@python, orsenthil priority: normal severity: normal stage: needs patch status: open title: timeout sentinel in ftplib and poplib type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12706> _______________________________________

5 7

[issue17799] settrace docs are wrong about "c_call" events
by Ned Batchelder 24 Jan '18

24 Jan '18

New submission from Ned Batchelder: Looking into this Stack Overflow question: http://stackoverflow.com/questions/16115027/pythons-sys-settrace-wont-creat… Reading the code in c_eval.c and friends, it looks like "c_call" events are never passed to the trace function, only to the profile function. The docs are wrong and should be fixed. The setprofile docs simply point to settrace for details, so the text needs to accommodate both functions' needs. ---------- assignee: docs@python components: Documentation messages: 187406 nosy: docs@python, nedbat priority: low severity: normal status: open title: settrace docs are wrong about "c_call" events versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17799> _______________________________________

7 15

[issue15221] os.path.is*() may return False if path can't be accessed
by Giampaolo Rodola' 15 Jan '18

15 Jan '18

New submission from Giampaolo Rodola' <g.rodola(a)gmail.com>: It seems a doc fix is the best way to go, in which case I leave this one to a native English speaker: http://mail.python.org/pipermail/python-dev/2012-June/120788.html Alternatively a new 'strict' parameter has been proposed as a workaround: http://mail.python.org/pipermail/python-dev/2012-June/120800.html ---------- assignee: docs@python components: Documentation messages: 164307 nosy: christian.heimes, docs@python, eric.araujo, ezio.melotti, georg.brandl, giampaolo.rodola, ncoghlan priority: normal severity: normal status: open title: os.path.is*() may return False if path can't be accessed versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15221> _______________________________________

7 9

[issue11260] smtpd-as-a-script feature should be documented and should use argparse
by Xavier Morel 09 Jan '18

09 Jan '18

New submission from Xavier Morel <xavier.morel(a)masklinn.net>: argparse has been merged to the standard library in 3.2, and (tell me if I'm wrong) would therefore be the "best-practices" way to parse command-line arguments. Numerous stdlib modules can be used as scripts, but they tend to have ad-hoc documentation (if they are at all documented) and arguments parsing (using any of the 4 available methods in Python: straight from sys.argv, getopt, optparse and argparse). I picked smtpd as a first shot since it does something useful (SMTP proxy) and has a pretty good (if ad-hoc) command-line documentation. smtpd is currently using getopt for its options parsing and the argument parsing is very cleanly factored: the port only had to replace the implementation of the `parseargs` function (and add and remove some helpers). * The port keeps the existing arguments semantics (including the mandatory host:port syntax for the local and remote specs if overridden) * The port tries to maintain the old error messages, but due to the way argparse works (or the way I used it for the specs) the parity is not perfect when providing incorrect specs * The CLI help uses argparse's formatting, and the documentation for the local and remote specs was set on these arguments rather than as an epilog. The version string was also removed from the help screen * Because they are set by argparse's arguments validation, the status codes on incorrect arguments are slightly different: - running smtpd.py as a regular user without the `--nosetuid` flag still exits with status 1 - providing incorrect spec formats (missing or non-int port) or providing too many positional arguments (3 or more) now exits with status 2 (formerly 1) ---------- assignee: docs@python components: Documentation, Library (Lib) files: smtpd-to-argparse.diff keywords: patch messages: 128917 nosy: barry, docs@python, xmorel priority: normal severity: normal status: open title: smtpd-as-a-script feature should be documented and should use argparse versions: Python 3.3 Added file: http://bugs.python.org/file20812/smtpd-to-argparse.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11260> _______________________________________

8 18

[issue22671] Typo in class io.BufferedIOBase docs
by gigaplastik 12 Dec '17

12 Dec '17

New submission from gigaplastik: The online documentation for class io.BufferedIOBase states the following: "Besides, the read() method does not have a default implementation that defers to readinto()." According to the documentation for class io.RawIOBase (which the statement compares with) read() method actually defers to readall(), NOT readinto() as misleadingly stated. The same typo is present in help('io.BufferedIOBase') output and, very likely, in all 3.X line docs for this class. ---------- assignee: docs@python components: Documentation messages: 229677 nosy: docs@python, gigaplastik priority: normal severity: normal status: open title: Typo in class io.BufferedIOBase docs type: enhancement versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22671> _______________________________________

9 14

[issue24896] It is undocumented that re.UNICODE affects re.IGNORECASE
by Leif Arne Storset 16 Nov '17

16 Nov '17

New submission from Leif Arne Storset: A non-ASCII string does not match a regular expression case-insensitively unless the UNICODE flag is set. This seems reasonable, but the documentation seems to imply that this is not the case. The example: import re # Does not match re.compile(u"неоднозначность", re.IGNORECASE) \ .findall(u"Неоднозначность") # Matches re.compile(u"неоднозначность", re.IGNORECASE | re.UNICODE) \ .findall(u"Неоднозначность") (In Python 3, it does not match if re.ASCII is given.) The documentation (2.7) says: re.UNICODE Make \w, \W, \b, \B, \d, \D, \s and \S dependent on the Unicode character properties database. (https://docs.python.org/2/library/re.html#re.UNICODE) My regex does not use any of those escapes, yet the regex changes behavior with the UNICODE flag. This leads to confusion when the regex doesn't match. The documentation is very specific about the behavior that changes with the flag, implying that behavior not mentioned is unaffected. Of course, it's easy to guess the correct (hopefully) solution. Still, I suggest changing the documentation to mention that re.IGNORECASE is affected. Looking at the source code, there seems to be further consequences (it mentions "Unicode locale") which may also warrant a mention. If you do want to avoid specifics, however, even a hand-wavy reference to something like "match according to Unicode" would help, because it implies that not only the escapes change behavior. In Python 3, there is a counterpart to the 2.7 problem: re.ASCII makes our Cyrillic string not match. Again, this behavior makes intuitive sense, but the documentation seems to indicate something different: re.ASCII Make \w, \W, \b, \B, \d, \D, \s and \S perform ASCII-only matching instead of full Unicode matching. This is only meaningful for Unicode patterns, and is ignored for byte patterns. … re.IGNORECASE Perform case-insensitive matching; expressions like [A-Z] will match lowercase letters, too. This is not affected by the current locale and works for Unicode characters as expected. re.ASCII does appear to affect re.IGNORECASE. Since this is the non-default case, however, I'm not sure it's worth calling it out. I'd be happy even if only the 2.7 docs change. ---------- assignee: docs@python components: Documentation messages: 248829 nosy: Leif Arne Storset, docs@python priority: normal severity: normal status: open title: It is undocumented that re.UNICODE affects re.IGNORECASE versions: Python 2.7, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24896> _______________________________________

8 14

[issue14124] _pickle.c comment/documentation improvement
by Merlijn van Deen 09 Nov '17

09 Nov '17

New submission from Merlijn van Deen <valhallasw(a)gmail.com>: As suggested by loewis in msg154233, I created some documentation to help people get started with _pickle.c. ---------- assignee: docs@python components: Documentation, Extension Modules files: _pickle_c_doc.diff keywords: patch messages: 154284 nosy: docs@python, valhallasw priority: normal severity: normal status: open title: _pickle.c comment/documentation improvement type: enhancement versions: Python 3.3 Added file: http://bugs.python.org/file24641/_pickle_c_doc.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14124> _______________________________________

3 4