Mailman 3 January 2011 - docs

[issue10225] Fix doctest runable examples in python manual
by Terry J. Reedy 10 Jan '11

10 Jan '11

Terry J. Reedy <tjreedy(a)udel.edu> added the comment: As I understand this, your patch would fix numerous errors in the docs, but has not been applied. It would be nice to get the fixes into 3.2. What sort of feedback do you want? Proofreading of text? Recheck of doctest? Does sphinx suppress doctest comments like #doctest: +IGNORE_EXCEPTION_DETAIL ? doctest.testfile("C:/programs/PyDev/py32/Doc/howto/sorting.rst", module_relative = False) fails 23 of 37 attempts, so improvement is needed ;-). ---------- nosy: +terry.reedy _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10225> _______________________________________

2 1

[issue10858] Make source code links less proeminent
by Antoine Pitrou 10 Jan '11

10 Jan '11

New submission from Antoine Pitrou <pitrou(a)free.fr>: Reading library source code will only be enlightening to expert users, since most modules are not academic but real-world implementations, with all the complications it entails. Therefore, putting a link at the top of module sections is only confusing for most people. I would like to shift these links to the bottom of doc pages, where we already have "see also" links to RFCs and the like. ---------- assignee: docs@python components: Documentation messages: 125669 nosy: docs@python, pitrou, rhettinger priority: normal severity: normal status: open title: Make source code links less proeminent versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10858> _______________________________________

6 10

[issue10873] String formatting example invalid
by Ashwin Purohit 10 Jan '11

10 Jan '11

New submission from Ashwin Purohit <purohit(a)gmail.com>: Your example on page http://docs.python.org/tutorial/inputoutput.html is outdated and won't work in Python 2.7: Basic usage of the str.format() method looks like this: >>> print 'We are the {} who say "{}!"'.format('knights', 'Ni') We are the knights who say "Ni!" Now, all brackets have to have a numeric or keyword argument. ---------- assignee: docs@python components: Documentation messages: 125838 nosy: doagie, docs@python priority: normal severity: normal status: open title: String formatting example invalid type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10873> _______________________________________

4 4

Docs in epub or single-html (without the left menu) format
by Santiago Romero 09 Jan '11

09 Jan '11

Hi all. First of all, sorry for my poor english. I've recently purchased a nice 9 inches e-ink ebook reader and I wanted to read all python 2.7 documentation by using it, but I've been unable to found python.org's documents in .epub format. PDF is not usable in ebook readers because is intended for printing and the "blank" page margins make the documents almost unreadable. On other websites/projects, when I can't find a document in epub format, I usually download and use the "single html" versions. Unfortunatelly, python html documentation includes a "left menu" that takes almost 35-40% of the reading space in my ebook. Are the docs going to be "converted" (if possible) to epub or is there a way to get a single-html version without the left menu? Thanks a lot. -- Santiago Romero

2 1

A probable bug in The Python Tutorial
by Youcheng Lin 09 Jan '11

09 Jan '11

Hi, In the section 3.2. First Steps Towards Programming This example introduces several new features. - The first line contains a *multiple assignment*: the variables a and b simultaneously get the new values 0 and 1. On the last line this is used again, demonstrating that the expressions on the right-hand side are all evaluated first before any of the assignments take place. The right-hand side expressions are evaluated from the* left to the right.* * * I think the red underscored part should be *right to the left* -- Sincerely, Youcheng Lin Email: youcheng.t.lin(a)gmail.com Cellphone: 312.823.0653 ________________________________________________________________ ________________________

2 1

[issue10871] argparse example use "file" instead of "open"
by Baptiste Lepilleur 09 Jan '11

09 Jan '11

New submission from Baptiste Lepilleur <blep(a)users.sourceforge.net>: In section "14.4.3.6. type" of the argparse module, the following code sample is given: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('foo', type=int) >>> parser.add_argument('bar', type=file) >>> parser.parse_args('2 temp.txt'.split()) Namespace(bar=<open file 'temp.txt', mode 'r' at 0x...>, foo=2) The built-in "file" used for argument 'bar' no longer exists in python 3.2. ---------- assignee: docs@python components: Documentation messages: 125834 nosy: blep, docs@python priority: normal severity: normal status: open title: argparse example use "file" instead of "open" versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10871> _______________________________________

2 1

[issue10870] Last line of argparse code samples can not be read on Windows
by Baptiste Lepilleur 09 Jan '11

09 Jan '11

New submission from Baptiste Lepilleur <blep(a)users.sourceforge.net>: When the code samples from the CHM documentation are displayed, if the lines are too long, a scroll bar is added at the bottom which prevents reading the last line of the code sample. Usually this can be worked-around by making the windows larger, but some examples in the documentation of the argparse are so wide that even in full screen, the window is not wide enough. I attached a screen capture to illustrate the issue (taken from section 14.4.3.3. nargs of Python 3.2b2). This is even worth with one-liner code sample when not browsing full screen (e.g. with the index on the side). Environment: Windows XP SP3, resolution: 1024x768, python 3.2b2. I don't know if it is possible, but adding a blank line at the end of code sample that are more than 80 characters wide would likely work-around the issue. ---------- assignee: docs@python components: Documentation files: argparse-codesample-unreadable.png messages: 125832 nosy: blep, docs@python priority: normal severity: normal status: open title: Last line of argparse code samples can not be read on Windows versions: Python 3.2 Added file: http://bugs.python.org/file20321/argparse-codesample-unreadable.png _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10870> _______________________________________

2 1

[issue10533] Need example of using __missing__
by Éric Araujo 09 Jan '11

09 Jan '11

Éric Araujo <merwok(a)netwok.org> added the comment: Great, thanks. We’ll see later if more cross-links are needed. ---------- stage: needs patch -> committed/rejected _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10533> _______________________________________

1 0

[issue10357] ** and "mapping" are poorly defined in python docs
by Fergal Daly 09 Jan '11

09 Jan '11

New submission from Fergal Daly <fergald(a)gmail.com>: According to the index, the only place that mentions ** in argument lists is http://docs.python.org/tutorial/controlflow.html#index-1099 and gives no indication of what an object must support to allow **. When you attempt to ** an object the real attribute exception is suppressed and you get a message "argument after ** must be a mapping" "mapping" is quite loosely defined. There are 3 definitions, the glossary entry seems the most complete http://docs.python.org/library/stdtypes.html#index-625 http://docs.python.org/reference/datamodel.html#index-842 http://docs.python.org/glossary.html#term-mapping But even the glossary entry doesn't tell you what you need for **. Only by reading the C source code did I discover that to be usable in **, an object must implement .keys() and .__getitem__(). The docs either should add .keys() to the definition of mapping or the code should use some other term or simply allow the original exception to reach the user. ---------- assignee: docs@python components: Documentation messages: 120739 nosy: Fergal.Daly, docs@python priority: normal severity: normal status: open title: ** and "mapping" are poorly defined in python docs versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10357> _______________________________________

4 6

[issue10863] zlib.compress() fails with string
by Jose-Luis Fernandez-Barros 09 Jan '11

09 Jan '11

New submission from Jose-Luis Fernandez-Barros <jlfbarros(a)gmail.com>: On "The Python Tutorial", section 10.9. Data Compression http://docs.python.org/py3k/tutorial/stdlib.html#data-compression >>> import zlib >>> s = 'witch which has which witches wrist watch' ... >>> t = zlib.compress(s) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: must be bytes or buffer, not str Possible solution (sorry, newbie) are: >>> s = b'witch which has which witches wrist watch' or >>> s = 'witch which has which witches wrist watch'.encode("utf-8") At "The Python Standard Library", secction 12. Data Compression and Archiving http://docs.python.org/py3k/library/zlib.html#module-zlib apparently example is correct: zlib.compress(string[, level]) ---------- assignee: docs@python components: Documentation messages: 125702 nosy: docs@python, joseluisfb priority: normal severity: normal status: open title: zlib.compress() fails with string type: compile error versions: Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10863> _______________________________________

2 4