Mailman 3 January 2011 - docs

[issue7229] Manual entry for time.daylight can be misleading
by Georg Brandl 11 Jan '11

11 Jan '11

Georg Brandl <georg(a)python.org> added the comment: It seems to me that the quoted function from bzr def local_time_offset(t=None): """Return offset of local zone from GMT, either at present or at time t.""" # python2.3 localtime() can't take None if t is None: t = time.time() if time.localtime(t).tm_isdst and time.daylight: return -time.altzone else: return -time.timezone would be very helpful to add to the `time` module docs as an example. I have to agree with the OP that the current state of the docs is not as clear as it could be. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue7229> _______________________________________

3 2

[issue1397474] timeit execution enviroment
by rurpy the second 11 Jan '11

11 Jan '11

rurpy the second <rurpy(a)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. Should the documentation promise that? I take your word that it also takes longer than running the function's code directly (outside a function) The original "Changed in version 2.6" section said | Note that the timing overhead is a little larger in this case | [callable objects] because of the extra function calls. Here, "the other case" is presumably the plain code but could also be a string function call (e.g. "test()") so I suppose it is still vacuously true in that case. Accordingly I reused the statement above in in my suggested changes. Perhaps all three cases (string code, string function call, callable object) should be distinguished further and compared re overhead? ---------- nosy: +rurpy2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue1397474> _______________________________________

1 0

[issue10875] Update Regular Expression HOWTO
by Terry J. Reedy 11 Jan '11

11 Jan '11

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: 0. Does 'Release 0.05' at the top have any useful current meaning? or could it be deleted? 1. Introduction: The history paragraph "The re module was added in Python 1.5, and provides Perl-style regular expression patterns. Earlier versions of Python came with the regex module, which provided Emacs-style patterns. The regex module was removed completely in Python 2.5." might be eliminated in 3.x, or at least the irrelevant-for-py3 reference to regex. This is a policy decision. 2. Performing matches: "If you have Tkinter available, you may also want to look at Tools/scripts/redemo.py," Change 'Tkinter' to 'tkinter' and make it a module reference. In link, change 'scripts' to 'demo' as redemo.py got moved. "Phil Schwartz’s Kodos is also an interactive tool for developing and testing RE patterns." Add the url '(http://kodos.sourceforge.net/)' to the text so that Windows help users can copy and paste it into a browser. (This should be a general policy.) "Python 2.2.2 (#1, Feb 10 2003, 12:57:01)" delete <_sre.SRE_Match object at 80c4f68> This is correctly updated (for late 2.x and 3.x) "<re.MatchObject instance at 80c9650>" (7 like this) Globally replace 're.MatchObject instance' with '_sre.SRE_Match object' 3. Footnote "[1] Introduced in Python 2.2.2." remove for 3.x here and wherever footnote reference is in the text. 4. "Not Using re.VERBOSE" This section is about *using* re.VERBOSE and the benefit thereof, not about not using it. I recommend deleting 'Not' as it gives the impression that the section is a warning about not using, the opposite of the intent. 5. Code example output and doctest: I ran doctest.testfile("C:/programs/PyDev/py32/Doc/howto/regex.rst", module_relative = False) After the 're...' to '_sre...' substitution above, all 11 failures would be due to 'at 0x#######' address mismatches. I believe changing all 11 addresses to '0x...' (I took this from the doctest doc) would both fix the failures and remove irrelevant detail for human readers. The other 87 examples all passed ;-!. Is there any current doctest-related markup that should be added? ---------- assignee: docs@python components: Documentation messages: 125855 nosy: akuchling, docs@python, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Update Regular Expression HOWTO versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10875> _______________________________________

4 19

[issue7229] Manual entry for time.daylight can be misleading
by Tomas Kubes 11 Jan '11

11 Jan '11

Tomas Kubes <mr_napik(a)centrum.cz> added the comment: > I think you are confusing the purposes of a reference manual with that of a tutorial or an FAQ collection. There is a fine line between them. Even though reference manual should not be a substitute for a tutorial, I still believe it should try to clarify potential confusions - after all it is the less experienced users who will most likely spend their time with it looking for something. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue7229> _______________________________________

1 0

[issue10885] multiprocessing docs
by Ross Lagerwall 11 Jan '11

11 Jan '11

Changes by Ross Lagerwall <rosslagerwall(a)gmail.com>: ---------- assignee: -> docs@python components: +Documentation nosy: +docs@python _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10885> _______________________________________

1 0

[issue7229] Manual entry for time.daylight can be misleading
by Tomas Kubes 11 Jan '11

11 Jan '11

Tomas Kubes <mr_napik(a)centrum.cz> added the comment: >>why do you think someone reading about time.daylight actually wants to "check if DST is currently active"? If you are not familiar with the cryptic names of POSIX but live in normal world, time.daylight sounds like a quite probable place where to check if the daylight savings are active. That's why I think the help text should explicitely note it has other meaning. You should try to think like a person that does not have any background knowledge of underlying libraries but just looks through the time library trying to solve the question - how can I check if my machine uses daylight savings now. Regards Tomas ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue7229> _______________________________________

2 1

[issue7229] Manual entry for time.daylight can be misleading
by Brian Curtin 11 Jan '11

11 Jan '11

Changes by Brian Curtin <curtin(a)acm.org>: ---------- nosy: -brian.curtin _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue7229> _______________________________________

1 0

[issue7229] Manual entry for time.daylight can be misleading
by Tomas Kubes 11 Jan '11

11 Jan '11

Tomas Kubes <mr_napik(a)centrum.cz> added the comment: Hello, I find this version very clear. Thanks Tomas ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue7229> _______________________________________

1 0

[issue7229] Manual entry for time.daylight can be misleading
by Tomas Kubes 11 Jan '11

11 Jan '11

Tomas Kubes <mr_napik(a)centrum.cz> added the comment: I am sorry, but as an original initiator of the the issue I find the argumentation of Alexander Belopolsky vastly ridiculous. Are you really seriously convinced that an average person responsible for Python application development and maintenance would be aware of a necessity to look for an ANSI C documentation to find a description and definitions of time functions? You sound like Marie Antoinette who replied to peasants complaining the they do not have any bread to eat that they should eat brioches instead. Maybe in the context of the “royal programmers family” documentation to ANSI C is wildly known and even memorized, but I do insist that Python documentation should be accessible and understandable even to ordinary peasants of the computer kingdom. And I keep my case that the current description might trick programmers to think that it holds information whether the summer time currently applies rather than just plain information about current time zone being able to use summer time. Regards Tomas ---------- status: pending -> open _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue7229> _______________________________________

1 0

[issue7229] Manual entry for time.daylight can be misleading
by Alexander Belopolsky 11 Jan '11

11 Jan '11

Alexander Belopolsky <belopolsky(a)users.sourceforge.net> added the comment: I am going to reject this. None of the proposed changes seem to be better than the current documentation. The time.daylight variable has the same meaning as eponymous C variable defined in time.h header. The latter is described in widely available and well known C and POSIX standards. Users that find Python manual description confusing or incomplete can easily find clarifications or details in other sources. ---------- status: open -> pending _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue7229> _______________________________________

1 0

docs January 2011