datetime.rst



:mod:`datetime` --- Basic date and time types
The :mod:`datetime` module supplies classes for manipulating dates and times in
both simple and complex ways.  While date and time arithmetic is supported, the
focus of the implementation is on efficient attribute extraction for output
formatting and manipulation. For related functionality, see also the
:mod:`time` and :mod:`calendar` modules.
There are two kinds of date and time objects: "naive" and "aware".
An aware object has sufficient knowledge of applicable algorithmic and
political time adjustments, such as time zone and daylight saving time
information, to locate itself relative to other aware objects.  An aware object
is used to represent a specific moment in time that is not open to
interpretation [1].
A naive object does not contain enough information to unambiguously locate
itself relative to other date/time objects.  Whether a naive object represents
Coordinated Universal Time (UTC), local time, or time in some other timezone is
purely up to the program, just like it is up to the program whether a
particular number represents metres, miles, or mass.  Naive objects are easy to
understand and to work with, at the cost of ignoring some aspects of reality.
For applications requiring aware objects, :class:`.datetime` and :class:`.time`
objects have an optional time zone information attribute, :attr:`tzinfo`, that
can be set to an instance of a subclass of the abstract :class:`tzinfo` class.
These :class:`tzinfo` objects capture information about the offset from UTC
time, the time zone name, and whether Daylight Saving Time is in effect.  Note
that only one concrete :class:`tzinfo` class, the :class:`timezone` class, is
supplied by the :mod:`datetime` module.  The :class:`timezone` class can
represent simple timezones with fixed offset from UTC, such as UTC itself or
North American EST and EDT timezones.  Supporting timezones at deeper levels of
detail is up to the application.  The rules for time adjustment across the
world are more political than rational, change frequently, and there is no
standard suitable for every application aside from UTC.
The :mod:`datetime` module exports the following constants:

Available Types
An idealized naive date, assuming the current Gregorian calendar always was, and
always will be, in effect. Attributes: :attr:`year`, :attr:`month`, and
:attr:`day`.
An idealized time, independent of any particular day, assuming that every day
has exactly 24*60*60 seconds (there is no notion of "leap seconds" here).
Attributes: :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,
and :attr:`tzinfo`.
A combination of a date and a time. Attributes: :attr:`year`, :attr:`month`,
:attr:`day`, :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,
and :attr:`tzinfo`.
A duration expressing the difference between two :class:`date`, :class:`.time`,
or :class:`.datetime` instances to microsecond resolution.
An abstract base class for time zone information objects.  These are used by the
:class:`.datetime` and :class:`.time` classes to provide a customizable notion of
time adjustment (for example, to account for time zone and/or daylight saving
time).
A class that implements the :class:`tzinfo` abstract base class as a
fixed offset from the UTC.
Objects of these types are immutable.
Objects of the :class:`date` type are always naive.
An object of type :class:`.time` or :class:`.datetime` may be naive or aware.
A :class:`.datetime` object d is aware if d.tzinfo is not None and
d.tzinfo.utcoffset(d) does not return None.  If d.tzinfo is
None, or if d.tzinfo is not None but d.tzinfo.utcoffset(d)
returns None, d is naive.  A :class:`.time` object t is aware
if t.tzinfo is not None and t.tzinfo.utcoffset(None) does not return
None.  Otherwise, t is naive.
The distinction between naive and aware doesn't apply to :class:`timedelta`
objects.
Subclass relationships:
object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime


:class:`timedelta` Objects
A :class:`timedelta` object represents a duration, the difference between two
dates or times.
All arguments are optional and default to 0.  Arguments may be integers
or floats, and may be positive or negative.
Only days, seconds and microseconds are stored internally.  Arguments are
converted to those units:

A millisecond is converted to 1000 microseconds.
A minute is converted to 60 seconds.
An hour is converted to 3600 seconds.
A week is converted to 7 days.

and days, seconds and microseconds are then normalized so that the
representation is unique, with

0 <= microseconds < 1000000

0 <= seconds < 3600*24 (the number of seconds in one day)
-999999999 <= days <= 999999999

If any argument is a float and there are fractional microseconds,
the fractional microseconds left over from all arguments are
combined and their sum is rounded to the nearest microsecond using
round-half-to-even tiebreaker.  If no argument is a float, the
conversion and normalization processes are exact (no information is
lost).
If the normalized value of days lies outside the indicated range,
:exc:`OverflowError` is raised.
Note that normalization of negative values may be surprising at first. For
example,

>>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)


Class attributes are:
Note that, because of normalization, timedelta.max > -timedelta.min.
-timedelta.max is not representable as a :class:`timedelta` object.
Instance attributes (read-only):


Attribute
Value


days
Between -999999999 and 999999999 inclusive


seconds
Between 0 and 86399 inclusive


microseconds
Between 0 and 999999 inclusive


Supported operations:


Operation
Result


t1 = t2 + t3
Sum of t2 and t3. Afterwards t1-t2 ==
t3 and t1-t3 == t2 are true. (1)


t1 = t2 - t3
Difference of t2 and t3. Afterwards t1
== t2 - t3 and t2 == t1 + t3 are
true. (1)


t1 = t2 * i or t1 = i * t2
Delta multiplied by an integer.
Afterwards t1 // i == t2 is true,
provided i != 0.


In general, t1 * i == t1 * (i-1) + t1
is true. (1)


t1 = t2 * f or t1 = f * t2
Delta multiplied by a float. The result is
rounded to the nearest multiple of
timedelta.resolution using round-half-to-even.


f = t2 / t3
Division (3) of t2 by t3.  Returns a
:class:`float` object.


t1 = t2 / f or t1 = t2 / i
Delta divided by a float or an int. The result
is rounded to the nearest multiple of
timedelta.resolution using round-half-to-even.


t1 = t2 // i or
t1 = t2 // t3

The floor is computed and the remainder (if
any) is thrown away.  In the second case, an
integer is returned. (3)


t1 = t2 % t3
The remainder is computed as a
:class:`timedelta` object. (3)


q, r = divmod(t1, t2)
Computes the quotient and the remainder:
q = t1 // t2 (3) and r = t1 % t2.
q is an integer and r is a :class:`timedelta`
object.


+t1
Returns a :class:`timedelta` object with the
same value. (2)


-t1
equivalent to :class:`timedelta`(-t1.days, -t1.seconds,
-t1.microseconds), and to t1* -1. (1)(4)


abs(t)
equivalent to +t when t.days >= 0, and
to -t when t.days < 0. (2)


str(t)
Returns a string in the form
[D day[s], ][H]H:MM:SS[.UUUUUU], where D
is negative for negative t. (5)


repr(t)
Returns a string in the form
datetime.timedelta(D[, S[, U]]), where D
is negative for negative t. (5)


Notes:


This is exact, but may overflow.


This is exact, and cannot overflow.


Division by 0 raises :exc:`ZeroDivisionError`.


-timedelta.max is not representable as a :class:`timedelta` object.


String representations of :class:`timedelta` objects are normalized
similarly to their internal representation.  This leads to somewhat
unusual results for negative timedeltas.  For example:
>>> timedelta(hours=-5)
datetime.timedelta(-1, 68400)
>>> print(_)
-1 day, 19:00:00


In addition to the operations listed above :class:`timedelta` objects support
certain additions and subtractions with :class:`date` and :class:`.datetime`
objects (see below).
Comparisons of :class:`timedelta` objects are supported with the
:class:`timedelta` object representing the smaller duration considered to be the
smaller timedelta. In order to stop mixed-type comparisons from falling back to
the default comparison by object address, when a :class:`timedelta` object is
compared to an object of a different type, :exc:`TypeError` is raised unless the
comparison is == or !=.  The latter cases return :const:`False` or
:const:`True`, respectively.
:class:`timedelta` objects are :term:`hashable` (usable as dictionary keys), support
efficient pickling, and in Boolean contexts, a :class:`timedelta` object is
considered to be true if and only if it isn't equal to timedelta(0).
Instance methods:
Example usage:

>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)  # adds up to 365 days
>>> year.total_seconds()
31536000.0
>>> year == another_year
True
>>> ten_years = 10 * year
>>> ten_years, ten_years.days // 365
(datetime.timedelta(3650), 10)
>>> nine_years = ten_years - year
>>> nine_years, nine_years.days // 365
(datetime.timedelta(3285), 9)
>>> three_years = nine_years // 3;
>>> three_years, three_years.days // 365
(datetime.timedelta(1095), 3)
>>> abs(three_years - ten_years) == 2 * three_years + year
True


:class:`date` Objects
A :class:`date` object represents a date (year, month and day) in an idealized
calendar, the current Gregorian calendar indefinitely extended in both
directions.  January 1 of year 1 is called day number 1, January 2 of year 1 is
called day number 2, and so on.  This matches the definition of the "proleptic
Gregorian" calendar in Dershowitz and Reingold's book Calendrical Calculations,
where it's the base calendar for all computations.  See the book for algorithms
for converting between proleptic Gregorian ordinals and many other calendar
systems.
All arguments are required.  Arguments may be integers, in the following
ranges:

MINYEAR <= year <= MAXYEAR
1 <= month <= 12
1 <= day <= number of days in the given month and year

If an argument outside those ranges is given, :exc:`ValueError` is raised.
Other constructors, all class methods:
Class attributes:
Instance attributes (read-only):
Supported operations:


Operation
Result


date2 = date1 + timedelta

date2 is timedelta.days days removed
from date1.  (1)


date2 = date1 - timedelta
Computes date2 such that date2 +
timedelta == date1. (2)


timedelta = date1 - date2
(3)


date1 < date2

date1 is considered less than date2 when
date1 precedes date2 in time. (4)


Notes:


date2 is moved forward in time if timedelta.days > 0, or backward if
timedelta.days < 0.  Afterward date2 - date1 == timedelta.days.
timedelta.seconds and timedelta.microseconds are ignored.
:exc:`OverflowError` is raised if date2.year would be smaller than
:const:`MINYEAR` or larger than :const:`MAXYEAR`.
This isn't quite equivalent to date1 + (-timedelta), because -timedelta in
isolation can overflow in cases where date1 - timedelta does not.
timedelta.seconds and timedelta.microseconds are ignored.
This is exact, and cannot overflow.  timedelta.seconds and
timedelta.microseconds are 0, and date2 + timedelta == date1 after.
In other words, date1 < date2 if and only if date1.toordinal() <
date2.toordinal(). In order to stop comparison from falling back to the
default scheme of comparing object addresses, date comparison normally raises
:exc:`TypeError` if the other comparand isn't also a :class:`date` object.
However, NotImplemented is returned instead if the other comparand has a
:meth:`timetuple` attribute.  This hook gives other kinds of date objects a
chance at implementing mixed-type comparison. If not, when a :class:`date`
object is compared to an object of a different type, :exc:`TypeError` is raised
unless the comparison is == or !=.  The latter cases return
:const:`False` or :const:`True`, respectively.

Dates can be used as dictionary keys. In Boolean contexts, all :class:`date`
objects are considered to be true.
Instance methods:
Example of counting days to an event:
>>> import time
>>> from datetime import date
>>> today = date.today()
>>> today
datetime.date(2007, 12, 5)
>>> today == date.fromtimestamp(time.time())
True
>>> my_birthday = date(today.year, 6, 24)
>>> if my_birthday < today:
...     my_birthday = my_birthday.replace(year=today.year + 1)
>>> my_birthday
datetime.date(2008, 6, 24)
>>> time_to_birthday = abs(my_birthday - today)
>>> time_to_birthday.days
202

Example of working with :class:`date`:
>>> from datetime import date
>>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
>>> d
datetime.date(2002, 3, 11)
>>> t = d.timetuple()
>>> for i in t:     # doctest: +SKIP
...     print(i)
2002                # year
3                   # month
11                  # day
0
0
0
0                   # weekday (0 = Monday)
70                  # 70th day in the year
-1
>>> ic = d.isocalendar()
>>> for i in ic:    # doctest: +SKIP
...     print(i)
2002                # ISO year
11                  # ISO week number
1                   # ISO day number ( 1 = Monday )
>>> d.isoformat()
'2002-03-11'
>>> d.strftime("%d/%m/%y")
'11/03/02'
>>> d.strftime("%A %d. %B %Y")
'Monday 11. March 2002'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
'The day is 11, the month is March.'


:class:`datetime` Objects
A :class:`.datetime` object is a single object containing all the information
from a :class:`date` object and a :class:`.time` object.  Like a :class:`date`
object, :class:`.datetime` assumes the current Gregorian calendar extended in
both directions; like a time object, :class:`.datetime` assumes there are exactly
3600*24 seconds in every day.
Constructor:
The year, month and day arguments are required.  tzinfo may be None, or an
instance of a :class:`tzinfo` subclass.  The remaining arguments may be integers,
in the following ranges:

MINYEAR <= year <= MAXYEAR
1 <= month <= 12
1 <= day <= number of days in the given month and year
0 <= hour < 24
0 <= minute < 60
0 <= second < 60
0 <= microsecond < 1000000

If an argument outside those ranges is given, :exc:`ValueError` is raised.
Other constructors, all class methods:
Class attributes:
Instance attributes (read-only):
Supported operations:


Operation
Result


datetime2 = datetime1 + timedelta
(1)


datetime2 = datetime1 - timedelta
(2)


timedelta = datetime1 - datetime2
(3)


datetime1 < datetime2
Compares :class:`.datetime` to
:class:`.datetime`. (4)


datetime2 is a duration of timedelta removed from datetime1, moving forward in
time if timedelta.days > 0, or backward if timedelta.days < 0.  The
result has the same :attr:`tzinfo` attribute as the input datetime, and
datetime2 - datetime1 == timedelta after. :exc:`OverflowError` is raised if
datetime2.year would be smaller than :const:`MINYEAR` or larger than
:const:`MAXYEAR`. Note that no time zone adjustments are done even if the
input is an aware object.


Computes the datetime2 such that datetime2 + timedelta == datetime1. As for
addition, the result has the same :attr:`tzinfo` attribute as the input
datetime, and no time zone adjustments are done even if the input is aware.
This isn't quite equivalent to datetime1 + (-timedelta), because -timedelta
in isolation can overflow in cases where datetime1 - timedelta does not.


Subtraction of a :class:`.datetime` from a :class:`.datetime` is defined only if
both operands are naive, or if both are aware.  If one is aware and the other is
naive, :exc:`TypeError` is raised.
If both are naive, or both are aware and have the same :attr:`tzinfo` attribute,
the :attr:`tzinfo` attributes are ignored, and the result is a :class:`timedelta`
object t such that datetime2 + t == datetime1.  No time zone adjustments
are done in this case.
If both are aware and have different :attr:`tzinfo` attributes, a-b acts
as if a and b were first converted to naive UTC datetimes first.  The
result is (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None)
- b.utcoffset()) except that the implementation never overflows.


datetime1 is considered less than datetime2 when datetime1 precedes
datetime2 in time.
If one comparand is naive and the other is aware, :exc:`TypeError`
is raised if an order comparison is attempted.  For equality
comparisons, naive instances are never equal to aware instances.
If both comparands are aware, and have the same :attr:`tzinfo` attribute, the
common :attr:`tzinfo` attribute is ignored and the base datetimes are
compared.  If both comparands are aware and have different :attr:`tzinfo`
attributes, the comparands are first adjusted by subtracting their UTC
offsets (obtained from self.utcoffset()).

Note
In order to stop comparison from falling back to the default scheme of comparing
object addresses, datetime comparison normally raises :exc:`TypeError` if the
other comparand isn't also a :class:`.datetime` object.  However,
NotImplemented is returned instead if the other comparand has a
:meth:`timetuple` attribute.  This hook gives other kinds of date objects a
chance at implementing mixed-type comparison.  If not, when a :class:`.datetime`
object is compared to an object of a different type, :exc:`TypeError` is raised
unless the comparison is == or !=.  The latter cases return
:const:`False` or :const:`True`, respectively.


:class:`.datetime` objects can be used as dictionary keys. In Boolean contexts,
all :class:`.datetime` objects are considered to be true.
Instance methods:
Examples of working with datetime objects:
>>> from datetime import datetime, date, time
>>> # Using datetime.combine()
>>> d = date(2005, 7, 14)
>>> t = time(12, 30)
>>> datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)
>>> # Using datetime.now() or datetime.utcnow()
>>> datetime.now()   # doctest: +SKIP
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
>>> datetime.utcnow()   # doctest: +SKIP
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060)
>>> # Using datetime.strptime()
>>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> dt
datetime.datetime(2006, 11, 21, 16, 30)
>>> # Using datetime.timetuple() to get tuple of all attributes
>>> tt = dt.timetuple()
>>> for it in tt:   # doctest: +SKIP
...     print(it)
...
2006    # year
11      # month
21      # day
16      # hour
30      # minute
0       # second
1       # weekday (0 = Monday)
325     # number of days since 1st January
-1      # dst - method tzinfo.dst() returned None
>>> # Date in ISO format
>>> ic = dt.isocalendar()
>>> for it in ic:   # doctest: +SKIP
...     print(it)
...
2006    # ISO year
47      # ISO week
2       # ISO weekday
>>> # Formatting datetime
>>> dt.strftime("%A, %d. %B %Y %I:%M%p")
'Tuesday, 21. November 2006 04:30PM'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'.format(dt, "day", "month", "time")
'The day is 21, the month is November, the time is 04:30PM.'

Using datetime with tzinfo:

>>> from datetime import timedelta, datetime, tzinfo
>>> class GMT1(tzinfo):
...     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)
...         else:
...             return timedelta(0)
...     def tzname(self,dt):
...          return "GMT +1"
...
>>> 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)
...         else:
...             return timedelta(0)
...     def tzname(self,dt):
...         return "GMT +2"
...
>>> gmt1 = GMT1()
>>> # Daylight Saving Time
>>> dt1 = datetime(2006, 11, 21, 16, 30, tzinfo=gmt1)
>>> dt1.dst()
datetime.timedelta(0)
>>> dt1.utcoffset()
datetime.timedelta(0, 3600)
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=gmt1)
>>> dt2.dst()
datetime.timedelta(0, 3600)
>>> dt2.utcoffset()
datetime.timedelta(0, 7200)
>>> # 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...>)
>>> dt2.utctimetuple() == dt3.utctimetuple()
True


:class:`time` Objects
A time object represents a (local) time of day, independent of any particular
day, and subject to adjustment via a :class:`tzinfo` object.
All arguments are optional.  tzinfo may be None, or an instance of a
:class:`tzinfo` subclass.  The remaining arguments may be integers, in the
following ranges:

0 <= hour < 24
0 <= minute < 60
0 <= second < 60

0 <= microsecond < 1000000.

If an argument outside those ranges is given, :exc:`ValueError` is raised.  All
default to 0 except tzinfo, which defaults to :const:`None`.
Class attributes:
Instance attributes (read-only):
Supported operations:


comparison of :class:`.time` to :class:`.time`, where a is considered less
than b when a precedes b in time.  If one comparand is naive and the other
is aware, :exc:`TypeError` is raised if an order comparison is attempted. For equality
comparisons, naive instances are never equal to aware instances.
If both comparands are aware, and have
the same :attr:`tzinfo` attribute, the common :attr:`tzinfo` attribute is
ignored and the base times are compared.  If both comparands are aware and
have different :attr:`tzinfo` attributes, the comparands are first adjusted by
subtracting their UTC offsets (obtained from self.utcoffset()). In order
to stop mixed-type comparisons from falling back to the default comparison by
object address, when a :class:`.time` object is compared to an object of a
different type, :exc:`TypeError` is raised unless the comparison is == or
!=.  The latter cases return :const:`False` or :const:`True`, respectively.


hash, use as dict key


efficient pickling


in Boolean contexts, a :class:`.time` object is considered to be true if and
only if, after converting it to minutes and subtracting :meth:`utcoffset` (or
0 if that's None), the result is non-zero.


Instance methods:
Example:

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


:class:`tzinfo` Objects
:class:`tzinfo` is an abstract base class, meaning that this class should not be
instantiated directly.  You need to derive a concrete subclass, and (at least)
supply implementations of the standard :class:`tzinfo` methods needed by the
:class:`.datetime` methods you use.  The :mod:`datetime` module supplies
a simple concrete subclass of :class:`tzinfo` :class:`timezone` which can represent
timezones with fixed offset from UTC such as UTC itself or North American EST and
EDT.
An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the
constructors for :class:`.datetime` and :class:`.time` objects. The latter objects
view their attributes as being in local time, and the :class:`tzinfo` object
supports methods revealing offset of local time from UTC, the name of the time
zone, and DST offset, all relative to a date or time object passed to them.
Special requirement for pickling:  A :class:`tzinfo` subclass must have an
:meth:`__init__` method that can be called with no arguments, else it can be
pickled but possibly not unpickled again.  This is a technical requirement that
may be relaxed in the future.
A concrete subclass of :class:`tzinfo` may need to implement the following
methods.  Exactly which methods are needed depends on the uses made of aware
:mod:`datetime` objects.  If in doubt, simply implement all of them.
These methods are called by a :class:`.datetime` or :class:`.time` object, in
response to their methods of the same names.  A :class:`.datetime` object passes
itself as the argument, and a :class:`.time` object passes None as the
argument.  A :class:`tzinfo` subclass's methods should therefore be prepared to
accept a dt argument of None, or of class :class:`.datetime`.
When None is passed, it's up to the class designer to decide the best
response.  For example, returning None is appropriate if the class wishes to
say that time objects don't participate in the :class:`tzinfo` protocols.  It
may be more useful for utcoffset(None) to return the standard UTC offset, as
there is no other convention for discovering the standard offset.
When a :class:`.datetime` object is passed in response to a :class:`.datetime`
method, dt.tzinfo is the same object as self.  :class:`tzinfo` methods can
rely on this, unless user code calls :class:`tzinfo` methods directly.  The
intent is that the :class:`tzinfo` methods interpret dt as being in local
time, and not need worry about objects in other timezones.
There is one more :class:`tzinfo` method that a subclass may wish to override:
Example :class:`tzinfo` classes:
Note that there are unavoidable subtleties twice per year in a :class:`tzinfo`
subclass accounting for both standard and daylight time, at the DST transition
points.  For concreteness, consider US Eastern (UTC -0500), where EDT begins the
minute after 1:59 (EST) on the second Sunday in March, and ends the minute after
1:59 (EDT) on the first Sunday in November:
  UTC   3:MM  4:MM  5:MM  6:MM  7:MM  8:MM
  EST  22:MM 23:MM  0:MM  1:MM  2:MM  3:MM
  EDT  23:MM  0:MM  1:MM  2:MM  3:MM  4:MM

start  22:MM 23:MM  0:MM  1:MM  3:MM  4:MM

  end  23:MM  0:MM  1:MM  1:MM  2:MM  3:MM

When DST starts (the "start" line), the local wall clock leaps from 1:59 to
3:00.  A wall time of the form 2:MM doesn't really make sense on that day, so
astimezone(Eastern) won't deliver a result with hour == 2 on the day DST
begins.  In order for :meth:`astimezone` to make this guarantee, the
:meth:`tzinfo.dst` method must consider times in the "missing hour" (2:MM for
Eastern) to be in daylight time.
When DST ends (the "end" line), there's a potentially worse problem: there's an
hour that can't be spelled unambiguously in local wall time: the last hour of
daylight time.  In Eastern, that's times of the form 5:MM UTC on the day
daylight time ends.  The local wall clock leaps from 1:59 (daylight time) back
to 1:00 (standard time) again. Local times of the form 1:MM are ambiguous.
:meth:`astimezone` mimics the local clock's behavior by mapping two adjacent UTC
hours into the same local hour then.  In the Eastern example, UTC times of the
form 5:MM and 6:MM both map to 1:MM when converted to Eastern.  In order for
:meth:`astimezone` to make this guarantee, the :meth:`tzinfo.dst` method must
consider times in the "repeated hour" to be in standard time.  This is easily
arranged, as in the example, by expressing DST switch times in the time zone's
standard local time.
Applications that can't bear such ambiguities should avoid using hybrid
:class:`tzinfo` subclasses; there are no ambiguities when using :class:`timezone`,
or any other fixed-offset :class:`tzinfo` subclass (such as a class representing
only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).


:class:`timezone` Objects
The :class:`timezone` class is a subclass of :class:`tzinfo`, each
instance of which represents a timezone defined by a fixed offset from
UTC.  Note that objects of this class cannot be used to represent
timezone information in the locations where different offsets are used
in different days of the year or where historical changes have been
made to civil time.
The offset argument must be specified as a :class:`timedelta`
object representing the difference between the local time and UTC.  It must
be strictly between -timedelta(hours=24) and
timedelta(hours=24) and represent a whole number of minutes,
otherwise :exc:`ValueError` is raised.
The name argument is optional.  If specified it must be a string that
is used as the value returned by the tzname(dt) method.  Otherwise,
tzname(dt) returns a string 'UTCsHH:MM', where s is the sign of
offset, HH and MM are two digits of offset.hours and
offset.minutes respectively.
Class attributes:


:meth:`strftime` and :meth:`strptime` Behavior
:class:`date`, :class:`.datetime`, and :class:`.time` objects all support a
strftime(format) method, to create a string representing the time under the
control of an explicit format string.  Broadly speaking, d.strftime(fmt)
acts like the :mod:`time` module's time.strftime(fmt, d.timetuple())
although not all objects support a :meth:`timetuple` method.
Conversely, the :meth:`datetime.strptime` class method creates a
:class:`.datetime` object from a string representing a date and time and a
corresponding format string. datetime.strptime(date_string, format) is
equivalent to datetime(*(time.strptime(date_string, format)[0:6])).
For :class:`.time` objects, the format codes for year, month, and day should not
be used, as time objects have no such values.  If they're used anyway, 1900
is substituted for the year, and 1 for the month and day.
For :class:`date` objects, the format codes for hours, minutes, seconds, and
microseconds should not be used, as :class:`date` objects have no such
values.  If they're used anyway, 0 is substituted for them.
The full set of format codes supported varies across platforms, because Python
calls the platform C library's :func:`strftime` function, and platform
variations are common.  To see the full set of format codes supported on your
platform, consult the :manpage:`strftime(3)` documentation.
The following is a list of all the format codes that the C standard (1989
version) requires, and these work on all platforms with a standard C
implementation.  Note that the 1999 version of the C standard added additional
format codes.


Directive
Meaning
Example
Notes


%a
Weekday as locale's
abbreviated name.


Sun, Mon, ..., Sat
(en_US);
So, Mo, ..., Sa
(de_DE)


(1)


%A
Weekday as locale's full name.


Sunday, Monday, ...,
Saturday (en_US);
Sonntag, Montag, ...,
Samstag (de_DE)


(1)


%w
Weekday as a decimal number,
where 0 is Sunday and 6 is
Saturday.
0, 1, ..., 6
 

%d
Day of the month as a
zero-padded decimal number.
01, 02, ..., 31
 

%b
Month as locale's abbreviated
name.


Jan, Feb, ..., Dec
(en_US);
Jan, Feb, ..., Dez
(de_DE)


(1)


%B
Month as locale's full name.


January, February,
..., December (en_US);
Januar, Februar, ...,
Dezember (de_DE)


(1)


%m
Month as a zero-padded
decimal number.
01, 02, ..., 12
 

%y
Year without century as a
zero-padded decimal number.
00, 01, ..., 99
 

%Y
Year with century as a decimal
number.
0001, 0002, ..., 2013,
2014, ..., 9998, 9999
(2)


%H
Hour (24-hour clock) as a
zero-padded decimal number.
00, 01, ..., 23
 

%I
Hour (12-hour clock) as a
zero-padded decimal number.
01, 02, ..., 12
 

%p
Locale's equivalent of either
AM or PM.


AM, PM (en_US);
am, pm (de_DE)


(1),
(3)


%M
Minute as a zero-padded
decimal number.
00, 01, ..., 59
 

%S
Second as a zero-padded
decimal number.
00, 01, ..., 59
(4)


%f
Microsecond as a decimal
number, zero-padded on the
left.
000000, 000001, ...,
999999
(5)


%z
UTC offset in the form +HHMM
or -HHMM (empty string if the
the object is naive).
(empty), +0000, -0400,
+1030
(6)


%Z
Time zone name (empty string
if the object is naive).
(empty), UTC, EST, CST
 

%j
Day of the year as a
zero-padded decimal number.
001, 002, ..., 366
 

%U
Week number of the year
(Sunday as the first day of
the week) as a zero padded
decimal number. All days in a
new year preceding the first
Sunday are considered to be in
week 0.
00, 01, ..., 53
(7)


%W
Week number of the year
(Monday as the first day of
the week) as a decimal number.
All days in a new year
preceding the first Monday
are considered to be in
week 0.
00, 01, ..., 53
(7)


%c
Locale's appropriate date and
time representation.


Tue Aug 16 21:30:00
1988 (en_US);
Di 16 Aug 21:30:00
1988 (de_DE)


(1)


%x
Locale's appropriate date
representation.


08/16/88 (None);
08/16/1988 (en_US);
16.08.1988 (de_DE)


(1)


%X
Locale's appropriate time
representation.


21:30:00 (en_US);
21:30:00 (de_DE)


(1)


%%
A literal '%' character.
%
 

Notes:


Because the format depends on the current locale, care should be taken when
making assumptions about the output value. Field orderings will vary (for
example, "month/day/year" versus "day/month/year"), and the output may
contain Unicode characters encoded using the locale's default encoding (for
example, if the current locale is ja_JP, the default encoding could be
any one of eucJP, SJIS, or utf-8; use :meth:`locale.getlocale`
to determine the current locale's encoding).


The :meth:`strptime` method can parse years in the full [1, 9999] range, but
years < 1000 must be zero-filled to 4-digit width.


When used with the :meth:`strptime` method, the %p directive only affects
the output hour field if the %I directive is used to parse the hour.


Unlike the :mod:`time` module, the :mod:`datetime` module does not support
leap seconds.


When used with the :meth:`strptime` method, the %f directive
accepts from one to six digits and zero pads on the right.  %f is
an extension to the set of format characters in the C standard (but
implemented separately in datetime objects, and therefore always
available).


For a naive object, the %z and %Z format codes are replaced by empty
strings.
For an aware object:

%z

:meth:`utcoffset` is transformed into a 5-character string of the form
+HHMM or -HHMM, where HH is a 2-digit string giving the number of UTC
offset hours, and MM is a 2-digit string giving the number of UTC offset
minutes.  For example, if :meth:`utcoffset` returns
timedelta(hours=-3, minutes=-30), %z is replaced with the string
'-0330'.

%Z

If :meth:`tzname` returns None, %Z is replaced by an empty
string.  Otherwise %Z is replaced by the returned value, which must
be a string.


When used with the :meth:`strptime` method, %U and %W are only used
in calculations when the day of the week and the year are specified.


Footnotes


[1]
If, that is, we ignore the effects of Relativity