1773
1780
microseconds should not be used, as :class:`date` objects have no such
1774
1781
values. If they're used anyway, ``0`` is substituted for them.
1776
For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty
1779
For an aware object:
1782
:meth:`utcoffset` is transformed into a 5-character string of the form +HHMM or
1783
-HHMM, where HH is a 2-digit string giving the number of UTC offset hours, and
1784
MM is a 2-digit string giving the number of UTC offset minutes. For example, if
1785
:meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is
1786
replaced with the string ``'-0330'``.
1789
If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty string.
1790
Otherwise ``%Z`` is replaced by the returned value, which must be a string.
1792
1783
The full set of format codes supported varies across platforms, because Python
1793
1784
calls the platform C library's :func:`strftime` function, and platform
1794
variations are common.
1785
variations are common. To see the full set of format codes supported on your
1786
platform, consult the :manpage:`strftime(3)` documentation.
1796
1788
The following is a list of all the format codes that the C standard (1989
1797
1789
version) requires, and these work on all platforms with a standard C
1798
1790
implementation. Note that the 1999 version of the C standard added additional
1801
+-----------+--------------------------------+-------+
1802
| Directive | Meaning | Notes |
1803
+===========+================================+=======+
1804
| ``%a`` | Locale's abbreviated weekday | |
1806
+-----------+--------------------------------+-------+
1807
| ``%A`` | Locale's full weekday name. | |
1808
+-----------+--------------------------------+-------+
1809
| ``%b`` | Locale's abbreviated month | |
1811
+-----------+--------------------------------+-------+
1812
| ``%B`` | Locale's full month name. | |
1813
+-----------+--------------------------------+-------+
1814
| ``%c`` | Locale's appropriate date and | |
1815
| | time representation. | |
1816
+-----------+--------------------------------+-------+
1817
| ``%d`` | Day of the month as a decimal | |
1818
| | number [01,31]. | |
1819
+-----------+--------------------------------+-------+
1820
| ``%f`` | Microsecond as a decimal | \(1) |
1821
| | number [0,999999], zero-padded | |
1823
+-----------+--------------------------------+-------+
1824
| ``%H`` | Hour (24-hour clock) as a | |
1825
| | decimal number [00,23]. | |
1826
+-----------+--------------------------------+-------+
1827
| ``%I`` | Hour (12-hour clock) as a | |
1828
| | decimal number [01,12]. | |
1829
+-----------+--------------------------------+-------+
1830
| ``%j`` | Day of the year as a decimal | |
1831
| | number [001,366]. | |
1832
+-----------+--------------------------------+-------+
1833
| ``%m`` | Month as a decimal number | |
1835
+-----------+--------------------------------+-------+
1836
| ``%M`` | Minute as a decimal number | |
1838
+-----------+--------------------------------+-------+
1839
| ``%p`` | Locale's equivalent of either | \(2) |
1841
+-----------+--------------------------------+-------+
1842
| ``%S`` | Second as a decimal number | \(3) |
1844
+-----------+--------------------------------+-------+
1845
| ``%U`` | Week number of the year | \(4) |
1846
| | (Sunday as the first day of | |
1847
| | the week) as a decimal number | |
1848
| | [00,53]. All days in a new | |
1849
| | year preceding the first | |
1850
| | Sunday are considered to be in | |
1852
+-----------+--------------------------------+-------+
1853
| ``%w`` | Weekday as a decimal number | |
1854
| | [0(Sunday),6]. | |
1855
+-----------+--------------------------------+-------+
1856
| ``%W`` | Week number of the year | \(4) |
1857
| | (Monday as the first day of | |
1858
| | the week) as a decimal number | |
1859
| | [00,53]. All days in a new | |
1860
| | year preceding the first | |
1861
| | Monday are considered to be in | |
1863
+-----------+--------------------------------+-------+
1864
| ``%x`` | Locale's appropriate date | |
1865
| | representation. | |
1866
+-----------+--------------------------------+-------+
1867
| ``%X`` | Locale's appropriate time | |
1868
| | representation. | |
1869
+-----------+--------------------------------+-------+
1870
| ``%y`` | Year without century as a | |
1871
| | decimal number [00,99]. | |
1872
+-----------+--------------------------------+-------+
1873
| ``%Y`` | Year with century as a decimal | \(5) |
1874
| | number [0001,9999]. | |
1875
+-----------+--------------------------------+-------+
1876
| ``%z`` | UTC offset in the form +HHMM | \(6) |
1877
| | or -HHMM (empty string if the | |
1878
| | the object is naive). | |
1879
+-----------+--------------------------------+-------+
1880
| ``%Z`` | Time zone name (empty string | |
1881
| | if the object is naive). | |
1882
+-----------+--------------------------------+-------+
1883
| ``%%`` | A literal ``'%'`` character. | |
1884
+-----------+--------------------------------+-------+
1793
+-----------+--------------------------------+------------------------+-------+
1794
| Directive | Meaning | Example | Notes |
1795
+===========+================================+========================+=======+
1796
| ``%a`` | Weekday as locale's || Sun, Mon, ..., Sat | \(1) |
1797
| | abbreviated name. | (en_US); | |
1798
| | || So, Mo, ..., Sa | |
1800
+-----------+--------------------------------+------------------------+-------+
1801
| ``%A`` | Weekday as locale's full name. || Sunday, Monday, ..., | \(1) |
1802
| | | Saturday (en_US); | |
1803
| | || Sonntag, Montag, ..., | |
1804
| | | Samstag (de_DE) | |
1805
+-----------+--------------------------------+------------------------+-------+
1806
| ``%w`` | Weekday as a decimal number, | 0, 1, ..., 6 | |
1807
| | where 0 is Sunday and 6 is | | |
1809
+-----------+--------------------------------+------------------------+-------+
1810
| ``%d`` | Day of the month as a | 01, 02, ..., 31 | |
1811
| | zero-padded decimal number. | | |
1812
+-----------+--------------------------------+------------------------+-------+
1813
| ``%b`` | Month as locale's abbreviated || Jan, Feb, ..., Dec | \(1) |
1814
| | name. | (en_US); | |
1815
| | || Jan, Feb, ..., Dez | |
1817
+-----------+--------------------------------+------------------------+-------+
1818
| ``%B`` | Month as locale's full name. || January, February, | \(1) |
1819
| | | ..., December (en_US);| |
1820
| | || Januar, Februar, ..., | |
1821
| | | Dezember (de_DE) | |
1822
+-----------+--------------------------------+------------------------+-------+
1823
| ``%m`` | Month as a zero-padded | 01, 02, ..., 12 | |
1824
| | decimal number. | | |
1825
+-----------+--------------------------------+------------------------+-------+
1826
| ``%y`` | Year without century as a | 00, 01, ..., 99 | |
1827
| | zero-padded decimal number. | | |
1828
+-----------+--------------------------------+------------------------+-------+
1829
| ``%Y`` | Year with century as a decimal | 0001, 0002, ..., 2013, | \(2) |
1830
| | number. | 2014, ..., 9998, 9999 | |
1831
+-----------+--------------------------------+------------------------+-------+
1832
| ``%H`` | Hour (24-hour clock) as a | 00, 01, ..., 23 | |
1833
| | zero-padded decimal number. | | |
1834
+-----------+--------------------------------+------------------------+-------+
1835
| ``%I`` | Hour (12-hour clock) as a | 01, 02, ..., 12 | |
1836
| | zero-padded decimal number. | | |
1837
+-----------+--------------------------------+------------------------+-------+
1838
| ``%p`` | Locale's equivalent of either || AM, PM (en_US); | \(1), |
1839
| | AM or PM. || am, pm (de_DE) | \(3) |
1840
+-----------+--------------------------------+------------------------+-------+
1841
| ``%M`` | Minute as a zero-padded | 00, 01, ..., 59 | |
1842
| | decimal number. | | |
1843
+-----------+--------------------------------+------------------------+-------+
1844
| ``%S`` | Second as a zero-padded | 00, 01, ..., 59 | \(4) |
1845
| | decimal number. | | |
1846
+-----------+--------------------------------+------------------------+-------+
1847
| ``%f`` | Microsecond as a decimal | 000000, 000001, ..., | \(5) |
1848
| | number, zero-padded on the | 999999 | |
1850
+-----------+--------------------------------+------------------------+-------+
1851
| ``%z`` | UTC offset in the form +HHMM | (empty), +0000, -0400, | \(6) |
1852
| | or -HHMM (empty string if the | +1030 | |
1853
| | the object is naive). | | |
1854
+-----------+--------------------------------+------------------------+-------+
1855
| ``%Z`` | Time zone name (empty string | (empty), UTC, EST, CST | |
1856
| | if the object is naive). | | |
1857
+-----------+--------------------------------+------------------------+-------+
1858
| ``%j`` | Day of the year as a | 001, 002, ..., 366 | |
1859
| | zero-padded decimal number. | | |
1860
+-----------+--------------------------------+------------------------+-------+
1861
| ``%U`` | Week number of the year | 00, 01, ..., 53 | \(7) |
1862
| | (Sunday as the first day of | | |
1863
| | the week) as a zero padded | | |
1864
| | decimal number. All days in a | | |
1865
| | new year preceding the first | | |
1866
| | Sunday are considered to be in | | |
1868
+-----------+--------------------------------+------------------------+-------+
1869
| ``%W`` | Week number of the year | 00, 01, ..., 53 | \(7) |
1870
| | (Monday as the first day of | | |
1871
| | the week) as a decimal number. | | |
1872
| | All days in a new year | | |
1873
| | preceding the first Monday | | |
1874
| | are considered to be in | | |
1876
+-----------+--------------------------------+------------------------+-------+
1877
| ``%c`` | Locale's appropriate date and || Tue Aug 16 21:30:00 | \(1) |
1878
| | time representation. | 1988 (en_US); | |
1879
| | || Di 16 Aug 21:30:00 | |
1880
| | | 1988 (de_DE) | |
1881
+-----------+--------------------------------+------------------------+-------+
1882
| ``%x`` | Locale's appropriate date || 08/16/88 (None); | \(1) |
1883
| | representation. || 08/16/1988 (en_US); | |
1884
| | || 16.08.1988 (de_DE) | |
1885
+-----------+--------------------------------+------------------------+-------+
1886
| ``%X`` | Locale's appropriate time || 21:30:00 (en_US); | \(1) |
1887
| | representation. || 21:30:00 (de_DE) | |
1888
+-----------+--------------------------------+------------------------+-------+
1889
| ``%%`` | A literal ``'%'`` character. | % | |
1890
+-----------+--------------------------------+------------------------+-------+
1895
Because the format depends on the current locale, care should be taken when
1896
making assumptions about the output value. Field orderings will vary (for
1897
example, "month/day/year" versus "day/month/year"), and the output may
1898
contain Unicode characters encoded using the locale's default encoding (for
1899
example, if the current locale is ``js_JP``, the default encoding could be
1900
any one of ``eucJP``, ``SJIS``, or ``utf-8``; use :meth:`locale.getlocale`
1901
to determine the current locale's encoding).
1904
The :meth:`strptime` method can parse years in the full [1, 9999] range, but
1905
years < 1000 must be zero-filled to 4-digit width.
1907
.. versionchanged:: 3.2
1908
In previous versions, :meth:`strftime` method was restricted to
1911
.. versionchanged:: 3.3
1912
In version 3.2, :meth:`strftime` method was restricted to
1916
When used with the :meth:`strptime` method, the ``%p`` directive only affects
1917
the output hour field if the ``%I`` directive is used to parse the hour.
1920
Unlike the :mod:`time` module, the :mod:`datetime` module does not support
1889
1924
When used with the :meth:`strptime` method, the ``%f`` directive
1890
1925
accepts from one to six digits and zero pads on the right. ``%f`` is
1891
1926
an extension to the set of format characters in the C standard (but
1892
1927
implemented separately in datetime objects, and therefore always
1896
When used with the :meth:`strptime` method, the ``%p`` directive only affects
1897
the output hour field if the ``%I`` directive is used to parse the hour.
1900
Unlike :mod:`time` module, :mod:`datetime` module does not support
1904
When used with the :meth:`strptime` method, ``%U`` and ``%W`` are only used in
1905
calculations when the day of the week and the year are specified.
1908
The :meth:`strptime` method can
1909
parse years in the full [1, 9999] range, but years < 1000 must be
1910
zero-filled to 4-digit width.
1912
.. versionchanged:: 3.2
1913
In previous versions, :meth:`strftime` method was restricted to
1916
.. versionchanged:: 3.3
1917
In version 3.2, :meth:`strftime` method was restricted to
1921
For example, if :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``,
1922
``%z`` is replaced with the string ``'-0330'``.
1924
.. versionchanged:: 3.2
1925
When the ``%z`` directive is provided to the :meth:`strptime` method, an
1926
aware :class:`.datetime` object will be produced. The ``tzinfo`` of the
1927
result will be set to a :class:`timezone` instance.
1931
For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty
1934
For an aware object:
1937
:meth:`utcoffset` is transformed into a 5-character string of the form
1938
+HHMM or -HHMM, where HH is a 2-digit string giving the number of UTC
1939
offset hours, and MM is a 2-digit string giving the number of UTC offset
1940
minutes. For example, if :meth:`utcoffset` returns
1941
``timedelta(hours=-3, minutes=-30)``, ``%z`` is replaced with the string
1945
If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty
1946
string. Otherwise ``%Z`` is replaced by the returned value, which must
1949
.. versionchanged:: 3.2
1950
When the ``%z`` directive is provided to the :meth:`strptime` method, an
1951
aware :class:`.datetime` object will be produced. The ``tzinfo`` of the
1952
result will be set to a :class:`timezone` instance.
1955
When used with the :meth:`strptime` method, ``%U`` and ``%W`` are only used
1956
in calculations when the day of the week and the year are specified.
1929
1958
.. rubric:: Footnotes
added
removed
Doc/library/datetime.rst
