Mailman 3 August 2012 - docs

[issue15444] Incorrectly writen contributor's names
by Serhiy Storchaka 11 Aug '12

11 Aug '12

New submission from Serhiy Storchaka <storchaka(a)gmail.com>: Some contributor's names written incorrectly (in ASCII) in documentation: Jesús Cea Avión as Jesús Cea Avion Lars Gustäbel as Lars Gustaebel Gerhard Häring as Gerhard Haering Marc-André Lemburg as Marc-Andre Lemburg Martin von Löwis as Martin von Loewis Charles-François Natali as Charles-Francois Natali Žiga Seilnach as Ziga Seilnacht The proposed patch restores natural spelling (based on Doc/ACKS and Misc/ACKS). I'm not sure about how to write right: Žiga Seilnach or Seilnacht? ---------- assignee: docs@python components: Documentation files: doc-nonascii-names.patch keywords: patch messages: 166330 nosy: docs@python, ghaering, jcea, lars.gustaebel, lemburg, loewis, neologix, storchaka, zseil priority: normal severity: normal status: open title: Incorrectly writen contributor's names Added file: http://bugs.python.org/file26504/doc-nonascii-names.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15444> _______________________________________

8 21

[issue15607] New print's argument "flush" is not mentioned in docstring
by Serhiy Storchaka 10 Aug '12

10 Aug '12

New submission from Serhiy Storchaka: New print's argument "flush" is not mentioned in docstring. ---------- assignee: docs@python components: Documentation keywords: easy messages: 167809 nosy: docs@python, storchaka priority: normal severity: normal stage: needs patch status: open title: New print's argument "flush" is not mentioned in docstring versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15607> _______________________________________

5 5

socketserver documentation
by Lipska TheCat 10 Aug '12

10 Aug '12

Hi I have recently begun to investigate Python and have come up against a number of apparent issues with the documentation 20.19.3. RequestHandler Objects investigating the socketserver.py code I believe the docs should be altered to refer to the class BaseRequestHandler and not RequestHandler. I also think that some class specific docs for StreamRequestHandler and DatagramRequestHandler would be useful. I don't know what system you use to maintain the documentation but I'd be happy to contribute some changes/additions Kind Regards lipska

1 0

Re: [docs] Provide some examples for usage of ElementTree methods/attributes (issue 15586)
by ellisd23＠gmail.com 09 Aug '12

09 Aug '12

Thank you Eli and Ezio for your comments. I have made changes per your suggestions and will upload the patch now. http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… File Doc/library/xml.etree.elementtree.rst (right): http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:69: tree = ET() I apologize. I originally wrote examples that ran and then saw that the development version of the docs already had examples, so I attempted to change over mine to match. On 2012/08/09 09:44:44, eli.bendersky wrote: > Why are you calling the module here? Did you actually execute the examples? > Please make sure all examples execute correctly. > > For loading data from the file, use ElementTree's constructor. No need to invoke > the parse method as well. http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:73: Reading the file from a remote URL:: I guess the only point of confusion I saw is that when parsing from a file (as a above), rather than taking a file object, parse takes the filename in the current working directory. I'll go ahead and remove it though, unless you think this point is valid. On 2012/08/09 09:44:44, eli.bendersky wrote: > I don't think the urllib example belongs here. It's clear that if ET can build > itself from files, streams and strings, than everything that produces those will > work. http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:159: ... tree.write('output.xml') I'm not sure from the code review tool which line you mean, though I think it is 159. Let me know if I'm wrong. On 2012/08/09 10:51:48, ezio.melotti wrote: > Leave an empty line before this (same with the following examples). http://bugs.python.org/review/15586/

1 0

[issue4966] Improving Lib Doc Sequence Types Section
by Ezio Melotti 09 Aug '12

09 Aug '12

Changes by Ezio Melotti <ezio.melotti(a)gmail.com>: ---------- versions: +Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue4966> _______________________________________

1 0

[issue15501] Document exception classes in subprocess module
by Anton Barkovsky 09 Aug '12

09 Aug '12

New submission from Anton Barkovsky: Exception classes from subprocess module are mentioned in the doc but do not have their own entries. I'm attaching patches for 3.3, 3.2 and 2.7 This issue supersedes #14966. ---------- assignee: docs@python components: Documentation files: subprocess_doc_3.3.patch keywords: patch messages: 166895 nosy: anton.barkovsky, docs@python priority: normal severity: normal status: open title: Document exception classes in subprocess module type: enhancement versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 Added file: http://bugs.python.org/file26598/subprocess_doc_3.3.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15501> _______________________________________

4 11

[issue14966] Fully document subprocess.CalledProcessError
by Nick Coghlan 09 Aug '12

09 Aug '12

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: CalledProcessError provides a nice encapsulation for a returncode, the original command and any partial output. The API should be officially documented so that third party subprocess.Popen convenience wrappers can use it easily. ---------- assignee: docs@python components: Documentation keywords: easy messages: 161984 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Fully document subprocess.CalledProcessError type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14966> _______________________________________

5 4

Re: [docs] Documentation for Signature, Parameter and signature in inspect module (issue 15151)
by yselivanov.ml＠gmail.com 09 Aug '12

09 Aug '12

http://bugs.python.org/review/15151/diff/5438/Doc/library/inspect.rst File Doc/library/inspect.rst (right): http://bugs.python.org/review/15151/diff/5438/Doc/library/inspect.rst#newco… Doc/library/inspect.rst:432: provide no metadata about their arguments. On 2012/08/08 21:14:48, asvetlov wrote: > maybe "metadata for their arguments"? "about" is better. http://bugs.python.org/review/15151/diff/5438/Doc/library/inspect.rst#newco… Doc/library/inspect.rst:442: a modified copy On 2012/08/08 21:14:48, asvetlov wrote: > put dot at end agree http://bugs.python.org/review/15151/diff/5438/Doc/library/inspect.rst#newco… Doc/library/inspect.rst:547: **Example** On 2012/08/08 21:14:48, asvetlov wrote: > Just remove this line. Bold looks ugly from my perspective well, there needs to be some kind of header. http://bugs.python.org/review/15151/diff/5438/Doc/library/inspect.rst#newco… Doc/library/inspect.rst:607: >>> def foo(a, b=10): On 2012/08/08 21:14:48, asvetlov wrote: > Deindent example to avoid gray border around. Not sure. I actually like how grey borders separate examples from other content. Makes it easier to read http://bugs.python.org/review/15151/

1 0

Re: [docs] Provide some examples for usage of ElementTree methods/attributes (issue 15586)
by ezio.melotti＠gmail.com 09 Aug '12

09 Aug '12

http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… File Doc/library/xml.etree.elementtree.rst (right): http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:129: :meth:`Element.text` accesses the element's content:: I would rephrase this paragraph to have 3 sentences: the first about findall, the second about find and text, and the third about get. + :meth:`Element.get` safely accesses attributes. Why safely? What happens if the attribute is missing? (I'm not saying these should be answered here, but the use of "safely" makes me wonder). +:meth:`Element.text` accesses the element's content Is the "content" only text nodes? http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:133: ... print(country.get('name'), rank) I would change the last line to: name = country.get('name') print(name, rank) so that the methods used in the first 3 lines matches the 3 sentences in the previous paragraph. http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:137: 68 Panama If you printed name and rank, why are these showing rank and name? http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:153: Let's say we want to subtract one from each country's rank:: s/subtract/add/ http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:158: ... rank.set('updated', 'yes') I would add something like ", and add an ``updated`` attribute to the rank element" or ", and mark it with an ``updated`` attribute" to the previous sentence. http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:159: ... tree.write('output.xml') Leave an empty line before this (same with the following examples). http://bugs.python.org/review/15586/

1 0

Provide some examples for usage of ElementTree methods/attributes (issue 15586)
by eliben＠gmail.com 09 Aug '12

09 Aug '12

http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… File Doc/library/xml.etree.elementtree.rst (right): http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:40: .. code-block:: xml Nice! http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:69: tree = ET() Why are you calling the module here? Did you actually execute the examples? Please make sure all examples execute correctly. For loading data from the file, use ElementTree's constructor. No need to invoke the parse method as well. http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:73: Reading the file from a remote URL:: I don't think the urllib example belongs here. It's clear that if ET can build itself from files, streams and strings, than everything that produces those will work. http://bugs.python.org/review/15586/diff/5683/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:125: If a more strict reliance on tree structure is desired, :meth:`Element.findall` I'd remove the "if a more strict reliance..." part. I'm not sure what it means. The findall/find examples are good http://bugs.python.org/review/15586/

1 0