Mailman 3 May 2013 - docs

[issue17583] IDLE HOWTO
by Amit Saha 09 May '13

09 May '13

Amit Saha added the comment: Hello, I just wanted to check if I should attach the image files separately and submit the text as a diff? Thanks. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17583> _______________________________________

1 0

Documentation Bug: PythonHosted.org: feedparser 5.1.3 : HTTP Features
by Pearce, Lyall 08 May '13

08 May '13

I hope this is the right place to send this... http://pythonhosted.org/feedparser/http-other.html#sending-custom-http-requ… >>> import feedparser >>> d = feedparser.parse('http://feedparser.org/docs/examples/atom03.xml', extra_headers={'Cache-control': 'max-age=0'}) Should be >>> import feedparser >>> d = feedparser.parse('http://feedparser.org/docs/examples/atom03.xml', request_headers={'Cache-control': 'max-age=0'}) Lyall Pearce Application Services Lyall.Pearce(a)HP.com<mailto:Lyall.Pearce@HP.com> T +61 8 8464 1356<tel:+61%208%208464%201356> M+61 419 811 701<tel:+61%20419%20811%20701> Hewlett-Packard Enterprise Services - South Pacific<http://hp.com/> Level 10, 108 North Terrace Adelaide, South Australia, 5000<http://maps.google.com/maps?q=106+North+Terrace,+Adelaide,+South+Australia,…> Australia<http://maps.google.com/maps?q=106+North+Terrace,+Adelaide,+South+Australia,…> Timezone: ACDT<http://timeanddate.com/library/abbreviations/timezones/au/cdt.html> +9:30 [Description: HP logo] Please print thoughtfully

1 0

Possible documentation bug
by Pedro G. Acevedo 08 May '13

08 May '13

Hello, I'm not sure if this is a bug per se, but it can throw you off so I would think it's at least counter-intuitive. On IE 8 (have not tested on other browsers), the Python version in the drop-down at the top of a documentation page does not match the version in the URL, which is the real version that I'm browsing. This happens if you have used the drop-down to switch versions. To reproduce: 1. Go to http://docs.python.org/3/library/index.html 2. Use the drop-down at the top of the page to switch to version 2.6. 3. See that the URL now reads 2.6, but the drop-down continues to display 3.4. This could make you think that you're browsing the 3.4 documentation when in reality you aren't. The string "(3.4)" is found nowhere in the page's source code so I assume it's being generated by an imported Javascript file. If this is a regular <select> element, then I assume the correct version could be displayed by adding the "selected" attribute to the <option> element of whichever version is currently being browsed. Cheers. Pedro G. Acevedo

1 0

Re: [docs] Improve the "introduction" page of the tutorial (issue 14097)
by rdmurray＠bitdance.com 08 May '13

08 May '13

On 2013/05/01 22:50:41, ezio.melotti wrote: > http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst… > Doc/tutorial/introduction.rst:110: Complex numbers are also supported; imaginary > numbers are written with a suffix > On 2013/05/01 18:30:31, r.david.murray wrote: > > The problem with completely omitting this is that the 'j' notation is a > special > > feature of the syntax, unlike Decimal or Fraction, which are "just" > specialized > > classes. > > This could go in a footnote. Because it is part of the language syntax I think there should be at least a one line mention in the main text. It could then have a 'for more information' link. > http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst… > Doc/tutorial/introduction.rst:551: object! We'll come back to *object > semantics* later. > On 2013/05/01 18:30:31, r.david.murray wrote: > > On 2013/04/02 01:19:18, ezio.melotti wrote: > > > This is a fundamental concept, and this lighthearted introduction only > serves > > to > > > add more confusion IMHO. > > > I removed the example for now, but this should be covered at a later point. > > > > I think maybe you could (should) cover it at an *earlier* point, in the > > discussion of [:] and what makes it a copy. > > I think this should be presented in the second page, so that people can first > digest what they learned here. > If we put this at the end of the page they might end up reading it while their > brain is still overheating from the amount of information they just learned and > risk to misunderstand it. That seems fine, if you also move the [:] example to that page. > http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst… > Doc/tutorial/introduction.rst:76: > On 2013/05/01 18:30:31, r.david.murray wrote: > > I know this is early in the tutorial, but should divmod be mentioned here? > > Maybe in a footnote, functions haven't even be introduced yet, and divmod() is > not really common. Probably even a footnote isn't appropriate. > http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst… > Doc/tutorial/introduction.rst:77: With Python is also possible to use the ``**`` > operator to calculate powers:: > On 2013/05/01 18:30:31, r.david.murray wrote: > > "With Python it is also", but I'm not sure why "also"? It doesn't seem to be > > related to the discussion of division. > > > > Most of the other languages only provide the 4 basic operations, but Python also > provides **. Without having created that context for 'also' in the text, I think it would be better to just drop it. > > The other problem with introducing ** here is that any discussion of ** should > > include a discussion of operator precedence and why -1**2 == -1. > > That's too advanced/specific for now, I think it could be explained somewhere > else if necessary (or maybe in another footnote?). A footnote would be fine. > http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst… > Doc/tutorial/introduction.rst:92: If a variable is not "defined" (assigned a > value), trying to use it will > On 2013/05/01 18:30:31, r.david.murray wrote: > > I really don't like the use of the word 'defined' here. I'd prefer something > > like "A name must be assigned an initial value before it can be used. Trying > to > > use a name that hasn't been assigned a value will give you an error:" > > That doesn't sound too well to me. What about it doesn't sound good? "defined" just feels *wrong* to me for Python. > http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst… > Doc/tutorial/introduction.rst:137: double quotes (``"..."``) with the same > result. ``\`` can be used to escape > On 2013/05/01 18:30:31, r.david.murray wrote: > > I'm not sure "with the same result" is at all clear, here. I think it would > be > > better to just say "They can be enclosed in either single quotes (``'...''') > or > > double quotes (``"..."``)" and then have the next sentence read "``\`` can be > > used to escape a quote character in a string that is surrounded by that same > > type of quote character::" which the examples with then make concrete. > > "with the same result" is supposed to indicate that apart from the (obvious) > differences regarding the escaping of \' and \", they behave the same. In other > languages there are differences between the two -- e.g. chars like \n and \t and > variable interpolation only work with one kind of quotes. How about putting that note that other languages do make distinctions in a footnote? (Or as a separate sentence.) > http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst… > Doc/tutorial/introduction.rst:141: 'spam eggs' > On 2013/05/01 18:30:31, r.david.murray wrote: > > I don't think the comments add any value. > > They are useful for people who read only the examples, and to link part of the > description with the examples. OK. I don't like them personally, but I can deal with that as personal preference. > http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst… > Doc/tutorial/introduction.rst:153: By default, the interpreter encloses the > string output in quotes and escapes special characters with backslashes. The > string is enclosed in > On 2013/05/01 18:30:31, r.david.murray wrote: > > I would narrow this further, and say "At the command prompt, ...", or "In the > > interactive interpreter" (shell?) since there really is no "default". > > s/By default/In the interactive interpreter/ SGTM. > > > I also > > would prefer to retain the sense of the 'in the same way' phrase...perhaps "in > a > > way that they could be typed at the input prompt"? > > "In the same way" is not totally accurate, because "s might end up replaced with > 's or the other way around. That's why my suggested replacement uses the word "could" :) > http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst… > Doc/tutorial/introduction.rst:180: triple-quotes: ``"""..."""`` or > ``'''...'''``. End of lines are automatically > On 2013/05/01 18:30:31, r.david.murray wrote: > > "End of lines are automatically..." This is confusing without the preceding > > example of escaping the ends of lines in a single quoted string. > > This is presented in the next example though. > The idea is that first I introduce """...""" and \ and explain what they do, > then I show an example and its output, pointing out what """...""" and \ did > there. Right, and I'm saying that I don't think that exposition works as well. > > That section > > should be retained, IMO. Despite the fact that it is not "best practice" to > > write code that way, pedagogically it explains the concepts better. > > The problem with that is that if people see it, it's likely they are going to > copy it and use it in their code. > Even if \ actually works even outside strings, the examples shows one of the > very few places where it's ok using it (IMHO). The text linking the two examples can say that the second one is the better way to do it. > http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst… > Doc/tutorial/introduction.rst:211: This only works with two literals though, not > with variables:: > On 2013/05/01 18:30:31, r.david.murray wrote: > > "arbitrary string expressions" is more correct here than "variables". > > It's more correct but less clear. "variables or expressions" might be OK > though. That sounds fine. > http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst… > Doc/tutorial/introduction.rst:213: >>> prefix = 'Py' > On 2013/05/01 18:30:31, r.david.murray wrote: > > I think you should include an expression example as well, such as showing that > > the multiplication example doesn't work with string concatenation. (But you > > should reverse it, 'un' *3 'ium') > > I preferred to show only one example, because each "failing" example takes 5 > more line, and having two tracebacks one after the other might be confusing. You could use the '...' notation and only show the SyntaxError. That should be typographically clear even to a beginner. > http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst… > Doc/tutorial/introduction.rst:367: items of different types, but usually the > items all have the same type. :: > On 2013/05/01 18:30:31, r.david.murray wrote: > > You are losing something here by omitting the example of items of different > > type. How about having both examples, and prefacing the second one with, > > "Normally, however, lists elements will all be of the same type"? > > I think it's not necessary, and it's better to keep the tutorial short. Well, I still think you are losing something valuable, but I won't block on it :) > http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst… > Doc/tutorial/introduction.rst:384: means that the following slice returns a new > (shallow) copy of the list:: > On 2013/05/01 18:30:31, r.david.murray wrote: > > We probably ought to link this to "shallow copy" in the glossary...and make an > > entry for it :) > > OK (was there an issue for this?) I don't think so. http://bugs.python.org/review/14097/

1 0

Re: [docs] Different documentation for identical methods (issue 17858)
by rdmurray＠bitdance.com 08 May '13

08 May '13

http://bugs.python.org/review/17858/diff/8073/Doc/library/threading.rst File Doc/library/threading.rst (right): http://bugs.python.org/review/17858/diff/8073/Doc/library/threading.rst#new… Doc/library/threading.rst:373: reason for existence). I don't think this parenthetical is completely accurate. For a Lock, even the same thread cannot acquire it (that's why RLock was later added). Probably just drop the parenthetical, I don't think it really adds anything helpful. http://bugs.python.org/review/17858/diff/8073/Doc/library/threading.rst#new… Doc/library/threading.rst:375: If *blocking* is ``False``, the lock is acquired only if it can be This wording is an improvement in general, but I'm not sure a new reader would know what "the lock is acquired only if it can be acquired" means. The original had "immediately without waiting" in there as well, which while a bit redundant was also a bit more comprehensible. Perhaps a better wording than either would be "If *blocking* is ``False`` the call returns immediately; the return value indicates whether or not the lock was acquired." Then this paragraph can be re-combined with the preceding one, since that one describes the behavior when blocking is True. http://bugs.python.org/review/17858/diff/8073/Doc/library/threading.rst#new… Doc/library/threading.rst:379: specifies the maximum wait time in seconds before returning. A negative I think it would be good to add "; the return value indicates whether or not the lock was acquired." here as well. http://bugs.python.org/review/17858/diff/8073/Doc/library/threading.rst#new… Doc/library/threading.rst:380: *timeout* argument specifies an unbounded wait. You cannot specify This immediately raises the question of what a 0 timeout means (and yes I see that the original does not answer that question). Seems like we could have avoided having a 'blocking' keyword if we'd had timeout from the start instead :) So, a negative timeout is the same as not specifying a timeout and also specifying blocking=True, and a zero timeout is the same as not specifying a timeout and also specifying blocking=False. We're stuck with the API, but as long as we are perhaps we should document it that way? http://bugs.python.org/review/17858/

1 0

[issue14191] argparse doesn't allow optionals within positionals
by Glenn Linderman 07 May '13

07 May '13

Glenn Linderman added the comment: Paul, thanks for your continued work. I had reworked your prior patch into a subclass of Argument Parser, and tweaking the code to get parse_intermixed_args to adjust the behaviors I had reported. Now substituting exactly your more flexible new code into my subclass from your latest test_intermixed.py (you should delete your old patches), I can quickly confirm that it works with my applications that used to use my wrapper class, and expect and use intermixed functionality. I also read through all your code and comments and it looks good to me. Regarding parse_fallback_args, I do not see documentation for it. If that is intentional, you might want to add comments in the code regarding its use for testing only... and might want to rename it to _parse_fallback_args. I personally don't see a lot of value to the function, or the new parameter; tests for parse_intermixed_args and parse_known_intermixed_args should be (and have been, thanks) added to the tests for argparse, and should suffice for testing. In non-test code, I see no benefit: either the user uses features that are incompatible with parse_intermixed_args, and thus uses the other features of argparse, or the user, for compatibility reasons, needs to use parse_intermixed_args, and thus is prevented from successfully using the incompatible features. If I'm missing some benefit of parse_fallback_args, it should be explained in either the documentation or the comments. Regarding the terminology: both intermixed and interspersed would be correct English words to describe the use case. So would intermingled :) Because Stephen "blessed" intermixed, and because it is used by getopt documentation (getopt has not been deprecated, optparse has), it seems to be the best term to use. Should optparse someday be removed, along with its documentation, the use of the term interspersed would also disappear, leaving more consistency in terminology. Alternative: Because optparse uses "interspersed" in an API, we cannot fix it to use "intermixed". However, we could fix the uses of "intermixed" to be "interspersed" prior to or at the time of accepting your patch to argparse... afterwards, it would be too late. Personally, I see no problem with the use of both terms in the documentation, and "intermixed" is the shortest, so I have a slight preference for that. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14191> _______________________________________

1 0

[issue17714] str.encode('base64') add trailing new line character. It is not documented.
by Roundup Robot 07 May '13

07 May '13

Roundup Robot added the comment: New changeset cbb23e40e0d7 by Ezio Melotti in branch '3.3': #17714: document that the base64 codec adds a trailing newline. http://hg.python.org/cpython/rev/cbb23e40e0d7 New changeset b3e1be1493a5 by Ezio Melotti in branch 'default': #17714: merge with 3.3. http://hg.python.org/cpython/rev/b3e1be1493a5 ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17714> _______________________________________

1 0

[issue17714] str.encode('base64') add trailing new line character. It is not documented.
by Ezio Melotti 07 May '13

07 May '13

Ezio Melotti added the comment: The str.encode() doc is the wrong place where to document this, since the '\n' is added only for the base64 codec. I added a note about this in the codecs docs[0]. [0]: http://docs.python.org/2/library/codecs.html#standard-encodings ---------- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17714> _______________________________________

1 0

[issue17714] str.encode('base64') add trailing new line character. It is not documented.
by Roundup Robot 07 May '13

07 May '13

Roundup Robot added the comment: New changeset 8b764c3521fa by Ezio Melotti in branch '2.7': #17714: document that the base64 codec adds a trailing newline. http://hg.python.org/cpython/rev/8b764c3521fa ---------- nosy: +python-dev _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17714> _______________________________________

1 0

[issue17871] Wrong signature of TextTestRunner's init function
by Piotr Dobrogost 06 May '13

06 May '13

New submission from Piotr Dobrogost: TextTestRunner's init as of 3.3.1 has (http://hg.python.org/cpython/file/d9893d13c628/Lib/unittest/runner.py#l128) the following parameters: stream, descriptions, verbosity, failfast, buffer, resultclass, warnings whereas docs (http://docs.python.org/3.3/library/unittest.html?highlight=unittest#loading…) show only the following parameters: stream, descriptions, verbosity, runnerclass, warnings 'Failfast' and 'buffer' parameters are missing in the docs and there's 'runnerclass' parameter instead of 'resultclass' parameter. ---------- assignee: docs@python components: Documentation messages: 188104 nosy: docs@python, ezio.melotti, michael.foord, piotr.dobrogost priority: normal severity: normal status: open title: Wrong signature of TextTestRunner's init function versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17871> _______________________________________

4 4