Mailman 3 September 2012 - docs

Unable to view http://docs.python.org/py3k/c-api/intro.html in Firefox
by Williams, Winslow (ES) 06 Sep '12

06 Sep '12

Up until just recently, I was able to view the page at http://docs.python.org/py3k/c-api/intro.html using Mozilla Firefox version 3.6.28. Today, however, when I navigate to that link, I see the following error message: Content Encoding Error ----------------------------- The page you are trying to view cannot be shown because it uses an invalid or unsupported form of compression. Interestingly enough, the page displays properly in Internet Explorer 7. Unfortunately, I'm browsing from a work computer and can't give any detailed information about plugins or network setup (they keep things buttoned-down here). I appreciate your efforts in documenting the Python language. My job would be much more difficult without your awesome online manuals. Thanks, Winslow Williams

1 0

python docs quick search improvement
by David Hoese 06 Sep '12

06 Sep '12

Hi, I started a thread on python-list the other day, you can find the thread here: http://mail.python.org/pipermail/python-list/2012-September/629900.html The general question is: Is there something that can be done to improve the results of the quick search on the python documentation website? As an example if you search for 'print' in the python docs quick search the print statement isn't in the results and the print function isn't in the top 20 results. Some replies on the thread suggested that everyone should just use a popular search engine, optionally specifying to only search the docs site. Others also suggested the python docs site use a Google search box, but also that this can cost a lot of money. I'm not very familiar with including search in a site, so I can't offer much more than the thread I've started. Thanks, Dave

1 0

[issue15775] Add StopParser(), ResumeParser, and GetParsingStatus to expat
by Martin v. Löwis 06 Sep '12

06 Sep '12

Martin v. Löwis added the comment: Dávid: Another (similar) example is the Python for loop. In it's original form, it would increase an index and invoke __getitem__ until that *raised* IndexError. In the current definition, it converts the iterated-over object into an iterator, and keeps calling .next until that *raises* StopIteration. So raising an exception to indicate that something is finished is an established Python idiom. In any case, I still think adding StopParser is a useful addition, in particular since that would also allow giving True as the "resumable" argument. Any such change needs to be accompanied by also exposing XML_ResumeParser, and possibly XML_GetParsingStatus. Since we all agree that this is not an important change, I don't mind keeping this issue around until someone comes along to contribute code for it. ---------- title: Add StopParser() to expat -> Add StopParser(), ResumeParser, and GetParsingStatus to expat _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15775> _______________________________________

1 0

[issue15775] Add StopParser() to expat
by Amaury Forgeot d'Arc 06 Sep '12

06 Sep '12

Amaury Forgeot d'Arc added the comment: Your first point is true, even if the Python zen (try "import this") states that "Errors should never pass silently." For your second point: exceptions are a common thing in Python code. This is similar to the EAFP principle http://docs.python.org/glossary.html#term-eafp Also, this example http://docs.python.org/release/2.7.3/library/imp.html#examples shows that exceptions can be part of the normal flow control. ---------- assignee: -> docs@python components: +Documentation nosy: +docs@python _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15775> _______________________________________

1 0

Re: [docs] comma after leading optional argument is after bracket in docs (issue 15831)
by chris.jerdonek＠gmail.com 05 Sep '12

05 Sep '12

Reviewers: ezio.melotti, Message: Responding to Ezio's two comments. http://bugs.python.org/review/15831/diff/5943/Doc/library/functions.rst File Doc/library/functions.rst (right): http://bugs.python.org/review/15831/diff/5943/Doc/library/functions.rst#new… Doc/library/functions.rst:983: .. function:: print(*objects, sep=' ', end='\\n', file=sys.stdout, flush=False) On 2012/09/05 14:15:29, ezio.melotti wrote: > Why the * is missing here? The first argument *objects already receives all remaining positional arguments (since it itself has a *), so putting an additional * after *objects would be redundant. The single * is only necessary if the positional arguments portion doesn't end with *identifier. http://bugs.python.org/review/15831/diff/5943/Doc/library/http.client.rst File Doc/library/http.client.rst (right): http://bugs.python.org/review/15831/diff/5943/Doc/library/http.client.rst#n… Doc/library/http.client.rst:31: source_address=None) On 2012/09/05 14:15:29, ezio.melotti wrote: > This signature is not too nice, but I'm not sure how it could be improved. Is > strict a bool? Maybe using timeout=socket.getdefaulttimeout() might be ok > (assuming that's what it uses), or if it's set to None or something similar and > then re-set to the actual value you could use None in the signature and describe > it in prose later. I believe this is the best we can do to be correct. Here is the actual signature: def __init__(self, host, port=None, strict=_strict_sentinel, timeout=socket._GLOBAL_DEFAULT_TIMEOUT, source_address=None): The two arguments in question default to private sentinel values. I think it is at least an improvement over the old signature which had triply nested brackets. Please review this at http://bugs.python.org/review/15831/ Affected files: Doc/library/argparse.rst Doc/library/configparser.rst Doc/library/curses.rst Doc/library/functions.rst Doc/library/http.client.rst Doc/library/inspect.rst Doc/library/itertools.rst Doc/library/multiprocessing.rst Doc/library/optparse.rst Doc/library/ossaudiodev.rst Doc/library/random.rst Doc/library/socket.rst Doc/library/stdtypes.rst Doc/library/syslog.rst Doc/library/tkinter.tix.rst

1 0

comma after leading optional argument is after bracket in docs (issue 15831)
by ezio.melotti＠gmail.com 05 Sep '12

05 Sep '12

http://bugs.python.org/review/15831/diff/5943/Doc/library/functions.rst File Doc/library/functions.rst (right): http://bugs.python.org/review/15831/diff/5943/Doc/library/functions.rst#new… Doc/library/functions.rst:983: .. function:: print(*objects, sep=' ', end='\\n', file=sys.stdout, flush=False) Why the * is missing here? http://bugs.python.org/review/15831/diff/5943/Doc/library/http.client.rst File Doc/library/http.client.rst (right): http://bugs.python.org/review/15831/diff/5943/Doc/library/http.client.rst#n… Doc/library/http.client.rst:31: source_address=None) This signature is not too nice, but I'm not sure how it could be improved. Is strict a bool? Maybe using timeout=socket.getdefaulttimeout() might be ok (assuming that's what it uses), or if it's set to None or something similar and then re-set to the actual value you could use None in the signature and describe it in prose later. http://bugs.python.org/review/15831/

1 0

missing explicit reference to importing module.
by Jesse Monroy 03 Sep '12

03 Sep '12

In section: python-2.7.3-docs-html/library/subprocess.html as with many sections it is not mentioned what modules need to be imported. If one was to read all the documentation, then one could presume that using a module means 'import module;'. This is not the case in many, many scripting languages, including PERL. So don't be lazy, add to the top of: python-2.7.3-docs-html/library/subprocess.html REQUIRES: import subprocess;

1 0

Possible typo in py3k glossary for the term "statement"
by Mike Little 01 Sep '12

01 Sep '12

Hi, I'm studying the Python 3.2.3 documentation, and find it to be quite well written. Just one thing I noticed after multiple readings of the Glossary page, http://docs.python.org/py3k/glossary.html: In the entry for the term "statement", http://docs.python.org/py3k/glossary.html#term-statement, it says: = = = statement A statement is part of a suite (a “block” of code). A statement is either an expression or a one of several constructs with a keyword, such as if, while or for. = = = (Please forgive my shaky grasp of logic terminology below. I think I made up some phrases from scratch.) For the sequence of words, "or a one of several constructs" the singular indefinite article "a" is modifying the "singular noun phrase", "one of several constructs", which to me is confusing. The sentence reads more clearly (to me), if we remove the article "a", giving us: "or one of several constructs" If, hypothetically, we had, "A statement is either a foofoo or *a* *list* of several barbars" Then the singular indefinite article modifies a singular noun, "list", and the statement would make sense. Or, if we had, "or a choice of several constructs", it would be syntactically ok, but it would change the term's meaning. I hope there nothing glaringly obvious that I'm overlooking! If so, my apologies, and I would be grateful for any feedback. Thanks, Mike Little

1 0

[issue14042] json.dumps() documentation is slightly incorrect.
by Petri Lehtinen 01 Sep '12

01 Sep '12

Petri Lehtinen added the comment: Fixed, see #13769. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14042> _______________________________________

1 0

[issue14783] Make int() and str() docstrings correct
by Ezio Melotti 01 Sep '12

01 Sep '12

Ezio Melotti added the comment: The issues about "weird" signatures are being discussed on #15831. > However, this issue is about the docstring. Leave it incorrect? > Change it to the hard-to-parse one liner? Change it to a > two-line signature also? For the docstring it's ok to use the double signature too. The description, while not too comprehensive, is understandable. The description of int() in the docs is instead a bit complicated. The content is good, but IMHO it would be more understandable if it was broken down into paragraphs or into a list. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14783> _______________________________________

1 0