Mailman 3 June 2012 - docs

[issue12743] C API marshalling doc contains XXX
by JJeffries July 27, 2018

July 27, 2018

New submission from JJeffries <jamesjeffries1(a)gmail.com>: The Python C API manual page for data marshaling contains the following paragraph. XXX What about error detection? It appears that reading past the end of the file will always result in a negative numeric value (where that’s relevant), but it’s not clear that negative values won’t be handled properly when there’s no error. What’s the right way to tell? Should only non-negative values be written using these routines? I suggest that the XXX should be removed as it is unclear why it's there. Patch to follow in the next couple of days if others agree. ---------- assignee: docs@python components: Documentation messages: 141959 nosy: JJeffries, docs@python priority: normal severity: normal status: open title: C API marshalling doc contains XXX _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12743> _______________________________________

7 13

[issue13525] Tutorial: Example of Source Code Encoding triggers error
by Nicolas Goutte May 9, 2018

May 9, 2018

New submission from Nicolas Goutte <nicolas.goutte(a)extragroup.de>: Current Behaviour The tutorial of Python 3.2.x has an example to set an encoding in a source file: http://docs.python.org/py3k/tutorial/interpreter.html#source-code-encoding It explains to set the following line at the start of the source code: # -*- coding: cp-1252 -*- However when done exactly so, Python raises the following exception: SyntaxError: encoding problem: with BOM The problem seems to be that Python knows Windows codepage 1252 as windows-1252 (its IANA charset name, see http://www.iana.org/assignments/charset-reg/windows-1252 ) or alternatively as cp1252 (without dash) but not as cp-1252 (with dash). As this is an example in the tutorial is particularly problematic, as users might not understand how to do it correctly. This is still the case in the tutorial of Python 3.3 alpha: http://docs.python.org/dev/tutorial/interpreter.html#source-code-encoding Expected Behaviour The tutorial should give a correct example, for example with: # -*- coding: windows-1252 -*- Alternatively a totally other example as for Python 2.7 would be nice too: http://docs.python.org/tutorial/interpreter.html#source-code-encoding Notes: I have tested this with following Python implementations: - Python 3.2.1 (openSUSE 12.1) on Linux - Python 3.2.2 on Windows 7 SP1 64 Bits - Python 3.2.2 on MacOS 10.5.8 (Always on the command line; I have not tested in IDLE.) ---------- assignee: docs@python components: Documentation files: cp_1252broken.py messages: 148798 nosy: docs@python, nicolasg priority: normal severity: normal status: open title: Tutorial: Example of Source Code Encoding triggers error versions: Python 3.2 Added file: http://bugs.python.org/file23840/cp_1252broken.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13525> _______________________________________

5 14

[issue13677] correct docstring for builtin compile
by Jim Jewett March 22, 2018

March 22, 2018

New submission from Jim Jewett <jimjjewett(a)gmail.com>: The current docstring for compile suggests that the flags are strictly for selecting future statements. These are not the only flags. It also suggests that the source must be source code and the result will be bytecode, which isn't quite true. I suggest changing: "The flags argument, if present, controls which future statements influence the compilation of the code." to: "The flags argument, if present, largely controls which future statements influence the compilation of the code. (Additional flags are documented in the AST module.)" ---------- assignee: docs@python components: Documentation files: bltinmodule.c.patch keywords: patch messages: 150337 nosy: Jim.Jewett, docs@python priority: normal severity: normal status: open title: correct docstring for builtin compile type: behavior Added file: http://bugs.python.org/file24105/bltinmodule.c.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13677> _______________________________________

4 6

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

Feb. 11, 2018

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 Feb. 5, 2018

Feb. 5, 2018

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 Jan. 26, 2018

Jan. 26, 2018

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 Jan. 25, 2018

Jan. 25, 2018

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

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

Jan. 15, 2018

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 Jan. 10, 2018

Jan. 10, 2018

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

[issue14124] _pickle.c comment/documentation improvement
by Merlijn van Deen Nov. 9, 2017

Nov. 9, 2017

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