Mailman 3 August 2013 - docs

[issue14911] generator.throw() documentation inaccurate
by Kristján Valur Jónsson 17 Oct '18

17 Oct '18

New submission from Kristján Valur Jónsson <kristjan(a)ccpgames.com>: the documentation for generator.throw() does not mention the fact that it has the same semantics for the three arguments as a "raise" expression has. The first two arguments can be: throw(exc_type, None) throw(exc_type, value) throw(exc_type, exc_instance) throw(exc_instance, None) ---------- assignee: docs@python components: Documentation messages: 161565 nosy: docs@python, kristjan.jonsson priority: normal severity: normal status: open title: generator.throw() documentation inaccurate versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14911> _______________________________________

5 12

[issue11233] clarifying Availability: Unix
by Sandro Tosi 15 Oct '18

15 Oct '18

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: Hi, following up http://mail.python.org/pipermail/docs/2011-February/003083.html we have a chat on #python-dev on the topic, the situation is - all started with os.lchmod() and as.lchflags() methods not available on a Debian system - that's because POSIX does not require those functions and then Linux systems don't provide them - so we then thought about clarifying, only for those 2 methods, that they might not be available with a format like "availability: some unix systems" - then we noticed that on top of os doc there's a notice "An “Availability: Unix” note means that this function is commonly found on Unix systems. It does not make any claims about its existence on a specific operating system." and so we thought about linking every 'Availability: Unix' to that note - or transform that not in a footnote and link every 'Availability: Unix' for functions that might not be present to that footnote. It's enough for the conversation dump: ideas/suggestions? :) ---------- assignee: docs@python components: Documentation messages: 128746 nosy: docs@python, sandro.tosi priority: normal severity: normal status: open title: clarifying Availability: Unix _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________

11 25

[issue15258] argparse documentation: Improve optparse section regarding allow_interspersed_args
by Nefarious CodeMonkey, Jr. 14 Aug '18

14 Aug '18

New submission from Nefarious CodeMonkey, Jr. <nejucomo(a)users.sourceforge.net>: It was not obvious from the documentation on argparse how to emulate the optparse.OptionParser.allow_interspersed_args feature. Please add something like the following to the section titled "Upgrading optparse code" (see: http://docs.python.org/library/argparse.html#upgrading-optparse-code ) """ * If the optparse code sets allow_interspersed_args to False, then add an argparse positional argument with nargs=argparse.REMAINDER """ ---------- assignee: docs@python components: Documentation messages: 164702 nosy: docs@python, nejucomo priority: normal severity: normal status: open title: argparse documentation: Improve optparse section regarding allow_interspersed_args type: enhancement versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15258> _______________________________________

5 4

[issue13574] refresh example in doc for Extending and Embedding
by Florent Xicluna 04 Aug '18

04 Aug '18

New submission from Florent Xicluna <florent.xicluna(a)gmail.com>: The example uses PyInstanceObject which is Python 2 only (old-style classes). http://docs.python.org/dev/extending/newtypes.html#weak-reference-support ---------- assignee: docs@python components: Documentation, Extension Modules messages: 149183 nosy: docs@python, flox priority: normal severity: normal stage: needs patch status: open title: refresh example in doc for Extending and Embedding type: behavior versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13574> _______________________________________

6 5

[issue12743] C API marshalling doc contains XXX
by JJeffries 27 Jul '18

27 Jul '18

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

[issue17286] Make subprocess handling text output with universal_newlines more obious
by Baptiste Lepilleur 11 Jun '18

11 Jun '18

New submission from Baptiste Lepilleur: It tooks me a while to figure out that using universal_newlines was the solution to "tell" subprocess that I wanted text string output instead of byte string. A search on stackoverflow shows that this issue is common and the solution nearly unknown (answer is usually to decode the byte string manually)... Because dealing with text output is IMHO the most common use case, the subprocess documentation should make it easier to "find" the recipe. I would suggest changing the documentation so that the universal_newlines is made obvious as it is very important: 1) the first /bin/vikings example be modified to show the use of this flag (at the top of the documentation, most people copy/past that): >>> p = subprocess.Popen(args, universal_newlines=True) # Success! and at a small comment below the example to explain that flag 2) change other example similarly when that make sense, IMHO: - ifconfig example - one of the subprocess.check_output example - subprocess.check_output() example, consider separating the byte string / text string example for increased visibility 3) consider adding a section with an obvious title "Dealing with binary and text input/output", providing examples and pointer to the correct documentation (I would place it after the convenience functions section for visibility). I think this would help attracting "eye" on this large piece of documentation. ---------- assignee: docs@python components: Documentation messages: 182872 nosy: Baptiste.Lepilleur, docs@python priority: normal severity: normal status: open title: Make subprocess handling text output with universal_newlines more obious type: enhancement versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17286> _______________________________________

5 5

[issue13525] Tutorial: Example of Source Code Encoding triggers error
by Nicolas Goutte 09 May '18

09 May '18

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 22 Mar '18

22 Mar '18

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

[issue18855] Inconsistent README filenames
by Madison May 01 Mar '18

01 Mar '18

New submission from Madison May: Is there any reason (other than backwards compatibility) that the names of README files are inconsistent? README: 3 instances - root, /Mac, /Misc, /Tools readme.txt: 2 instances - /PC, /PCbuild README.txt: 1 instance - /Doc ---------- assignee: docs@python components: Documentation messages: 196299 nosy: docs@python, madison.may priority: normal severity: normal status: open title: Inconsistent README filenames _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18855> _______________________________________

11 11

[issue17232] Improve -O docs
by Maciej Fijalkowski 25 Feb '18

25 Feb '18

New submission from Maciej Fijalkowski: This is what the current documentation says: -O Turn on basic optimizations. This changes the filename extension for compiled (bytecode) files from .pyc to .pyo. See also PYTHONOPTIMIZE. -OO Discard docstrings in addition to the -O optimizations. As far as I know, the only "optimization" that's done is removal of __debug__ sections and assert statements and has been like this for years. Maybe it should say so "-O does not do any optimizations, only removes assert statement" or so. ---------- assignee: docs@python components: Documentation messages: 182365 nosy: docs@python, fijall priority: normal severity: normal status: open title: Improve -O docs type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17232> _______________________________________

15 33