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

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:

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:

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

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:

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'


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

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

Footnotes

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