Source

cpython / Doc / library / 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". This distinction refers to whether the object has any notion of time zone, daylight saving time, or other kind of algorithmic or political time adjustment. Whether a naive :class:`.datetime` object represents Coordinated Universal Time (UTC), local time, or time in some other timezone is purely up to the program, just like it's up to the program whether a particular number represents metres, miles, or mass. Naive :class:`.datetime` objects are easy to understand and to work with, at the cost of ignoring some aspects of reality.

For applications requiring more, :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 whatever level of detail is required 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 d of type :class:`.time` or :class:`.datetime` may be naive or aware. 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.

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. 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:

  1. This is exact, but may overflow.

  2. This is exact, and cannot overflow.

  3. Division by 0 raises :exc:`ZeroDivisionError`.

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

  5. 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:

  1. 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`.
  2. 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.
  3. This is exact, and cannot overflow. timedelta.seconds and timedelta.microseconds are 0, and date2 + timedelta == date1 after.
  4. 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`:

: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)
  1. 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.

  2. 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.

  3. 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.

  4. 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 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:

Using datetime with tzinfo:

>>> from datetime import timedelta, datetime, tzinfo
>>> class GMT1(tzinfo):
...     def __init__(self):         # 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)
...     def utcoffset(self, dt):
...         return timedelta(hours=1) + self.dst(dt)
...     def dst(self, dt):
...         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 __init__(self):
...         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)
...     def utcoffset(self, dt):
...         return timedelta(hours=1) + self.dst(dt)
...     def dst(self, dt):
...         if self.dston <=  dt.replace(tzinfo=None) < self.dstoff:
...             return timedelta(hours=2)
...         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 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'

: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 reprsent 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:`rzinfo.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.

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.

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.

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 Notes
%a Locale's abbreviated weekday name.  
%A Locale's full weekday name.  
%b Locale's abbreviated month name.  
%B Locale's full month name.  
%c Locale's appropriate date and time representation.  
%d Day of the month as a decimal number [01,31].  
%f Microsecond as a decimal number [0,999999], zero-padded on the left (1)
%H Hour (24-hour clock) as a decimal number [00,23].  
%I Hour (12-hour clock) as a decimal number [01,12].  
%j Day of the year as a decimal number [001,366].  
%m Month as a decimal number [01,12].  
%M Minute as a decimal number [00,59].  
%p Locale's equivalent of either AM or PM. (2)
%S Second as a decimal number [00,59]. (3)
%U Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. (4)
%w Weekday as a decimal number [0(Sunday),6].  
%W Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 0. (4)
%x Locale's appropriate date representation.  
%X Locale's appropriate time representation.  
%y Year without century as a decimal number [00,99].  
%Y Year with century as a decimal number [0001,9999]. (5)
%z UTC offset in the form +HHMM or -HHMM (empty string if the the object is naive). (6)
%Z Time zone name (empty string if the object is naive).  
%% A literal '%' character.  

Notes:

  1. 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).
  2. 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.
  3. Unlike :mod:`time` module, :mod:`datetime` module does not support leap seconds.
  4. 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.
  5. The :meth:`strptime` method can parse years in the full [1, 9999] range, but years < 1000 must be zero-filled to 4-digit width.
  6. For example, if :meth:`utcoffset` returns timedelta(hours=-3, minutes=-30), %z is replaced with the string '-0330'.