Mailman 3 May 2013 - docs

[issue17583] IDLE HOWTO
by Amit Saha May 9, 2013

May 9, 2013

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 May 8, 2013

May 8, 2013

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':… [View More]

1 0

Possible documentation bug
by Pedro G. Acevedo May 8, 2013

May 8, 2013

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 … [View More]

1 0

Re: [docs] Improve the "introduction" page of the tutorial (issue 14097)
by rdmurray＠bitdance.com May 8, 2013

May 8, 2013

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 > &… [View More]gt; 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/ [View Less]

1 0

Re: [docs] Different documentation for identical methods (issue 17858)
by rdmurray＠bitdance.com May 8, 2013

May 8, 2013

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/… [View More]

1 0

[issue14191] argparse doesn't allow optionals within positionals
by Glenn Linderman May 7, 2013

May 7, 2013

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 … [View More]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> _______________________________________ [View Less]

1 0

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

May 7, 2013

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 May 7, 2013

May 7, 2013

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.… [View More]

1 0

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

May 7, 2013

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 May 7, 2013

May 7, 2013

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 … [View More]

4 4