On Mon, Jul 19, 2010 at 7:21 PM, Alexander Belopolsky <report@bugs.python.org> wrote:

I suggest the following wording for time.timezone description:

time.timezone: The number of seconds one must add to the local time to arrive at UTC.

Makes sense. I can't see any other real explanation for -7200 value if I am in +2 UTC timezone.

Similarly, tzinfo.utcoffset() can be defined as "Returns timedelta one must add to UTC to arrive at local time."

I believe the correct convention is "Return timedelta...". Another concern - if UTC is 0 reference point then there is no reason to add something to it - you just can say - "Return timedelta equal to local UTC offset."

Tim Peters <tim.peters@gmail.com> added the comment: FYI, I like the change. As I recall it, the current wording was just to avoid saying "ahead of UTC" or "behind UTC" (which was the original wording). Technically pure or not, I never saw anyone get truly confused by "East of UTC" or "West of UTC", but I fully that what people really want to know is what to do with the thing (add or subtract it). ---------- nosy: +tim_one _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

anatoly techtonik <techtonik@gmail.com> added the comment:

Documenting utcoffset() as "Return timedelta equal to local UTC offset." is almost circular.  It does not explain whether it has to be added or subtracted from UTC to arrive at local time.

Ok. Sold.

...

I believe the correct convention is "Return timedelta...".

This is handled inconsistently in the documentation; I'm hoping the current maintainers reinforce the "Returns ..." structure.  The documentation is descriptive, not an external specification.

http://www.python.org/dev/peps/pep-0257/#one-line-docstrings I've took the convention from here. I thought docs are generated from docstrings. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

Alexander Belopolsky <belopolsky@users.sourceforge.net> added the comment: On Tue, Jul 20, 2010 at 11:39 AM, Tim Peters <report@bugs.python.org> wrote:

..  As I recall it, the current wording was just to avoid saying "ahead of UTC" or "behind UTC" (which was the original wording).

Interesting. I actually like the original wording better. For me, "my watch is 6 hours behind UTC" makes it clear that when the Big Ben clock shows tea time (18:00), my watch displays noon (17:00 - 6:00 = 12:00.) I wonder if east/west is somehow more natural for native speakers of English. I would really like to hear more from the international audience. When it comes to measuring time there are many interesting traditions that don't translate well between nations. For example, I've heard that in the Far East, the future is considered to be behind because you can see the past but you cannot see the future. If this is the notion that you are used to, time being ahead or behind can be truly confusing. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

Alexander Belopolsky <belopolsky@users.sourceforge.net> added the comment: On Tue, Jul 20, 2010 at 12:08 PM, anatoly techtonik <report@bugs.python.org> wrote: ..

Ok. Sold.

Good. All we need now is just a patch. :-) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

Henrique Bastos <henrique@bastos.net> added the comment: Here goes a patch to replace east/west references on datetime documentation. As spoken with fdrake we think the datetime documentation could be improved extracting the timezone subclassing details to specific section. We'll be filling a new issue for that patch. ---------- nosy: +Rodolpho.Eckhardt, henriquebastos _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

Alexander Belopolsky <belopolsky@users.sourceforge.net> added the comment: LGTM ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

Alexander Belopolsky <belopolsky@users.sourceforge.net> added the comment: On the second reading, I have a few issues with the patch. 1. Please run makepatcheck. There are whitespace issues in datetime.rst. 2. In docstrings, you remove the information about the sign. I would not mind leaving docstrings the way they are. Otherwise, please add a short sentence explaining the sign of utcoffset and dst. 3. "This represents the offset in minutes that must be added to the local time zone to follow DST rules." This unclear. DST offset is added to the "standard time", not "local time zone". (I am not sure if "standard time" is defined in the manual, though.) Also, "in minutes" is not necessary - timedelta carries the units. You can add that only offsets that are multiples of a minute are supported. ---------- stage: commit review -> patch review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

Rodrigo Bernardo Pimentel <rbp@isnomore.net> added the comment: 1. Done (it's on the patch I'm uploading). Sorry. 3. Ok, we've rewritten that sentence. As Henrique mentioned, we're working on a larger patch to make datetime documentation clearer, and we can include a definition of "standard time" there. 2. I assume you're talking about sentences like "(negative for west of UTC)". We removed that wording because it inevitably leads to associating UTC with a geographical reference. Even if we disregard that, it's not true that "utcoffset is negative west of UTC", since it will we zero for for UTC-1 (and even +1 for places physically "west of UTC" but at timezone UTC+0) when DST is effective. It seems that any sentence we add to that effect will be simply restating the definitions of UTC, timezones and DST (and their mathematical relationships). That is, "utcoffset will be negative when dt.tzinfo + dst() is negative". Perhaps we could include a more detailed discusion about the sign of utcoffset() on the larger doc patch I've mentioned? Or do you have any suggestions? ---------- Added file: http://bugs.python.org/file19709/datetime_doc_remove_east_west_2.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

Mark Lawrence added the comment: Well, we have a patch and it's been discussed here and on #7229, so can we take this forward? ---------- nosy: +BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

Changes by Alexander Belopolsky <alexander.belopolsky@gmail.com>: ---------- dependencies: +Don't use east/west of UTC in date/time documentation _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

Martin Panter added the comment: Assuming you meant Issue 8810, yes these patches would collide with each other. I am yet to look at the patches, but I gess they should be merged. ---------- dependencies: +TZ offset description is unclear in docs -Don't use east/west of UTC in date/time documentation nosy: +martin.panter _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

Change by Paul Ganssle <p.ganssle@gmail.com>: ---------- nosy: +p-ganssle _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue9305> _______________________________________

Ajay Mahato <ajjayymahato@gmail.com> added the comment: I am taking up this issue. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue9305> _______________________________________

Change by Murali Ravipudi <murali.ravipudi@gmail.com>: ---------- nosy: +Murali Ravipudi _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue9305> _______________________________________