Skip to content

Commit

Permalink
bpo-30699: Improve example on datetime tzinfo instances (GH-4290)
Browse files Browse the repository at this point in the history 
* Improve example on tzinfo instances

Move from GMTX to TZX when naming the classes, as GMT1 might be rather
confusing as seen in the reported issue.
In addition, move to UTC over GMT and improve the tzname implementation.

* Simplify datetime with tzinfo example

Move the example in the documentation to just use timezone.utc and a
user defined Kabul timezone rather than having two user defined
timezones with DST.

Kabul timezone is still interesting as it changes its offset but not
based on DST. This is more accurate as the previous example was missing
information about the fold attribute. Additionally, implementing the fold
attribute was rather complex and probably not relevant enough for the
section "datetime with tzinfo".
  • Loading branch information
@mariocj89 @vstinner
mariocj89 authored and vstinner committed Jun 4, 2019
1 parent ca612a9 commit f0b5ae4
Showing 1 changed file with 60 additions and 51 deletions.
111 changes: 60 additions & 51 deletions Doc/library/datetime.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1365,56 +1365,64 @@ Examples of working with datetime objects:

Using datetime with tzinfo:

>>> from datetime import timedelta, datetime, tzinfo
>>> class GMT1(tzinfo):
>>> from datetime import timedelta, datetime, tzinfo, timezone
>>> class KabulTz(tzinfo):
... # Kabul used +4 until 1945, when they moved to +4:30
... UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)
... def utcoffset(self, dt):
... return timedelta(hours=1) + self.dst(dt)
... def dst(self, dt):
... # DST starts last Sunday in March
... d = datetime(dt.year, 4, 1) # ends last Sunday in October
... self.dston = d - timedelta(days=d.weekday() + 1)
... d = datetime(dt.year, 11, 1)
... self.dstoff = d - timedelta(days=d.weekday() + 1)
... if self.dston <= dt.replace(tzinfo=None) < self.dstoff:
... return timedelta(hours=1)
... if dt.year < 1945:
... return timedelta(hours=4)
... elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, 30):
... # If dt falls in the imaginary range, use fold to decide how
... # to resolve. See PEP495
... return timedelta(hours=4, minutes=(30 if dt.fold else 0))
... else:
... return timedelta(0)
... def tzname(self,dt):
... return "GMT +1"
... return timedelta(hours=4, minutes=30)
...
... def fromutc(self, dt):
... # A custom implementation is required for fromutc as
... # the input to this function is a datetime with utc values
... # but with a tzinfo set to self
... # See datetime.astimezone or fromtimestamp
...
... # Follow same validations as in datetime.tzinfo
... if not isinstance(dt, datetime):
... raise TypeError("fromutc() requires a datetime argument")
... if dt.tzinfo is not self:
... raise ValueError("dt.tzinfo is not self")
...
... if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE:
... return dt + timedelta(hours=4, minutes=30)
... else:
... return dt + timedelta(hours=4)
...
>>> class GMT2(tzinfo):
... def utcoffset(self, dt):
... return timedelta(hours=2) + self.dst(dt)
... def dst(self, dt):
... d = datetime(dt.year, 4, 1)
... self.dston = d - timedelta(days=d.weekday() + 1)
... d = datetime(dt.year, 11, 1)
... self.dstoff = d - timedelta(days=d.weekday() + 1)
... if self.dston <= dt.replace(tzinfo=None) < self.dstoff:
... return timedelta(hours=1)
... return timedelta(0)
...
... def tzname(self, dt):
... if dt >= self.UTC_MOVE_DATE:
... return "+04:30"
... else:
... return timedelta(0)
... def tzname(self,dt):
... return "GMT +2"
... return "+04"
...
>>> gmt1 = GMT1()
>>> # Daylight Saving Time
>>> dt1 = datetime(2006, 11, 21, 16, 30, tzinfo=gmt1)
>>> dt1.dst()
datetime.timedelta(0)
>>> dt1.utcoffset()
datetime.timedelta(seconds=3600)
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=gmt1)
>>> dt2.dst()
datetime.timedelta(seconds=3600)
>>> dt2.utcoffset()
datetime.timedelta(seconds=7200)
... def __repr__(self):
... return f"{self.__class__.__name__}()"
...
>>> tz1 = KabulTz()
>>> # Datetime before the change
>>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00
>>> # Datetime after the change
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00
>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(GMT2())
>>> dt3 # doctest: +ELLIPSIS
datetime.datetime(2006, 6, 14, 14, 0, tzinfo=<GMT2 object at 0x...>)
>>> dt2 # doctest: +ELLIPSIS
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=<GMT1 object at 0x...>)
>>> dt3 = dt2.astimezone(timezone.utc)
>>> dt3
datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)
>>> dt2
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())
>>> dt2.utctimetuple() == dt3.utctimetuple()
True

Expand Down Expand Up @@ -1656,26 +1664,27 @@ Instance methods:
Example:

>>> from datetime import time, tzinfo, timedelta
>>> class GMT1(tzinfo):
>>> class TZ1(tzinfo):
... def utcoffset(self, dt):
... return timedelta(hours=1)
... def dst(self, dt):
... return timedelta(0)
... def tzname(self,dt):
... return "Europe/Prague"
... return "+01:00"
... def __repr__(self):
... return f"{self.__class__.__name__}()"
...
>>> t = time(12, 10, 30, tzinfo=GMT1())
>>> t # doctest: +ELLIPSIS
datetime.time(12, 10, 30, tzinfo=<GMT1 object at 0x...>)
>>> gmt = GMT1()
>>> t = time(12, 10, 30, tzinfo=TZ1())
>>> t
datetime.time(12, 10, 30, tzinfo=TZ1())
>>> t.isoformat()
'12:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'Europe/Prague'
'+01:00'
>>> t.strftime("%H:%M:%S %Z")
'12:10:30 Europe/Prague'
'12:10:30 +01:00'
>>> 'The {} is {:%H:%M}.'.format("time", t)
'The time is 12:10.'

Expand Down

0 comments on commit f0b5ae4

Please sign in to comment.