Mailman 3 September 2012 - docs

[issue15901] multiprocessing sharedctypes Array don't accept strings
by Simon Sept. 10, 2012

Sept. 10, 2012

Changes by Simon <simone.riva(a)bluewin.ch>: ---------- assignee: -> docs@python components: +Documentation -ctypes nosy: +docs@python type: crash -> behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15901> _______________________________________

1 0

Re: [docs] TZ offset description is unclear in docs (issue 8810)
by alexander.belopolsky＠gmail.com Sept. 9, 2012

Sept. 9, 2012

http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst File Doc/library/datetime.rst (right): http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst#newco… Doc/library/datetime.rst:1011: west from UTC. On 2012/09/10 03:24:15, bignose wrote: > You're right that UTC is not a geographical location. It is a region in the > abstract one-dimensional circular space of time zones, and other time zones are > east or west from that region in the space of time zones. This is a novel interpretation, but in this sense that sentence is as useful as saying that integers left of zero are negative and those right of zero are positive. Yes, in some sense the statement is correct, but is not really helpful. In datetime module documentation the East/West terminology is unnecessary. People don't read Python reference manual to figure out whether they live in the East or in the West. What they want to know is what datetime.utcoffset means and it means timedelta that needs to be added to (naive) UTC time to arrive at (naive) local time. They also want to know that the sign of utcoffset() is opposite to the sign of time.timezone. However, saying that time.timezone is positive west of UTC and datetime.utcoffset() is negative west of UTC hides this simple fact behind additional terminology. (By the time one reads about utcoffset() she already forgot what was East/West for time.timezone and does not realize that the convention is opposite.) http://bugs.python.org/review/8810/

1 0

Re: [docs] TZ offset description is unclear in docs (issue 8810)
by ben+python＠benfinney.id.au Sept. 9, 2012

Sept. 9, 2012

Thank you very much for reviewing this patch. http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst File Doc/library/datetime.rst (right): http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst#newco… Doc/library/datetime.rst:1011: west from UTC. On 2012/09/09 19:52:19, sasha wrote: > The sentence above still uses slightly incorrect terminology. UTC is > timescale and not a geographical location. There is no such point or a line > on our planet called UTC, so it is not correct to speak about things east or > west of UTC. You're right that UTC is not a geographical location. It is a region in the abstract one-dimensional circular space of time zones, and other time zones are east or west from that region in the space of time zones. Because those time zones map continuously (though not monotonically) to geographical regions, it is correct and useful to use “east” and “west” to describe the relative positions of time zones in the space of time zones, because those two directions map in both spaces the same way. > If you read UTC here as the Greenwich meridian, then the sentence is > incorrect because there are places west of Greenwich that use negative > offsets. Don't do that, then :-) UTC is not the same as the Greenwich meridian, and this passage doesn't imply that anywhere, so reading them as identical will lead to incorrect conclusions. http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst#newco… Doc/library/datetime.rst:1049: Note that the name is 100% informational – there's no requirement that it On 2012/09/09 19:52:19, sasha wrote: > 100% is redundant here. I would just say "is informational." It's not quite redundant; it carries the implication that there is no purpose *other than* the informational. I think that's the main point of this sentence (which I didn't write, merely moved). Would you prefer “is only informational”? I think that would be better. http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst#newco… Doc/library/datetime.rst:1050: mean anything in particular. For example, ``"GMT"``, ``"UTC"``, ``"-500"``, On 2012/09/09 19:52:19, sasha wrote: > Grammar? "it mean" -> "it means" or "for it to mean" The sentence is correct English grammar, AFAICT; it refers to the action, not the state. “there is no requirement that it mean foo” has the same meaning as “there is no requirement for it to mean foo”, but the former is less clumsy IMO. http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst#newco… Doc/library/datetime.rst:1931: On 2012/09/09 19:52:19, sasha wrote: > Spurious empty line? Checking the source in my tree, yes, it's spurious. That blank line can be deleted without a problem. http://bugs.python.org/review/8810/

1 0

Re: [docs] TZ offset description is unclear in docs (issue 8810)
by alexander.belopolsky＠gmail.com Sept. 9, 2012

Sept. 9, 2012

Reviewers: Nick Coghlan, http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst File Doc/library/datetime.rst (right): http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst#newco… Doc/library/datetime.rst:1011: west from UTC. The sentence above still uses slightly incorrect terminology. UTC is timescale and not a geographical location. There is no such point or a line on our planet called UTC, so it is not correct to speak about things east or west of UTC. If you read UTC here as the Greenwich meridian, then the sentence is incorrect because there are places west of Greenwich that use negative offsets. http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst#newco… Doc/library/datetime.rst:1027: west from UTC. See above. http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst#newco… Doc/library/datetime.rst:1049: Note that the name is 100% informational – there's no requirement that it 100% is redundant here. I would just say "is informational." http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst#newco… Doc/library/datetime.rst:1050: mean anything in particular. For example, ``"GMT"``, ``"UTC"``, ``"-500"``, Grammar? "it mean" -> "it means" or "for it to mean" http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst#newco… Doc/library/datetime.rst:1931: Spurious empty line? Please review this at http://bugs.python.org/review/8810/ Affected files: Doc/library/datetime.rst Lib/datetime.py Modules/_datetimemodule.c

1 0

[issue15724] Add "versionchanged" to memoryview docs
by Stefan Krah Sept. 9, 2012

Sept. 9, 2012

New submission from Stefan Krah: There are a couple of places in the memoryview docs that still need a "versionchanged" tag. Other places might need explanations what exactly has changed. ---------- assignee: docs@python components: Documentation messages: 168563 nosy: docs@python, skrah priority: normal severity: normal stage: needs patch status: open title: Add "versionchanged" to memoryview docs type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15724> _______________________________________

3 6

[issue5088] optparse: inconsistent default value for append actions
by Roundup Robot Sept. 8, 2012

Sept. 8, 2012

Roundup Robot added the comment: New changeset 8c60bb098eff by R David Murray in branch '3.2': #5088: document behavior of optparse defaults with 'append' action. http://hg.python.org/cpython/rev/8c60bb098eff New changeset 0c2bdd2c2032 by R David Murray in branch 'default': Merge #5088: document behavior of optparse defaults with 'append' action. http://hg.python.org/cpython/rev/0c2bdd2c2032 New changeset 79f6d4aff39d by R David Murray in branch '2.7': closes #5088: document behavior of optparse defaults with 'append' action. http://hg.python.org/cpython/rev/79f6d4aff39d ---------- nosy: +python-dev resolution: accepted -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue5088> _______________________________________

1 0

[issue15865] reflect bare star * in function signature documentation
by Chris Jerdonek Sept. 8, 2012

Sept. 8, 2012

New submission from Chris Jerdonek: This issue is to make sure that the bare * in the function signatures of pure Python functions is properly reflected in the documentation. This will bring the signatures in the documentation closer to the signatures that we have in the Python code -- a goal articulated by Ezio in a comment to issue 15831. For example, configparser.RawConfigParser() has this function signature: def __init__(self, defaults=None, dict_type=_default_dict, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=DEFAULTSECT, interpolation=_UNSET): But its documentation has no *: class configparser.RawConfigParser(defaults=None, dict_type=collections.OrderedDict, allow_no_value=False, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configaparser.DEFAULTSECT, interpolation=None) (from http://docs.python.org/dev/library/configparser.html#configparser.RawConfig… ) >From a search of the code, there are about 60 occurrences of a bare * in the signature of a pure Python function (not all of which will need to be updated). ---------- assignee: docs@python components: Documentation keywords: easy messages: 169850 nosy: cjerdonek, docs@python, ezio.melotti priority: normal severity: normal status: open title: reflect bare star * in function signature documentation type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15865> _______________________________________

5 10

[issue10224] Build 3.x documentation using python3.x
by Brett Cannon Sept. 8, 2012

Sept. 8, 2012

Changes by Brett Cannon <brett(a)python.org>: ---------- nosy: +brett.cannon _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10224> _______________________________________

1 0

[issue15520] Document datetime.timestamp() in 3.3 What's New
by Dirkjan Ochtman Sept. 6, 2012

Sept. 6, 2012

New submission from Dirkjan Ochtman: It seems nice if datetime.timestamp() would be mentioned in the What's New. Does that seem acceptable? I'm happy to whip up a patch. ---------- assignee: docs@python components: Documentation messages: 167096 nosy: djc, docs@python priority: normal severity: normal status: open title: Document datetime.timestamp() in 3.3 What's New versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15520> _______________________________________

4 3

Bug/typo
by Morten Beuchert Sept. 6, 2012

Sept. 6, 2012

Hi, I found a bug/typo in the Python Tutorial (version 2.7.3), Chapter 3.1.2. Quote: hello = r"This is a rather long string containing\n\several lines of text much as you would do in C." print hello Notice the character 'r' that's not supposed to be there. Best regards, Morten Beuchert

1 1