[issue20003] Language Ref raise doc misssing from None
New submission from rurpy: In the current (3.3.3 and 3.4dev) Language Reference Manual, the section on the Raise statement fails to mention that the second expression can be None (per PEP-409/415) or the special behavior (suppressing a chained exception) that ensues. Rather it explicitly states it can not be None: ...the second expression must be another exception class or instance... It appears that although the Exceptions section of the Library Reference was updated when PEP-409/415 was implemented, the Language Reference was not. -- assignee: docs@python components: Documentation messages: 206400 nosy: docs@python, rurpy2 priority: normal severity: normal status: open title: Language Ref raise doc misssing from None versions: Python 3.3, Python 3.4 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue20003 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue18584] examples in email.policy doc are fu'd
New submission from rurpy:
In the first example in the documentation for library module email.policy
(http://docs.python.org/3/library/email.policy.html#module-email.policy):
from email import msg_from_binary_file
from email.generator import BytesGenerator
from subprocess import Popen, PIPE
with open('mymsg.txt', 'b') as f:
... msg = msg_from_binary_file(f)
line 1: The module is message_from_binary_file, not msg_from_binary_file
line 4: The mode must be rb, not b.
line 5: Same module (mis-)name problem as line 1.
Then in following example...
import os
with open('converted.txt', 'wb') as f:
... f.write(msg.as_string (policy=msg.policy.clone (linesep=os.linesep))
line 3: Ubnbalanced parens, .as_string() has no policy keyword arg.
Please note I am trying to figure out how to use the email module for the first
time and the above errors are glaring. There may be (probably are) other
errors in the examples and in the text that I am unaware of -- I've made no
attempt to find any others. I suggest that someone familiar with email module
review this page more carefully.
--
assignee: docs@python
components: Documentation
messages: 193852
nosy: docs@python, rurpy2
priority: normal
severity: normal
status: open
title: examples in email.policy doc are fu'd
versions: Python 3.3
___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue18584
___
___
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
rurpy added the comment: I would like to submit the following post made to c.l.p in support of my claim that a cross-reference to the string formatting x format specifier would be desireable in the documentation for the hex() builtin: Newsgroups: comp.lang.python Subject: Re: Integer as raw hex string? Date: Mon, 24 Dec 2012 11:21:15 -0500 https://groups.google.com/group/comp.lang.python/msg/054706d112f6385d?hl=en (In case the link goes away... the post asks how to get the same results as hex() but without the leading 0x.) -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
rurpy added the comment: An ammendment to my proposed doc change. Replace the text (which is unchanged from the current doc), ...the result is a valid Python expression with, ...the result is a valid Python hexinteger literal (see link:[Python Lang Ref, sec 2.4.4. Integer literals]) Python epression in the current doc is way more non-specific than it need be. The result is not any old python expression, it is a very specific type of python expression so the doc should say that. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16677] Hard to find operator precedence in Lang Ref.
New submission from rurpy: Python Language Reference, chapter 6 Expressions. The last section (6.15) of this is titled, Summary. That title is misleading -- it is not really a summary of the Expressions chapter but rather, as the first sentence makes clear, a table of operator precedences. It is not really even a summary of operator precedences since some of the preceeding operator sections don't mention their precedence. And adding to the confusion, none of preceding sections even use the word precedence, referring instead to binding or priority. Operator precedences are something many users frequently look for frequently in a language reference and the lack of an Operator Precedence entry in the ToC makes this section hard to find. There are no index entries for operators/precedence or expressions/order of evaluation. There is an index entry for evaluation order but that points to a different section. At a minimum, this section should have its title changed from Summary to Operator Precedence and get one or more index entries. In other languages operator precedence is often described and indexed under order of evaluation, often as a subindex of expressions. In the Python reference, there is a very short section called, 6.14, Evaluation Order that immediately preceeds the Operator Precedence section. That section and the Operator Precedence section could be effectively combined into a single section. -- assignee: docs@python components: Documentation messages: 177444 nosy: docs@python, rurpy2 priority: normal severity: normal status: open title: Hard to find operator precedence in Lang Ref. type: enhancement versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16677 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
rurpy added the comment: Raymond Hettinger (rhettinger) msg177365: For some of the points, a couple examples will do a better job of explaining hex() that trying to write-out the full code specification in prose. Examples should never substitute for a clear, complete and concise description. Examples serve to illustrate and clarify a description. An example can only describe usage at a single point in the solution space. The prose description (when well written) describes the total solution space. Overly wordy documentation is harder to use than something short that addresses the primary use case. No comments in this issue have suggested providing an overly wordy description. The suggestion was for wording that accurately and concisely describes the behavior of the hex() function. That is what good reference material is supposed to do. Reference documentation should describe the behavior of its subject including any corner cases. Addressing only the primary use case is not sufficient. For addressing the primary use case, supplement the prose with an example. Also, the suggested notes editorialize and venture into the realm of personal coding preferences. That characterization is incorrect. There is no editorializing (if this in reference to the word flexible in the note). It is a fact that string formatting with the %x specifier also converts to hex and offers more control over the output than the hex() function does. A reader interested in the hex() function should be apprised of this alternative. Perhaps there is some other word that you would find more neutral than flexible? There is no venturing into personal coding preferences -- only the factual and appropriate mention of an alternative. One of the cheapest, easiest ways of improving documentation is good cross-referencing to related items. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
New submission from rurpy the second: The documentation of the hex() builtin function is poor. Specifically it does not say (directly) that: 1. The resulting string is prefixed with 0x. 2. Any a-f characters used are lower case. 3. Negative integers are converted by prefixing a minus sign to hex() of the absolute value of the argument. 4. It should have a cross reference to the %x format of the % operator with a note that it is more veratile than the hex() builtin. 5. It should have a cross reference to the way of performing the inverse operation: hex-int I am not a good writer but here is an attempt at improving it: Convert an integer number to a hexadecimal string. The resulting string is prefixed with 0x and any alpha characters a-f are lowercase ascii. Negative integers are converted to hex(abs(x)) prefixed with -. In all cases the result is a valid Python expression. If x is not a Python int object, it has to define an __index__() method that returns an integer. Note: For another more flexible way of converting an integer to hexadecimal see the x and X conversion types in link:[4.7.2 - printf-style String Formatting] and link:[6.1.3.1 - Format Specification Mini-Language] Note: To convert a hexadecimal string to an integer, use link:[int()] with a radix argument of 16. Note: To obtain a hexadecimal string representation for a float, use the link:[float.hex()] method. -- assignee: docs@python components: Documentation messages: 177352 nosy: docs@python, rurpy2 priority: normal severity: normal status: open title: doc for builtin hex() is poor versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12806] argparse: Hybrid help text formatter
rurpy the second added the comment: I happened upon this issue while Googling for a formatter with the behavior described here. I put together a formatter derived from the code submitted by GraylinKim (2011-08-22) and offer it for consideration (though it is missing some things like docstrings and hasn't been tested very thoroughly). As per other comments, it uses additional indentation rather than leading special characters to start a new block. Differently than GraylinKim's code, additional indentation suppresses wrapping or any formatting. However, it would be easy to change that as I hope is obvious from the code. There are two common ways of denoting a block of text (a block being text that should be reformatted as a single unit; aka paragraph) 1. A group of text lines ending with newlines followed by a blank line to denote the end of the block. 2. A single (long) text line where the terminating newline denotes the end of the block (i.e. one line == one block). Both occur in the context of argparse help text: Example of #1: p.add_argument (, help='''block1 block1 block1 block1 block1 block1 block1 block1 block1 block1 block1 block1 block2 block2 block2 block2 block2 block2 block2 block2''') Examples of #2: p.add_argument (, help='block1 block1 block1 block1 ' 'block1 block1 block1 block1 ' 'block1 block1 block1 block1 \n' '' 'block2 block2 block2 block2 ' 'block2 block2 block2 block2 ') p.add_argument (, help='''block1 block1 block1 block1 \ block1 block1 block1 block1 \ block1 block1 block1 block1 \ block2 block2 block2 block2 \ block2 block2 block2 block2 ''') There is no way, when reading lines of text, to tell whether one is reading text in the form of #1 or #2, when one sees a newline. So a formatter really needs to be able to be told which form it is being given. This seems to require two separate formatter classes (though they call common code.) The first form (call it multiline blocked text) is formatted by ParagraphFormatterML. The second form (call it single-line blocked text; I often use form #2a) by ParagraphFormatter. -- nosy: +rurpy2 Added file: http://bugs.python.org/file28091/paraformatter.py ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12806 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12806] argparse: Hybrid help text formatter
rurpy the second added the comment: Additional comment loosely related to the ParagraphFormatter offered in previous comment... [If this is not the right venue -- perhaps a new issue or one of the python mail lists would be better -- please tell me.] I notice that argparse.ArgumentParser requires a class (as opposed to instance) for the formatter_class parameter. A cursory look at argparse gives me the impression that this is only so that ArgumentParser can instantiate the instance with a 'prog' argument. If ArgumentParser accepted a HelpFormatter object (rather than a class), then a user could instantiate a custom formatter class with arguments that would customize its behavior. For example, I would be able to write a single ParagraphFormatter class that was instantiated like formatter = ParagraphFormatter (multiline=False) or formatter = ParagraphFormatter (multiline=True) If one has other requirements, perhaps apply one kind of formatting to description/epilogue text and another to the arguments text, then there is an even greater multiplicity of classes that could be avoided by instantiating a single formatter class with arguments. So why can't ArgumentParser look at the formatter_class value: if it's a class proceed as now, but if it's an class instance, simply set its ._prog attribute and use it as is: def _get_formatter(self): if isinstance (self.formatter_class, type type): return self.formatter_class(prog=self.prog) else: self.formatter_class._prog = prog return self.formatter_class Of course the formatter_class parameter name would then require a little explanation but that's what documentation is for. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12806 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16180] cannot quit pdb when there is a syntax error in the debuggee (must kill it)
rurpy the second added the comment: This continues to be a problem on Python-3.3.0 -- nosy: +rurpy2 versions: +Python 3.3 -Python 3.2 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16180 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue15216] Support setting the encoding on a text stream after creation
Changes by rurpy the second ru...@yahoo.com: -- nosy: +rurpy2 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue15216 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue14973] restore python2 unicode literals in ru strings
New submission from rurpy the second ru...@yahoo.com: PEP 414 proposes restoring the u string prefix (semantically as a noop) to make porting from Python2 easier. I would like to propose that ru-strings also interpret embedded \u unicode literals in the python2 fashion (as a single unicode character) rather than in the python 3.2 fashion (as 6 characters). Many Python2 programs use unicode literals in strings because they can be represented and displayed in source code with the ascii character set. For example, I often write ur \u3000\u3042\t rather than ur あ because the former is much clearer in source code than the latter and does not require the viewer to have a Japanese font installed. However such a string must be manually converted for Python3 because the former string has a very different meaning in Python3 than Python2. The equivalent in Python3 is \u3000\u3042\\t. AFAIK, 2to3 does not fix this. Because there are no longer unicode literals in Python3 raw strings, any string with a unicode literal *has* to be a non-raw string (AFAICT). This means that strings used as regexes, that have a lot of backslashes and have unicode literals, must have the backslashes doubled. Doubling the backslashes in the above example is trivial but it is not trival in more realistic regexes. This was one of the main reasons for having raw strings in Python2 I thought. It is unfortunate that one looses this ability (in the presence of unicode literals) in Python3. When I raised this issue on the Python user's list [*1], Terry Reedy made the suggestion that since the u string prefix was being reintroduced for python 3.3, that having the prefix also restore the python2 unicode literal handling would not introduce any incompatibilties and would greatly increase the ease of porting to Python3 for some programs.[*2] He subsequently raised the issue on the dev list.[*3] An argument might be made that this is an extra feature that would encourage the use of the u-prefix beyond that of easing porting from Python2. Perhaps so but there is currently a hole in Python's capability that is difficult to work around, and I've seen no other proposals to fix it. So it seems to me that the benefits of this proposal greatly outweigh that somewhat purist argument. [*1] http://mail.python.org/pipermail/python-list/2012-May/1292870.html [*2] http://mail.python.org/pipermail/python-list/2012-May/1292887.html [*3] http://mail.python.org/pipermail/python-dev/2012-May/119760.html -- components: Unicode messages: 162025 nosy: ezio.melotti, rurpy2 priority: normal severity: normal status: open title: restore python2 unicode literals in ru strings type: enhancement versions: Python 3.3 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue14973 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1397474] timeit execution enviroment
rurpy the second ru...@yahoo.com added the comment: I find the changes suggested by T Reedy and refined in the patch by E Bendersky an improvement. However, I found the following things confused me when reading it: ...constructor creates a function... the constructor creates a Timeit instance, not a function. There is a method on that instance that is the function but the way it is phrased in like describing the autos coming off a Ford production line as steering wheels. As written, the statement creates an immediate WTF reaction in my mind. ...that executes the *setup* statement... Use of term statement here is confusing as that term already has a well defined meaning in Python docs. One can't syntactically use a statement as a function argument. Only by suspending this confusion and reading further does one discover that statement here means a string containing text of some python code or a callable object. Use of statement (singular) also directly conflicts with following information that states multiple statements are ok. Since the synopsis line already refers to snippets, I think continuing to use that is better (having no preexisting conflicting meanings) than statement. ...default to ``'pass'`... The call summary immediately above makes clear what the default parameter values are. While fine to repeat it in text, it is not high priority information so should be moved to later in the description. ...or newlines as long as they don’t contain multi-line string literals... What is a multi-line string literal? The Language Reference - Lexical Analysis - String Literals section says nothing about multi-line literals. Is it a\nb? Or a b? Both? 'a\nb' actually works. 'a b' doesn't of course but it is it is also clearly not valid python string syntax so I'm not sure that 'multi-line strings need even be mentioned. If it is mentioned then it should be made clear that multi-line string literals are not allowed not because timeit doesn't like them, but because python syntax allows no way to embed them in another string. . ...pre-defined user objects... What does pre-defined mean? Builtin? Imported from stdlib? I would use a more explicit description here. I also think a short explanation of *why* one needs to import program objects in 'setup' makes it a little easier and quicker to understand what one is doing with the import, particularly if one is using timeit somewhere other than __main__.. Thus I suggest expanding that section slightly. Here is my attempt to adjust taking the above observations into account. (Sorry, can't supply a patch since I have slow internet connection and don't have source. Text below is just my hand edit of the + lines in Eli's patch.) Class for timing execution speed of small code snippets. A Timeit instance will contain a function (see :meth:`Timer.timeit`) that executes a snippet of setup code once and then times some number of executions of stmt code . The code snippets, given as arguments *setup* and *stmt* when creating the instance, may be either strings or callable objects. If a string, it may contain a python expression, statement, or multiple statements separated by ; or newlines. Whitespace adhering to the usual Python indentation rules must follow any newlines. If a callable object, (often a function), the object is called with no arguments. Note that the timing overhead is a little larger in this case because of the extra function calls required. The *setup* and *stmt* parameters default to ``'pass'``. The *timer* parameter defaults to a platform-dependent timer function (see the module doc string). When the *setup* and *stmt* are run, they are run in a different namespace than that of the code that calls timeit(). To give *stmt* (whether it is a callable name or code string) access to objects defined in the code that calls timeit, *setup* can import any needed objects. For example, if your code defines function testfunc(), *setup* can contain, ``from __main__ import testfunc``, and code in *stmt* can then call testfunc. To measure the execution time of *stmt*, use the :meth:`Timer.timeit()` method. The :meth:`Timer.repeat()` method is a convenience to call :meth:`Timer.timeit()` multiple times and return a list of results. Changed in version 2.6: The stmt and setup parameters can now also take objects. Notes: Added the line Whitespace adhering... because when using backslash-n in strings it is easy to forget about any needed indentation. Sentence could be deleted if deemed too obvious. There may also be a better way to phrase it; currently it might imply that some whitespace is always neccessary if not enough attention paid to the usual indentation rules phrase. In msg116330 - Eli Bendersky (eli.bendersky) wrote: 1) My tests show that passing the callable instead of the string 'test()' actually takes longer to run
[issue10545] remove or rewrite Using Backslash to Continue Statements anti-idiom
New submission from rurpy the second ru...@yahoo.com: The Python HOWTOs-Idioms and Anti-Idioms has a section Using Backslash to Continue Statements. It says that line continuation is dangerous and gives two reasons. 1. Hard to see a space after the backslash. This is not dangerous as it cause an impossible-to-miss syntax error (as pointed out in the following sentence.) 2. It can cause other subtle errors. It gives a code example purporting to demonstrate this but without saying what the input data to the code is or what the resulting problem is. I spent a while trying to figure it out unsuccessfully. In http://www.mail-archive.com/python-l...@python.org/msg249344.html a number of c.l.p regulars did not figure it out either. I also note related bug http://bugs.python.org/issue7391 that points out that avoinding backslashed continuations with parens is not always possible. So I suggest... 1. If the the given example actually illustrates a real problem, document clearly what it is. This is a reference manual, not a quiz book. 2. If not, then remove that argument. Now the only reason for not using backslashes is that a hard-to-see space after the backslash will cause a syntax error. That is neither dangerous or a strong reason not to do it. An unstated reason is that PEP-8 recommends against it but its recommendation is not absolute and is based only on aethtetics. With no real arguments against using it other than style, it should not be documented as an anti-idiom, recommendations against it should remain only in PEP-8 with other such style guidelines, and this section should be removed from the Anti-Idioms chapter. -- assignee: d...@python components: Documentation messages: 122477 nosy: d...@python, rurpy2 priority: normal severity: normal status: open title: remove or rewrite Using Backslash to Continue Statements anti-idiom ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10545 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
