CINXE.COM

<!DOCTYPE html> <html lang="en" data-content_root="../"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" /> <meta property="og:title" content="datetime — Basic date and time types" /> <meta property="og:type" content="website" /> <meta property="og:url" content="https://docs.python.org/3/library/datetime.html" /> <meta property="og:site_name" content="Python documentation" /> <meta property="og:description" content="Source code: Lib/datetime.py The datetime module supplies classes for manipulating dates and times. While date and time arithmetic is supported, the focus of the implementation is on efficient attr..." /> <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" /> <meta property="og:image:alt" content="Python documentation" /> <meta name="description" content="Source code: Lib/datetime.py The datetime module supplies classes for manipulating dates and times. While date and time arithmetic is supported, the focus of the implementation is on efficient attr..." /> <meta property="og:image:width" content="200" /> <meta property="og:image:height" content="200" /> <meta name="theme-color" content="#3776ab" /> <title>datetime — Basic date and time types — Python 3.13.0 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0"> <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" /> <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=41b4f12d" /> <link rel="stylesheet" type="text/css" href="../_static/sidebar-wrap.css?v=65806c5a" /> <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" /> <script src="../_static/documentation_options.js?v=6aaf4047"></script> <script src="../_static/doctools.js?v=9bcbadda"></script> <script src="../_static/sphinx_highlight.js?v=dc90522c"></script> <script src="../_static/sidebar.js"></script> <link rel="search" type="application/opensearchdescription+xml" title="Search within Python 3.13.0 documentation" href="../_static/opensearch.xml"/> <link rel="author" title="About these documents" href="../about.html" /> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> <link rel="copyright" title="Copyright" href="../copyright.html" /> <link rel="next" title="zoneinfo — IANA time zone support" href="zoneinfo.html" /> <link rel="prev" title="Data Types" href="datatypes.html" /> <script defer data-domain="docs.python.org" src="https://plausible.io/js/script.js"></script> <link rel="canonical" href="https://docs.python.org/3/library/datetime.html" /> <style> @media only screen { table.full-width-table { width: 100%; } } </style> <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css"> <link rel="shortcut icon" type="image/png" href="../_static/py.svg" /> <script type="text/javascript" src="../_static/copybutton.js"></script> <script type="text/javascript" src="../_static/menu.js"></script> <script type="text/javascript" src="../_static/search-focus.js"></script> <script type="text/javascript" src="../_static/themetoggle.js"></script> <script type="text/javascript" src="../_static/rtd_switcher.js"></script> <meta name="readthedocs-addons-api-version" content="1"> </head> <body> <div class="mobile-nav"> <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation" aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" /> <nav class="nav-content" role="navigation"> <label for="menuToggler" class="toggler__label"> </label> <a href="https://www.python.org/" class="nav-logo"> <img src="../_static/py.svg" alt="Python logo"/> </a> <form role="search" class="search" action="../search.html" method="get"> <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon"> <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path> </svg> <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" /> <input type="submit" value="Go"/> </form> </nav> <div class="menu-wrapper"> <nav class="menu" role="navigation" aria-label="main navigation"> <div class="language_switcher_placeholder"></div> <label class="theme-selector-label"> Theme <select class="theme-selector" oninput="activateTheme(this.value)"> <option value="auto" selected>Auto</option> <option value="light">Light</option> <option value="dark">Dark</option> </select> </label> <div> <h3><a href="../contents.html">Table of Contents</a></h3> <ul> <li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate">datetime</code> — Basic date and time types</a><ul> <li><a class="reference internal" href="#aware-and-naive-objects">Aware and Naive Objects</a></li> <li><a class="reference internal" href="#constants">Constants</a><ul> <li><a class="reference internal" href="#datetime.MINYEAR"><code class="docutils literal notranslate">MINYEAR</code></a></li> <li><a class="reference internal" href="#datetime.MAXYEAR"><code class="docutils literal notranslate">MAXYEAR</code></a></li> <li><a class="reference internal" href="#datetime.UTC"><code class="docutils literal notranslate">UTC</code></a></li> </ul> </li> <li><a class="reference internal" href="#available-types">Available Types</a><ul> <li><a class="reference internal" href="#common-properties">Common Properties</a></li> <li><a class="reference internal" href="#determining-if-an-object-is-aware-or-naive">Determining if an Object is Aware or Naive</a></li> </ul> </li> <li><a class="reference internal" href="#timedelta-objects"><code class="xref py py-class docutils literal notranslate">timedelta</code> Objects</a><ul> <li><a class="reference internal" href="#datetime.timedelta"><code class="docutils literal notranslate">timedelta</code></a></li> <li><a class="reference internal" href="#datetime.timedelta.min"><code class="docutils literal notranslate">min</code></a></li> <li><a class="reference internal" href="#datetime.timedelta.max"><code class="docutils literal notranslate">max</code></a></li> <li><a class="reference internal" href="#datetime.timedelta.resolution"><code class="docutils literal notranslate">resolution</code></a></li> <li><a class="reference internal" href="#datetime.timedelta.days"><code class="docutils literal notranslate">days</code></a></li> <li><a class="reference internal" href="#datetime.timedelta.seconds"><code class="docutils literal notranslate">seconds</code></a></li> <li><a class="reference internal" href="#datetime.timedelta.microseconds"><code class="docutils literal notranslate">microseconds</code></a></li> <li><a class="reference internal" href="#datetime.timedelta.total_seconds"><code class="docutils literal notranslate">total_seconds()</code></a></li> <li><a class="reference internal" href="#examples-of-usage-timedelta">Examples of usage: <code class="xref py py-class docutils literal notranslate">timedelta</code></a></li> </ul> </li> <li><a class="reference internal" href="#date-objects"><code class="xref py py-class docutils literal notranslate">date</code> Objects</a><ul> <li><a class="reference internal" href="#datetime.date"><code class="docutils literal notranslate">date</code></a></li> <li><a class="reference internal" href="#datetime.date.today"><code class="docutils literal notranslate">today()</code></a></li> <li><a class="reference internal" href="#datetime.date.fromtimestamp"><code class="docutils literal notranslate">fromtimestamp()</code></a></li> <li><a class="reference internal" href="#datetime.date.fromordinal"><code class="docutils literal notranslate">fromordinal()</code></a></li> <li><a class="reference internal" href="#datetime.date.fromisoformat"><code class="docutils literal notranslate">fromisoformat()</code></a></li> <li><a class="reference internal" href="#datetime.date.fromisocalendar"><code class="docutils literal notranslate">fromisocalendar()</code></a></li> <li><a class="reference internal" href="#datetime.date.min"><code class="docutils literal notranslate">min</code></a></li> <li><a class="reference internal" href="#datetime.date.max"><code class="docutils literal notranslate">max</code></a></li> <li><a class="reference internal" href="#datetime.date.resolution"><code class="docutils literal notranslate">resolution</code></a></li> <li><a class="reference internal" href="#datetime.date.year"><code class="docutils literal notranslate">year</code></a></li> <li><a class="reference internal" href="#datetime.date.month"><code class="docutils literal notranslate">month</code></a></li> <li><a class="reference internal" href="#datetime.date.day"><code class="docutils literal notranslate">day</code></a></li> <li><a class="reference internal" href="#datetime.date.replace"><code class="docutils literal notranslate">replace()</code></a></li> <li><a class="reference internal" href="#datetime.date.timetuple"><code class="docutils literal notranslate">timetuple()</code></a></li> <li><a class="reference internal" href="#datetime.date.toordinal"><code class="docutils literal notranslate">toordinal()</code></a></li> <li><a class="reference internal" href="#datetime.date.weekday"><code class="docutils literal notranslate">weekday()</code></a></li> <li><a class="reference internal" href="#datetime.date.isoweekday"><code class="docutils literal notranslate">isoweekday()</code></a></li> <li><a class="reference internal" href="#datetime.date.isocalendar"><code class="docutils literal notranslate">isocalendar()</code></a></li> <li><a class="reference internal" href="#datetime.date.isoformat"><code class="docutils literal notranslate">isoformat()</code></a></li> <li><a class="reference internal" href="#datetime.date.__str__"><code class="docutils literal notranslate">__str__()</code></a></li> <li><a class="reference internal" href="#datetime.date.ctime"><code class="docutils literal notranslate">ctime()</code></a></li> <li><a class="reference internal" href="#datetime.date.strftime"><code class="docutils literal notranslate">strftime()</code></a></li> <li><a class="reference internal" href="#datetime.date.__format__"><code class="docutils literal notranslate">__format__()</code></a></li> <li><a class="reference internal" href="#examples-of-usage-date">Examples of Usage: <code class="xref py py-class docutils literal notranslate">date</code></a></li> </ul> </li> <li><a class="reference internal" href="#datetime-objects"><code class="xref py py-class docutils literal notranslate">datetime</code> Objects</a><ul> <li><a class="reference internal" href="#datetime.datetime"><code class="docutils literal notranslate">datetime</code></a></li> <li><a class="reference internal" href="#datetime.datetime.today"><code class="docutils literal notranslate">today()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.now"><code class="docutils literal notranslate">now()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.utcnow"><code class="docutils literal notranslate">utcnow()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.fromtimestamp"><code class="docutils literal notranslate">fromtimestamp()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.utcfromtimestamp"><code class="docutils literal notranslate">utcfromtimestamp()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.fromordinal"><code class="docutils literal notranslate">fromordinal()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.combine"><code class="docutils literal notranslate">combine()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.fromisoformat"><code class="docutils literal notranslate">fromisoformat()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.fromisocalendar"><code class="docutils literal notranslate">fromisocalendar()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.strptime"><code class="docutils literal notranslate">strptime()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.min"><code class="docutils literal notranslate">min</code></a></li> <li><a class="reference internal" href="#datetime.datetime.max"><code class="docutils literal notranslate">max</code></a></li> <li><a class="reference internal" href="#datetime.datetime.resolution"><code class="docutils literal notranslate">resolution</code></a></li> <li><a class="reference internal" href="#datetime.datetime.year"><code class="docutils literal notranslate">year</code></a></li> <li><a class="reference internal" href="#datetime.datetime.month"><code class="docutils literal notranslate">month</code></a></li> <li><a class="reference internal" href="#datetime.datetime.day"><code class="docutils literal notranslate">day</code></a></li> <li><a class="reference internal" href="#datetime.datetime.hour"><code class="docutils literal notranslate">hour</code></a></li> <li><a class="reference internal" href="#datetime.datetime.minute"><code class="docutils literal notranslate">minute</code></a></li> <li><a class="reference internal" href="#datetime.datetime.second"><code class="docutils literal notranslate">second</code></a></li> <li><a class="reference internal" href="#datetime.datetime.microsecond"><code class="docutils literal notranslate">microsecond</code></a></li> <li><a class="reference internal" href="#datetime.datetime.tzinfo"><code class="docutils literal notranslate">tzinfo</code></a></li> <li><a class="reference internal" href="#datetime.datetime.fold"><code class="docutils literal notranslate">fold</code></a></li> <li><a class="reference internal" href="#datetime.datetime.date"><code class="docutils literal notranslate">date()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.time"><code class="docutils literal notranslate">time()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.timetz"><code class="docutils literal notranslate">timetz()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.replace"><code class="docutils literal notranslate">replace()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.astimezone"><code class="docutils literal notranslate">astimezone()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.utcoffset"><code class="docutils literal notranslate">utcoffset()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.dst"><code class="docutils literal notranslate">dst()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.tzname"><code class="docutils literal notranslate">tzname()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.timetuple"><code class="docutils literal notranslate">timetuple()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.utctimetuple"><code class="docutils literal notranslate">utctimetuple()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.toordinal"><code class="docutils literal notranslate">toordinal()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.timestamp"><code class="docutils literal notranslate">timestamp()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.weekday"><code class="docutils literal notranslate">weekday()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.isoweekday"><code class="docutils literal notranslate">isoweekday()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.isocalendar"><code class="docutils literal notranslate">isocalendar()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.isoformat"><code class="docutils literal notranslate">isoformat()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.__str__"><code class="docutils literal notranslate">__str__()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.ctime"><code class="docutils literal notranslate">ctime()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.strftime"><code class="docutils literal notranslate">strftime()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.__format__"><code class="docutils literal notranslate">__format__()</code></a></li> <li><a class="reference internal" href="#examples-of-usage-datetime">Examples of Usage: <code class="xref py py-class docutils literal notranslate">datetime</code></a></li> </ul> </li> <li><a class="reference internal" href="#time-objects"><code class="xref py py-class docutils literal notranslate">time</code> Objects</a><ul> <li><a class="reference internal" href="#datetime.time"><code class="docutils literal notranslate">time</code></a></li> <li><a class="reference internal" href="#datetime.time.min"><code class="docutils literal notranslate">min</code></a></li> <li><a class="reference internal" href="#datetime.time.max"><code class="docutils literal notranslate">max</code></a></li> <li><a class="reference internal" href="#datetime.time.resolution"><code class="docutils literal notranslate">resolution</code></a></li> <li><a class="reference internal" href="#datetime.time.hour"><code class="docutils literal notranslate">hour</code></a></li> <li><a class="reference internal" href="#datetime.time.minute"><code class="docutils literal notranslate">minute</code></a></li> <li><a class="reference internal" href="#datetime.time.second"><code class="docutils literal notranslate">second</code></a></li> <li><a class="reference internal" href="#datetime.time.microsecond"><code class="docutils literal notranslate">microsecond</code></a></li> <li><a class="reference internal" href="#datetime.time.tzinfo"><code class="docutils literal notranslate">tzinfo</code></a></li> <li><a class="reference internal" href="#datetime.time.fold"><code class="docutils literal notranslate">fold</code></a></li> <li><a class="reference internal" href="#datetime.time.fromisoformat"><code class="docutils literal notranslate">fromisoformat()</code></a></li> <li><a class="reference internal" href="#datetime.time.replace"><code class="docutils literal notranslate">replace()</code></a></li> <li><a class="reference internal" href="#datetime.time.isoformat"><code class="docutils literal notranslate">isoformat()</code></a></li> <li><a class="reference internal" href="#datetime.time.__str__"><code class="docutils literal notranslate">__str__()</code></a></li> <li><a class="reference internal" href="#datetime.time.strftime"><code class="docutils literal notranslate">strftime()</code></a></li> <li><a class="reference internal" href="#datetime.time.__format__"><code class="docutils literal notranslate">__format__()</code></a></li> <li><a class="reference internal" href="#datetime.time.utcoffset"><code class="docutils literal notranslate">utcoffset()</code></a></li> <li><a class="reference internal" href="#datetime.time.dst"><code class="docutils literal notranslate">dst()</code></a></li> <li><a class="reference internal" href="#datetime.time.tzname"><code class="docutils literal notranslate">tzname()</code></a></li> <li><a class="reference internal" href="#examples-of-usage-time">Examples of Usage: <code class="xref py py-class docutils literal notranslate">time</code></a></li> </ul> </li> <li><a class="reference internal" href="#tzinfo-objects"><code class="xref py py-class docutils literal notranslate">tzinfo</code> Objects</a><ul> <li><a class="reference internal" href="#datetime.tzinfo"><code class="docutils literal notranslate">tzinfo</code></a></li> <li><a class="reference internal" href="#datetime.tzinfo.utcoffset"><code class="docutils literal notranslate">utcoffset()</code></a></li> <li><a class="reference internal" href="#datetime.tzinfo.dst"><code class="docutils literal notranslate">dst()</code></a></li> <li><a class="reference internal" href="#datetime.tzinfo.tzname"><code class="docutils literal notranslate">tzname()</code></a></li> <li><a class="reference internal" href="#datetime.tzinfo.fromutc"><code class="docutils literal notranslate">fromutc()</code></a></li> </ul> </li> <li><a class="reference internal" href="#timezone-objects"><code class="xref py py-class docutils literal notranslate">timezone</code> Objects</a><ul> <li><a class="reference internal" href="#datetime.timezone"><code class="docutils literal notranslate">timezone</code></a></li> <li><a class="reference internal" href="#datetime.timezone.utcoffset"><code class="docutils literal notranslate">utcoffset()</code></a></li> <li><a class="reference internal" href="#datetime.timezone.tzname"><code class="docutils literal notranslate">tzname()</code></a></li> <li><a class="reference internal" href="#datetime.timezone.dst"><code class="docutils literal notranslate">dst()</code></a></li> <li><a class="reference internal" href="#datetime.timezone.fromutc"><code class="docutils literal notranslate">fromutc()</code></a></li> <li><a class="reference internal" href="#datetime.timezone.utc"><code class="docutils literal notranslate">utc</code></a></li> </ul> </li> <li><a class="reference internal" href="#strftime-and-strptime-behavior"><code class="xref py py-meth docutils literal notranslate">strftime()</code> and <code class="xref py py-meth docutils literal notranslate">strptime()</code> Behavior</a><ul> <li><a class="reference internal" href="#strftime-and-strptime-format-codes"><code class="xref py py-meth docutils literal notranslate">strftime()</code> and <code class="xref py py-meth docutils literal notranslate">strptime()</code> Format Codes</a></li> <li><a class="reference internal" href="#technical-detail">Technical Detail</a></li> </ul> </li> </ul> </li> </ul> </div> <div> <h4>Previous topic</h4> <a href="datatypes.html" title="previous chapter">Data Types</a> </div> <div> <h4>Next topic</h4> <a href="zoneinfo.html" title="next chapter"><code class="xref py py-mod docutils literal notranslate">zoneinfo</code> — IANA time zone support</a> </div> <div role="note" aria-label="source link"> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../bugs.html">Report a Bug</a></li> <li> <a href="https://github.com/python/cpython/blob/main/Doc/library/datetime.rst" rel="nofollow">Show Source </a> </li> </ul> </div> </nav> </div> </div> <div class="related" role="navigation" aria-label="Related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="../py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="zoneinfo.html" title="zoneinfo — IANA time zone support" accesskey="N">next</a> |</li> <li class="right" > <a href="datatypes.html" title="Data Types" accesskey="P">previous</a> |</li> <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="https://www.python.org/">Python</a> »</li> <li class="switchers"> <div class="language_switcher_placeholder"></div> <div class="version_switcher_placeholder"></div> </li> <li> </li> <li id="cpython-language-and-version"> <a href="../index.html">3.13.0 Documentation</a> » </li> <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li> <li class="nav-item nav-item-2"><a href="datatypes.html" accesskey="U">Data Types</a> »</li> <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate">datetime</code> — Basic date and time types</a></li> <li class="right"> <div class="inline-search" role="search"> <form class="inline-search" action="../search.html" method="get"> <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" /> <input type="submit" value="Go" /> </form> </div> | </li> <li class="right"> <label class="theme-selector-label"> Theme <select class="theme-selector" oninput="activateTheme(this.value)"> <option value="auto" selected>Auto</option> <option value="light">Light</option> <option value="dark">Dark</option> </select> </label> |</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <section id="module-datetime"> <h1><code class="xref py py-mod docutils literal notranslate">datetime</code> — Basic date and time types<a class="headerlink" href="#module-datetime" title="Link to this heading">¶</a></h1> Source code: <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.13/Lib/datetime.py">Lib/datetime.py</a> <hr class="docutils" /> The <code class="xref py py-mod docutils literal notranslate">datetime</code> module supplies classes for manipulating dates and times. While date and time arithmetic is supported, the focus of the implementation is on efficient attribute extraction for output formatting and manipulation. <div class="admonition tip"> Tip Skip to <a class="reference internal" href="#format-codes">the format codes</a>. </div> <div class="admonition seealso"> See also <dl class="simple"> <dt>Module <a class="reference internal" href="calendar.html#module-calendar" title="calendar: Functions for working with calendars, including some emulation of the Unix cal program."><code class="xref py py-mod docutils literal notranslate">calendar</code></a></dt><dd>General calendar related functions. </dd> <dt>Module <a class="reference internal" href="time.html#module-time" title="time: Time access and conversions."><code class="xref py py-mod docutils literal notranslate">time</code></a></dt><dd>Time access and conversions. </dd> <dt>Module <a class="reference internal" href="zoneinfo.html#module-zoneinfo" title="zoneinfo: IANA time zone support"><code class="xref py py-mod docutils literal notranslate">zoneinfo</code></a></dt><dd>Concrete time zones representing the IANA time zone database. </dd> <dt>Package <a class="reference external" href="https://dateutil.readthedocs.io/en/stable/">dateutil</a></dt><dd>Third-party library with expanded time zone and parsing support. </dd> <dt>Package <a class="extlink-pypi reference external" href="https://pypi.org/project/DateType/">DateType</a></dt><dd>Third-party library that introduces distinct static types to e.g. allow <a class="reference internal" href="../glossary.html#term-static-type-checker">static type checkers</a> to differentiate between naive and aware datetimes. </dd> </dl> </div> <section id="aware-and-naive-objects"> <h2>Aware and Naive Objects<a class="headerlink" href="#aware-and-naive-objects" title="Link to this heading">¶</a></h2> Date and time objects may be categorized as “aware” or “naive” depending on whether or not they include time zone information. With sufficient knowledge of applicable algorithmic and political time adjustments, such as time zone and daylight saving time information, an aware object can locate itself relative to other aware objects. An aware object represents a specific moment in time that is not open to interpretation. <a class="footnote-reference brackets" href="#id5" id="id1" role="doc-noteref">[1]</a> 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 time zone 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, <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> and <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> objects have an optional time zone information attribute, <code class="xref py py-attr docutils literal notranslate">tzinfo</code>, that can be set to an instance of a subclass of the abstract <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> class. These <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> objects capture information about the offset from UTC time, the time zone name, and whether daylight saving time is in effect. Only one concrete <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> class, the <a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate">timezone</code></a> class, is supplied by the <code class="xref py py-mod docutils literal notranslate">datetime</code> module. The <code class="xref py py-class docutils literal notranslate">timezone</code> class can represent simple time zones with fixed offsets from UTC, such as UTC itself or North American EST and EDT time zones. Supporting time zones 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. </section> <section id="constants"> <h2>Constants<a class="headerlink" href="#constants" title="Link to this heading">¶</a></h2> The <code class="xref py py-mod docutils literal notranslate">datetime</code> module exports the following constants: <dl class="py data"> <dt class="sig sig-object py" id="datetime.MINYEAR"> datetime.MINYEAR<a class="headerlink" href="#datetime.MINYEAR" title="Link to this definition">¶</a></dt> <dd>The smallest year number allowed in a <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> or <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object. <a class="reference internal" href="#datetime.MINYEAR" title="datetime.MINYEAR"><code class="xref py py-const docutils literal notranslate">MINYEAR</code></a> is 1. </dd></dl> <dl class="py data"> <dt class="sig sig-object py" id="datetime.MAXYEAR"> datetime.MAXYEAR<a class="headerlink" href="#datetime.MAXYEAR" title="Link to this definition">¶</a></dt> <dd>The largest year number allowed in a <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> or <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object. <a class="reference internal" href="#datetime.MAXYEAR" title="datetime.MAXYEAR"><code class="xref py py-const docutils literal notranslate">MAXYEAR</code></a> is 9999. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.UTC"> datetime.UTC<a class="headerlink" href="#datetime.UTC" title="Link to this definition">¶</a></dt> <dd>Alias for the UTC time zone singleton <a class="reference internal" href="#datetime.timezone.utc" title="datetime.timezone.utc"><code class="xref py py-attr docutils literal notranslate">datetime.timezone.utc</code></a>. <div class="versionadded"> Added in version 3.11. </div> </dd></dl> </section> <section id="available-types"> <h2>Available Types<a class="headerlink" href="#available-types" title="Link to this heading">¶</a></h2> <dl class="py class"> <dt class="sig sig-object py"> class datetime.date</dt> <dd>An idealized naive date, assuming the current Gregorian calendar always was, and always will be, in effect. Attributes: <a class="reference internal" href="#datetime.date.year" title="datetime.date.year"><code class="xref py py-attr docutils literal notranslate">year</code></a>, <a class="reference internal" href="#datetime.date.month" title="datetime.date.month"><code class="xref py py-attr docutils literal notranslate">month</code></a>, and <a class="reference internal" href="#datetime.date.day" title="datetime.date.day"><code class="xref py py-attr docutils literal notranslate">day</code></a>. </dd></dl> <dl class="py class"> <dt class="sig sig-object py"> class datetime.time</dt> <dd>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: <a class="reference internal" href="#datetime.time.hour" title="datetime.time.hour"><code class="xref py py-attr docutils literal notranslate">hour</code></a>, <a class="reference internal" href="#datetime.time.minute" title="datetime.time.minute"><code class="xref py py-attr docutils literal notranslate">minute</code></a>, <a class="reference internal" href="#datetime.time.second" title="datetime.time.second"><code class="xref py py-attr docutils literal notranslate">second</code></a>, <a class="reference internal" href="#datetime.time.microsecond" title="datetime.time.microsecond"><code class="xref py py-attr docutils literal notranslate">microsecond</code></a>, and <a class="reference internal" href="#datetime.time.tzinfo" title="datetime.time.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a>. </dd></dl> <dl class="py class"> <dt class="sig sig-object py"> class datetime.datetime</dt> <dd>A combination of a date and a time. Attributes: <a class="reference internal" href="#datetime.datetime.year" title="datetime.datetime.year"><code class="xref py py-attr docutils literal notranslate">year</code></a>, <a class="reference internal" href="#datetime.datetime.month" title="datetime.datetime.month"><code class="xref py py-attr docutils literal notranslate">month</code></a>, <a class="reference internal" href="#datetime.datetime.day" title="datetime.datetime.day"><code class="xref py py-attr docutils literal notranslate">day</code></a>, <a class="reference internal" href="#datetime.datetime.hour" title="datetime.datetime.hour"><code class="xref py py-attr docutils literal notranslate">hour</code></a>, <a class="reference internal" href="#datetime.datetime.minute" title="datetime.datetime.minute"><code class="xref py py-attr docutils literal notranslate">minute</code></a>, <a class="reference internal" href="#datetime.datetime.second" title="datetime.datetime.second"><code class="xref py py-attr docutils literal notranslate">second</code></a>, <a class="reference internal" href="#datetime.datetime.microsecond" title="datetime.datetime.microsecond"><code class="xref py py-attr docutils literal notranslate">microsecond</code></a>, and <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a>. </dd></dl> <dl class="py class"> <dt class="sig sig-object py"> class datetime.timedelta</dt> <dd>A duration expressing the difference between two <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> or <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> instances to microsecond resolution. </dd></dl> <dl class="py class"> <dt class="sig sig-object py"> class datetime.tzinfo</dt> <dd>An abstract base class for time zone information objects. These are used by the <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> and <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> classes to provide a customizable notion of time adjustment (for example, to account for time zone and/or daylight saving time). </dd></dl> <dl class="py class"> <dt class="sig sig-object py"> class datetime.timezone</dt> <dd>A class that implements the <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> abstract base class as a fixed offset from the UTC. <div class="versionadded"> Added in version 3.2. </div> </dd></dl> Objects of these types are immutable. Subclass relationships: <div class="highlight-python3 notranslate"><div class="highlight"><pre>object timedelta tzinfo timezone time date datetime </pre></div> </div> <section id="common-properties"> <h3>Common Properties<a class="headerlink" href="#common-properties" title="Link to this heading">¶</a></h3> The <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a>, <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a>, <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a>, and <a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate">timezone</code></a> types share these common features: <ul class="simple"> <li>Objects of these types are immutable.</li> <li>Objects of these types are <a class="reference internal" href="../glossary.html#term-hashable">hashable</a>, meaning that they can be used as dictionary keys.</li> <li>Objects of these types support efficient pickling via the <a class="reference internal" href="pickle.html#module-pickle" title="pickle: Convert Python objects to streams of bytes and back."><code class="xref py py-mod docutils literal notranslate">pickle</code></a> module.</li> </ul> </section> <section id="determining-if-an-object-is-aware-or-naive"> <h3>Determining if an Object is Aware or Naive<a class="headerlink" href="#determining-if-an-object-is-aware-or-naive" title="Link to this heading">¶</a></h3> Objects of the <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> type are always naive. An object of type <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> or <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> may be aware or naive. A <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object <code class="docutils literal notranslate">d</code> is aware if both of the following hold: <ol class="arabic simple"> <li><code class="docutils literal notranslate">d.tzinfo</code> is not <code class="docutils literal notranslate">None</code></li> <li><code class="docutils literal notranslate">d.tzinfo.utcoffset(d)</code> does not return <code class="docutils literal notranslate">None</code></li> </ol> Otherwise, <code class="docutils literal notranslate">d</code> is naive. A <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> object <code class="docutils literal notranslate">t</code> is aware if both of the following hold: <ol class="arabic simple"> <li><code class="docutils literal notranslate">t.tzinfo</code> is not <code class="docutils literal notranslate">None</code></li> <li><code class="docutils literal notranslate">t.tzinfo.utcoffset(None)</code> does not return <code class="docutils literal notranslate">None</code>.</li> </ol> Otherwise, <code class="docutils literal notranslate">t</code> is naive. The distinction between aware and naive doesn’t apply to <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> objects. </section> </section> <section id="timedelta-objects"> <h2><a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> Objects<a class="headerlink" href="#timedelta-objects" title="Link to this heading">¶</a></h2> A <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object represents a duration, the difference between two <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> or <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> instances. <dl class="py class"> <dt class="sig sig-object py" id="datetime.timedelta"> class datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)<a class="headerlink" href="#datetime.timedelta" title="Link to this definition">¶</a></dt> <dd>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: <ul class="simple"> <li>A millisecond is converted to 1000 microseconds.</li> <li>A minute is converted to 60 seconds.</li> <li>An hour is converted to 3600 seconds.</li> <li>A week is converted to 7 days.</li> </ul> and days, seconds and microseconds are then normalized so that the representation is unique, with <ul class="simple"> <li><code class="docutils literal notranslate">0 <= microseconds < 1000000</code></li> <li><code class="docutils literal notranslate">0 <= seconds < 3600*24</code> (the number of seconds in one day)</li> <li><code class="docutils literal notranslate">-999999999 <= days <= 999999999</code></li> </ul> The following example illustrates how any arguments besides days, seconds and microseconds are “merged” and normalized into those three resulting attributes: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import timedelta >>> delta = timedelta( ... days=50, ... seconds=27, ... microseconds=10, ... milliseconds=29000, ... minutes=5, ... hours=8, ... weeks=2 ... ) >>> # Only days, seconds, and microseconds remain >>> delta datetime.timedelta(days=64, seconds=29156, microseconds=10) </pre></div> </div> 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, <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate">OverflowError</code></a> is raised. Note that normalization of negative values may be surprising at first. For example: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import timedelta >>> d = timedelta(microseconds=-1) >>> (d.days, d.seconds, d.microseconds) (-1, 86399, 999999) </pre></div> </div> </dd></dl> Class attributes: <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.timedelta.min"> timedelta.min<a class="headerlink" href="#datetime.timedelta.min" title="Link to this definition">¶</a></dt> <dd>The most negative <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object, <code class="docutils literal notranslate">timedelta(-999999999)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.timedelta.max"> timedelta.max<a class="headerlink" href="#datetime.timedelta.max" title="Link to this definition">¶</a></dt> <dd>The most positive <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object, <code class="docutils literal notranslate">timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.timedelta.resolution"> timedelta.resolution<a class="headerlink" href="#datetime.timedelta.resolution" title="Link to this definition">¶</a></dt> <dd>The smallest possible difference between non-equal <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> objects, <code class="docutils literal notranslate">timedelta(microseconds=1)</code>. </dd></dl> Note that, because of normalization, <code class="docutils literal notranslate">timedelta.max</code> is greater than <code class="docutils literal notranslate">-timedelta.min</code>. <code class="docutils literal notranslate">-timedelta.max</code> is not representable as a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object. Instance attributes (read-only): <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.timedelta.days"> timedelta.days<a class="headerlink" href="#datetime.timedelta.days" title="Link to this definition">¶</a></dt> <dd>Between -999,999,999 and 999,999,999 inclusive. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.timedelta.seconds"> timedelta.seconds<a class="headerlink" href="#datetime.timedelta.seconds" title="Link to this definition">¶</a></dt> <dd>Between 0 and 86,399 inclusive. <div class="admonition caution"> Caution It is a somewhat common bug for code to unintentionally use this attribute when it is actually intended to get a <a class="reference internal" href="#datetime.timedelta.total_seconds" title="datetime.timedelta.total_seconds"><code class="xref py py-meth docutils literal notranslate">total_seconds()</code></a> value instead: <div class="highlight-pycon notranslate"><div class="highlight"><pre>>>> from datetime import timedelta >>> duration = timedelta(seconds=11235813) >>> duration.days, duration.seconds (130, 3813) >>> duration.total_seconds() 11235813.0 </pre></div> </div> </div> </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.timedelta.microseconds"> timedelta.microseconds<a class="headerlink" href="#datetime.timedelta.microseconds" title="Link to this definition">¶</a></dt> <dd>Between 0 and 999,999 inclusive. </dd></dl> Supported operations: <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Operation</th> <th class="head">Result</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">t1 = t2 + t3</code></td> <td>Sum of <code class="docutils literal notranslate">t2</code> and <code class="docutils literal notranslate">t3</code>. Afterwards <code class="docutils literal notranslate">t1 - t2 == t3</code> and <code class="docutils literal notranslate">t1 - t3 == t2</code> are true. (1)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">t1 = t2 - t3</code></td> <td>Difference of <code class="docutils literal notranslate">t2</code> and <code class="docutils literal notranslate">t3</code>. Afterwards <code class="docutils literal notranslate">t1 == t2 - t3</code> and <code class="docutils literal notranslate">t2 == t1 + t3</code> are true. (1)(6)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">t1 = t2 * i or t1 = i * t2</code></td> <td>Delta multiplied by an integer. Afterwards <code class="docutils literal notranslate">t1 // i == t2</code> is true, provided <code class="docutils literal notranslate">i != 0</code>.</td> </tr> <tr class="row-odd"><td></td> <td>In general, <code class="docutils literal notranslate">t1  * i == t1 * (i-1) + t1</code> is true. (1)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">t1 = t2 * f or t1 = f * t2</code></td> <td>Delta multiplied by a float. The result is rounded to the nearest multiple of timedelta.resolution using round-half-to-even.</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">f = t2 / t3</code></td> <td>Division (3) of overall duration <code class="docutils literal notranslate">t2</code> by interval unit <code class="docutils literal notranslate">t3</code>. Returns a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate">float</code></a> object.</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">t1 = t2 / f or t1 = t2 / i</code></td> <td>Delta divided by a float or an int. The result is rounded to the nearest multiple of timedelta.resolution using round-half-to-even.</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">t1 = t2 // i</code> or <code class="docutils literal notranslate">t1 = t2 // t3</code></td> <td>The floor is computed and the remainder (if any) is thrown away. In the second case, an integer is returned. (3)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">t1 = t2 % t3</code></td> <td>The remainder is computed as a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object. (3)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">q, r = divmod(t1, t2)</code></td> <td>Computes the quotient and the remainder: <code class="docutils literal notranslate">q = t1 // t2</code> (3) and <code class="docutils literal notranslate">r = t1 % t2</code>. <code class="docutils literal notranslate">q</code> is an integer and <code class="docutils literal notranslate">r</code> is a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object.</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">+t1</code></td> <td>Returns a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object with the same value. (2)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">-t1</code></td> <td>Equivalent to <code class="docutils literal notranslate">timedelta(-t1.days, -t1.seconds, -t1.microseconds)</code>, and to <code class="docutils literal notranslate">t1 * -1</code>. (1)(4)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">abs(t)</code></td> <td>Equivalent to <code class="docutils literal notranslate">+t</code> when <code class="docutils literal notranslate">t.days >= 0</code>, and to <code class="docutils literal notranslate">-t</code> when <code class="docutils literal notranslate">t.days < 0</code>. (2)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">str(t)</code></td> <td>Returns a string in the form <code class="docutils literal notranslate">[D day[s], ][H]H:MM:SS[.UUUUUU]</code>, where D is negative for negative <code class="docutils literal notranslate">t</code>. (5)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">repr(t)</code></td> <td>Returns a string representation of the <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object as a constructor call with canonical attribute values.</td> </tr> </tbody> </table> Notes: <ol class="arabic"> <li>This is exact but may overflow.</li> <li>This is exact and cannot overflow.</li> <li>Division by zero raises <a class="reference internal" href="exceptions.html#ZeroDivisionError" title="ZeroDivisionError"><code class="xref py py-exc docutils literal notranslate">ZeroDivisionError</code></a>.</li> <li><code class="docutils literal notranslate">-timedelta.max</code> is not representable as a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object.</li> <li>String representations of <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> objects are normalized similarly to their internal representation. This leads to somewhat unusual results for negative timedeltas. For example: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> timedelta(hours=-5) datetime.timedelta(days=-1, seconds=68400) >>> print(_) -1 day, 19:00:00 </pre></div> </div> </li> <li>The expression <code class="docutils literal notranslate">t2 - t3</code> will always be equal to the expression <code class="docutils literal notranslate">t2 + (-t3)</code> except when t3 is equal to <code class="docutils literal notranslate">timedelta.max</code>; in that case the former will produce a result while the latter will overflow.</li> </ol> In addition to the operations listed above, <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> objects support certain additions and subtractions with <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> and <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> objects (see below). <div class="versionchanged"> Changed in version 3.2: Floor division and true division of a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object by another <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object are now supported, as are remainder operations and the <a class="reference internal" href="functions.html#divmod" title="divmod"><code class="xref py py-func docutils literal notranslate">divmod()</code></a> function. True division and multiplication of a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object by a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate">float</code></a> object are now supported. </div> <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> objects support equality and order comparisons. In Boolean contexts, a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object is considered to be true if and only if it isn’t equal to <code class="docutils literal notranslate">timedelta(0)</code>. Instance methods: <dl class="py method"> <dt class="sig sig-object py" id="datetime.timedelta.total_seconds"> timedelta.total_seconds()<a class="headerlink" href="#datetime.timedelta.total_seconds" title="Link to this definition">¶</a></dt> <dd>Return the total number of seconds contained in the duration. Equivalent to <code class="docutils literal notranslate">td / timedelta(seconds=1)</code>. For interval units other than seconds, use the division form directly (e.g. <code class="docutils literal notranslate">td / timedelta(microseconds=1)</code>). Note that for very large time intervals (greater than 270 years on most platforms) this method will lose microsecond accuracy. <div class="versionadded"> Added in version 3.2. </div> </dd></dl> <section id="examples-of-usage-timedelta"> <h3>Examples of usage: <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a><a class="headerlink" href="#examples-of-usage-timedelta" title="Link to this heading">¶</a></h3> An additional example of normalization: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> # Components of another_year add up to exactly 365 days >>> from datetime import timedelta >>> year = timedelta(days=365) >>> another_year = timedelta(weeks=40, days=84, hours=23, ... minutes=50, seconds=600) >>> year == another_year True >>> year.total_seconds() 31536000.0 </pre></div> </div> Examples of <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> arithmetic: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import timedelta >>> year = timedelta(days=365) >>> ten_years = 10 * year >>> ten_years datetime.timedelta(days=3650) >>> ten_years.days // 365 10 >>> nine_years = ten_years - year >>> nine_years datetime.timedelta(days=3285) >>> three_years = nine_years // 3 >>> three_years, three_years.days // 365 (datetime.timedelta(days=1095), 3) </pre></div> </div> </section> </section> <section id="date-objects"> <h2><a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> Objects<a class="headerlink" href="#date-objects" title="Link to this heading">¶</a></h2> A <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> 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. <a class="footnote-reference brackets" href="#id6" id="id2" role="doc-noteref">[2]</a> <dl class="py class"> <dt class="sig sig-object py" id="datetime.date"> class datetime.date(year, month, day)<a class="headerlink" href="#datetime.date" title="Link to this definition">¶</a></dt> <dd>All arguments are required. Arguments must be integers, in the following ranges: <ul class="simple"> <li><code class="docutils literal notranslate">MINYEAR <= year <= MAXYEAR</code></li> <li><code class="docutils literal notranslate">1 <= month <= 12</code></li> <li><code class="docutils literal notranslate">1 <= day <= number of days in the given month and year</code></li> </ul> If an argument outside those ranges is given, <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> is raised. </dd></dl> Other constructors, all class methods: <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.today"> classmethod date.today()<a class="headerlink" href="#datetime.date.today" title="Link to this definition">¶</a></dt> <dd>Return the current local date. This is equivalent to <code class="docutils literal notranslate">date.fromtimestamp(time.time())</code>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.fromtimestamp"> classmethod date.fromtimestamp(timestamp)<a class="headerlink" href="#datetime.date.fromtimestamp" title="Link to this definition">¶</a></dt> <dd>Return the local date corresponding to the POSIX timestamp, such as is returned by <a class="reference internal" href="time.html#time.time" title="time.time"><code class="xref py py-func docutils literal notranslate">time.time()</code></a>. This may raise <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate">OverflowError</code></a>, if the timestamp is out of the range of values supported by the platform C <code class="xref c c-func docutils literal notranslate">localtime()</code> function, and <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate">OSError</code></a> on <code class="xref c c-func docutils literal notranslate">localtime()</code> failure. It’s common for this to be restricted to years from 1970 through 2038. Note that on non-POSIX systems that include leap seconds in their notion of a timestamp, leap seconds are ignored by <a class="reference internal" href="#datetime.date.fromtimestamp" title="datetime.date.fromtimestamp"><code class="xref py py-meth docutils literal notranslate">fromtimestamp()</code></a>. <div class="versionchanged"> Changed in version 3.3: Raise <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate">OverflowError</code></a> instead of <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> if the timestamp is out of the range of values supported by the platform C <code class="xref c c-func docutils literal notranslate">localtime()</code> function. Raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate">OSError</code></a> instead of <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> on <code class="xref c c-func docutils literal notranslate">localtime()</code> failure. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.fromordinal"> classmethod date.fromordinal(ordinal)<a class="headerlink" href="#datetime.date.fromordinal" title="Link to this definition">¶</a></dt> <dd>Return the date corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has ordinal 1. <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> is raised unless <code class="docutils literal notranslate">1 <= ordinal <= date.max.toordinal()</code>. For any date <code class="docutils literal notranslate">d</code>, <code class="docutils literal notranslate">date.fromordinal(d.toordinal()) == d</code>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.fromisoformat"> classmethod date.fromisoformat(date_string)<a class="headerlink" href="#datetime.date.fromisoformat" title="Link to this definition">¶</a></dt> <dd>Return a <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> corresponding to a date_string given in any valid ISO 8601 format, with the following exceptions: <ol class="arabic simple"> <li>Reduced precision dates are not currently supported (<code class="docutils literal notranslate">YYYY-MM</code>, <code class="docutils literal notranslate">YYYY</code>).</li> <li>Extended date representations are not currently supported (<code class="docutils literal notranslate">±YYYYYY-MM-DD</code>).</li> <li>Ordinal dates are not currently supported (<code class="docutils literal notranslate">YYYY-OOO</code>).</li> </ol> Examples: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import date >>> date.fromisoformat('2019-12-04') datetime.date(2019, 12, 4) >>> date.fromisoformat('20191204') datetime.date(2019, 12, 4) >>> date.fromisoformat('2021-W01-1') datetime.date(2021, 1, 4) </pre></div> </div> <div class="versionadded"> Added in version 3.7. </div> <div class="versionchanged"> Changed in version 3.11: Previously, this method only supported the format <code class="docutils literal notranslate">YYYY-MM-DD</code>. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.fromisocalendar"> classmethod date.fromisocalendar(year, week, day)<a class="headerlink" href="#datetime.date.fromisocalendar" title="Link to this definition">¶</a></dt> <dd>Return a <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> corresponding to the ISO calendar date specified by year, week and day. This is the inverse of the function <a class="reference internal" href="#datetime.date.isocalendar" title="datetime.date.isocalendar"><code class="xref py py-meth docutils literal notranslate">date.isocalendar()</code></a>. <div class="versionadded"> Added in version 3.8. </div> </dd></dl> Class attributes: <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.date.min"> date.min<a class="headerlink" href="#datetime.date.min" title="Link to this definition">¶</a></dt> <dd>The earliest representable date, <code class="docutils literal notranslate">date(MINYEAR, 1, 1)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.date.max"> date.max<a class="headerlink" href="#datetime.date.max" title="Link to this definition">¶</a></dt> <dd>The latest representable date, <code class="docutils literal notranslate">date(MAXYEAR, 12, 31)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.date.resolution"> date.resolution<a class="headerlink" href="#datetime.date.resolution" title="Link to this definition">¶</a></dt> <dd>The smallest possible difference between non-equal date objects, <code class="docutils literal notranslate">timedelta(days=1)</code>. </dd></dl> Instance attributes (read-only): <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.date.year"> date.year<a class="headerlink" href="#datetime.date.year" title="Link to this definition">¶</a></dt> <dd>Between <a class="reference internal" href="#datetime.MINYEAR" title="datetime.MINYEAR"><code class="xref py py-const docutils literal notranslate">MINYEAR</code></a> and <a class="reference internal" href="#datetime.MAXYEAR" title="datetime.MAXYEAR"><code class="xref py py-const docutils literal notranslate">MAXYEAR</code></a> inclusive. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.date.month"> date.month<a class="headerlink" href="#datetime.date.month" title="Link to this definition">¶</a></dt> <dd>Between 1 and 12 inclusive. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.date.day"> date.day<a class="headerlink" href="#datetime.date.day" title="Link to this definition">¶</a></dt> <dd>Between 1 and the number of days in the given month of the given year. </dd></dl> Supported operations: <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Operation</th> <th class="head">Result</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">date2 = date1 + timedelta</code></td> <td><code class="docutils literal notranslate">date2</code> will be <code class="docutils literal notranslate">timedelta.days</code> days after <code class="docutils literal notranslate">date1</code>. (1)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">date2 = date1 - timedelta</code></td> <td>Computes <code class="docutils literal notranslate">date2</code> such that <code class="docutils literal notranslate">date2 + timedelta == date1</code>. (2)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">timedelta = date1 - date2</code></td> <td>(3)</td> </tr> <tr class="row-odd"><td><div class="line-block"> <div class="line"><code class="docutils literal notranslate">date1 == date2</code></div> <div class="line"><code class="docutils literal notranslate">date1 != date2</code></div> </div> </td> <td>Equality comparison. (4)</td> </tr> <tr class="row-even"><td><div class="line-block"> <div class="line"><code class="docutils literal notranslate">date1 < date2</code></div> <div class="line"><code class="docutils literal notranslate">date1 > date2</code></div> <div class="line"><code class="docutils literal notranslate">date1 <= date2</code></div> <div class="line"><code class="docutils literal notranslate">date1 >= date2</code></div> </div> </td> <td>Order comparison. (5)</td> </tr> </tbody> </table> Notes: <ol class="arabic"> <li>date2 is moved forward in time if <code class="docutils literal notranslate">timedelta.days > 0</code>, or backward if <code class="docutils literal notranslate">timedelta.days < 0</code>. Afterward <code class="docutils literal notranslate">date2 - date1 == timedelta.days</code>. <code class="docutils literal notranslate">timedelta.seconds</code> and <code class="docutils literal notranslate">timedelta.microseconds</code> are ignored. <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate">OverflowError</code></a> is raised if <code class="docutils literal notranslate">date2.year</code> would be smaller than <a class="reference internal" href="#datetime.MINYEAR" title="datetime.MINYEAR"><code class="xref py py-const docutils literal notranslate">MINYEAR</code></a> or larger than <a class="reference internal" href="#datetime.MAXYEAR" title="datetime.MAXYEAR"><code class="xref py py-const docutils literal notranslate">MAXYEAR</code></a>.</li> <li><code class="docutils literal notranslate">timedelta.seconds</code> and <code class="docutils literal notranslate">timedelta.microseconds</code> are ignored.</li> <li>This is exact, and cannot overflow. <code class="docutils literal notranslate">timedelta.seconds</code> and <code class="docutils literal notranslate">timedelta.microseconds</code> are 0, and <code class="docutils literal notranslate">date2 + timedelta == date1</code> after.</li> <li><a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> objects are equal if they represent the same date. <code class="xref py py-class docutils literal notranslate">date</code> objects that are not also <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> instances are never equal to <code class="xref py py-class docutils literal notranslate">datetime</code> objects, even if they represent the same date. </li> <li>date1 is considered less than date2 when date1 precedes date2 in time. In other words, <code class="docutils literal notranslate">date1 < date2</code> if and only if <code class="docutils literal notranslate">date1.toordinal() < date2.toordinal()</code>. Order comparison between a <code class="xref py py-class docutils literal notranslate">date</code> object that is not also a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> instance and a <code class="xref py py-class docutils literal notranslate">datetime</code> object raises <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate">TypeError</code></a>. </li> </ol> <div class="versionchanged"> Changed in version 3.13: Comparison between <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object and an instance of the <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> subclass that is not a <code class="xref py py-class docutils literal notranslate">datetime</code> subclass no longer converts the latter to <code class="xref py py-class docutils literal notranslate">date</code>, ignoring the time part and the time zone. The default behavior can be changed by overriding the special comparison methods in subclasses. </div> In Boolean contexts, all <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> objects are considered to be true. Instance methods: <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.replace"> date.replace(year=self.year, month=self.month, day=self.day)<a class="headerlink" href="#datetime.date.replace" title="Link to this definition">¶</a></dt> <dd>Return a date with the same value, except for those parameters given new values by whichever keyword arguments are specified. Example: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import date >>> d = date(2002, 12, 31) >>> d.replace(day=26) datetime.date(2002, 12, 26) </pre></div> </div> <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> objects are also supported by generic function <a class="reference internal" href="copy.html#copy.replace" title="copy.replace"><code class="xref py py-func docutils literal notranslate">copy.replace()</code></a>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.timetuple"> date.timetuple()<a class="headerlink" href="#datetime.date.timetuple" title="Link to this definition">¶</a></dt> <dd>Return a <a class="reference internal" href="time.html#time.struct_time" title="time.struct_time"><code class="xref py py-class docutils literal notranslate">time.struct_time</code></a> such as returned by <a class="reference internal" href="time.html#time.localtime" title="time.localtime"><code class="xref py py-func docutils literal notranslate">time.localtime()</code></a>. The hours, minutes and seconds are 0, and the DST flag is -1. <code class="docutils literal notranslate">d.timetuple()</code> is equivalent to: <div class="highlight-python3 notranslate"><div class="highlight"><pre>time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1)) </pre></div> </div> where <code class="docutils literal notranslate">yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1</code> is the day number within the current year starting with 1 for January 1st. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.toordinal"> date.toordinal()<a class="headerlink" href="#datetime.date.toordinal" title="Link to this definition">¶</a></dt> <dd>Return the proleptic Gregorian ordinal of the date, where January 1 of year 1 has ordinal 1. For any <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> object <code class="docutils literal notranslate">d</code>, <code class="docutils literal notranslate">date.fromordinal(d.toordinal()) == d</code>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.weekday"> date.weekday()<a class="headerlink" href="#datetime.date.weekday" title="Link to this definition">¶</a></dt> <dd>Return the day of the week as an integer, where Monday is 0 and Sunday is 6. For example, <code class="docutils literal notranslate">date(2002, 12, 4).weekday() == 2</code>, a Wednesday. See also <a class="reference internal" href="#datetime.date.isoweekday" title="datetime.date.isoweekday"><code class="xref py py-meth docutils literal notranslate">isoweekday()</code></a>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.isoweekday"> date.isoweekday()<a class="headerlink" href="#datetime.date.isoweekday" title="Link to this definition">¶</a></dt> <dd>Return the day of the week as an integer, where Monday is 1 and Sunday is 7. For example, <code class="docutils literal notranslate">date(2002, 12, 4).isoweekday() == 3</code>, a Wednesday. See also <a class="reference internal" href="#datetime.date.weekday" title="datetime.date.weekday"><code class="xref py py-meth docutils literal notranslate">weekday()</code></a>, <a class="reference internal" href="#datetime.date.isocalendar" title="datetime.date.isocalendar"><code class="xref py py-meth docutils literal notranslate">isocalendar()</code></a>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.isocalendar"> date.isocalendar()<a class="headerlink" href="#datetime.date.isocalendar" title="Link to this definition">¶</a></dt> <dd>Return a <a class="reference internal" href="../glossary.html#term-named-tuple">named tuple</a> object with three components: <code class="docutils literal notranslate">year</code>, <code class="docutils literal notranslate">week</code> and <code class="docutils literal notranslate">weekday</code>. The ISO calendar is a widely used variant of the Gregorian calendar. <a class="footnote-reference brackets" href="#id7" id="id3" role="doc-noteref">[3]</a> The ISO year consists of 52 or 53 full weeks, and where a week starts on a Monday and ends on a Sunday. The first week of an ISO year is the first (Gregorian) calendar week of a year containing a Thursday. This is called week number 1, and the ISO year of that Thursday is the same as its Gregorian year. For example, 2004 begins on a Thursday, so the first week of ISO year 2004 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan 2004: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import date >>> date(2003, 12, 29).isocalendar() datetime.IsoCalendarDate(year=2004, week=1, weekday=1) >>> date(2004, 1, 4).isocalendar() datetime.IsoCalendarDate(year=2004, week=1, weekday=7) </pre></div> </div> <div class="versionchanged"> Changed in version 3.9: Result changed from a tuple to a <a class="reference internal" href="../glossary.html#term-named-tuple">named tuple</a>. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.isoformat"> date.isoformat()<a class="headerlink" href="#datetime.date.isoformat" title="Link to this definition">¶</a></dt> <dd>Return a string representing the date in ISO 8601 format, <code class="docutils literal notranslate">YYYY-MM-DD</code>: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import date >>> date(2002, 12, 4).isoformat() '2002-12-04' </pre></div> </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.__str__"> date.__str__()<a class="headerlink" href="#datetime.date.__str__" title="Link to this definition">¶</a></dt> <dd>For a date <code class="docutils literal notranslate">d</code>, <code class="docutils literal notranslate">str(d)</code> is equivalent to <code class="docutils literal notranslate">d.isoformat()</code>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.ctime"> date.ctime()<a class="headerlink" href="#datetime.date.ctime" title="Link to this definition">¶</a></dt> <dd>Return a string representing the date: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import date >>> date(2002, 12, 4).ctime() 'Wed Dec 4 00:00:00 2002' </pre></div> </div> <code class="docutils literal notranslate">d.ctime()</code> is equivalent to: <div class="highlight-python3 notranslate"><div class="highlight"><pre>time.ctime(time.mktime(d.timetuple())) </pre></div> </div> on platforms where the native C <code class="xref c c-func docutils literal notranslate">ctime()</code> function (which <a class="reference internal" href="time.html#time.ctime" title="time.ctime"><code class="xref py py-func docutils literal notranslate">time.ctime()</code></a> invokes, but which <a class="reference internal" href="#datetime.date.ctime" title="datetime.date.ctime"><code class="xref py py-meth docutils literal notranslate">date.ctime()</code></a> does not invoke) conforms to the C standard. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.strftime"> date.strftime(format)<a class="headerlink" href="#datetime.date.strftime" title="Link to this definition">¶</a></dt> <dd>Return a string representing the date, controlled by an explicit format string. Format codes referring to hours, minutes or seconds will see 0 values. See also <a class="reference internal" href="#strftime-strptime-behavior">strftime() and strptime() Behavior</a> and <a class="reference internal" href="#datetime.date.isoformat" title="datetime.date.isoformat"><code class="xref py py-meth docutils literal notranslate">date.isoformat()</code></a>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.date.__format__"> date.__format__(format)<a class="headerlink" href="#datetime.date.__format__" title="Link to this definition">¶</a></dt> <dd>Same as <a class="reference internal" href="#datetime.date.strftime" title="datetime.date.strftime"><code class="xref py py-meth docutils literal notranslate">date.strftime()</code></a>. This makes it possible to specify a format string for a <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> object in <a class="reference internal" href="../reference/lexical_analysis.html#f-strings">formatted string literals</a> and when using <a class="reference internal" href="stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal notranslate">str.format()</code></a>. See also <a class="reference internal" href="#strftime-strptime-behavior">strftime() and strptime() Behavior</a> and <a class="reference internal" href="#datetime.date.isoformat" title="datetime.date.isoformat"><code class="xref py py-meth docutils literal notranslate">date.isoformat()</code></a>. </dd></dl> <section id="examples-of-usage-date"> <h3>Examples of Usage: <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a><a class="headerlink" href="#examples-of-usage-date" title="Link to this heading">¶</a></h3> Example of counting days to an event: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> 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 </pre></div> </div> More examples of working with <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a>: <div class="highlight-pycon notranslate"><div class="highlight"><pre>>>> from datetime import date >>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001 >>> d datetime.date(2002, 3, 11) >>> # Methods related to formatting string output >>> d.isoformat() '2002-03-11' >>> d.strftime("%d/%m/%y") '11/03/02' >>> d.strftime("%A %d. %B %Y") 'Monday 11. March 2002' >>> d.ctime() 'Mon Mar 11 00:00:00 2002' >>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month") 'The day is 11, the month is March.' >>> # Methods for to extracting 'components' under different calendars >>> t = d.timetuple() >>> for i in t: ... 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: ... print(i) 2002 # ISO year 11 # ISO week number 1 # ISO day number ( 1 = Monday ) >>> # A date object is immutable; all operations produce a new object >>> d.replace(year=2005) datetime.date(2005, 3, 11) </pre></div> </div> </section> </section> <section id="datetime-objects"> <h2><a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> Objects<a class="headerlink" href="#datetime-objects" title="Link to this heading">¶</a></h2> A <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object is a single object containing all the information from a <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> object and a <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> object. Like a <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> object, <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> assumes the current Gregorian calendar extended in both directions; like a <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> object, <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> assumes there are exactly 3600*24 seconds in every day. Constructor: <dl class="py class"> <dt class="sig sig-object py" id="datetime.datetime"> class datetime.datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)<a class="headerlink" href="#datetime.datetime" title="Link to this definition">¶</a></dt> <dd>The year, month and day arguments are required. tzinfo may be <code class="docutils literal notranslate">None</code>, or an instance of a <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclass. The remaining arguments must be integers in the following ranges: <ul class="simple"> <li><code class="docutils literal notranslate">MINYEAR <= year <= MAXYEAR</code>,</li> <li><code class="docutils literal notranslate">1 <= month <= 12</code>,</li> <li><code class="docutils literal notranslate">1 <= day <= number of days in the given month and year</code>,</li> <li><code class="docutils literal notranslate">0 <= hour < 24</code>,</li> <li><code class="docutils literal notranslate">0 <= minute < 60</code>,</li> <li><code class="docutils literal notranslate">0 <= second < 60</code>,</li> <li><code class="docutils literal notranslate">0 <= microsecond < 1000000</code>,</li> <li><code class="docutils literal notranslate">fold in [0, 1]</code>.</li> </ul> If an argument outside those ranges is given, <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> is raised. <div class="versionchanged"> Changed in version 3.6: Added the fold parameter. </div> </dd></dl> Other constructors, all class methods: <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.today"> classmethod datetime.today()<a class="headerlink" href="#datetime.datetime.today" title="Link to this definition">¶</a></dt> <dd>Return the current local date and time, with <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> <code class="docutils literal notranslate">None</code>. Equivalent to: <div class="highlight-python3 notranslate"><div class="highlight"><pre>datetime.fromtimestamp(time.time()) </pre></div> </div> See also <a class="reference internal" href="#datetime.datetime.now" title="datetime.datetime.now"><code class="xref py py-meth docutils literal notranslate">now()</code></a>, <a class="reference internal" href="#datetime.datetime.fromtimestamp" title="datetime.datetime.fromtimestamp"><code class="xref py py-meth docutils literal notranslate">fromtimestamp()</code></a>. This method is functionally equivalent to <a class="reference internal" href="#datetime.datetime.now" title="datetime.datetime.now"><code class="xref py py-meth docutils literal notranslate">now()</code></a>, but without a <code class="docutils literal notranslate">tz</code> parameter. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.now"> classmethod datetime.now(tz=None)<a class="headerlink" href="#datetime.datetime.now" title="Link to this definition">¶</a></dt> <dd>Return the current local date and time. If optional argument tz is <code class="docutils literal notranslate">None</code> or not specified, this is like <a class="reference internal" href="#datetime.datetime.today" title="datetime.datetime.today"><code class="xref py py-meth docutils literal notranslate">today()</code></a>, but, if possible, supplies more precision than can be gotten from going through a <a class="reference internal" href="time.html#time.time" title="time.time"><code class="xref py py-func docutils literal notranslate">time.time()</code></a> timestamp (for example, this may be possible on platforms supplying the C <code class="xref c c-func docutils literal notranslate">gettimeofday()</code> function). If tz is not <code class="docutils literal notranslate">None</code>, it must be an instance of a <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclass, and the current date and time are converted to tz’s time zone. This function is preferred over <a class="reference internal" href="#datetime.datetime.today" title="datetime.datetime.today"><code class="xref py py-meth docutils literal notranslate">today()</code></a> and <a class="reference internal" href="#datetime.datetime.utcnow" title="datetime.datetime.utcnow"><code class="xref py py-meth docutils literal notranslate">utcnow()</code></a>. <div class="admonition note"> Note Subsequent calls to <code class="xref py py-meth docutils literal notranslate">datetime.now()</code> may return the same instant depending on the precision of the underlying clock. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.utcnow"> classmethod datetime.utcnow()<a class="headerlink" href="#datetime.datetime.utcnow" title="Link to this definition">¶</a></dt> <dd>Return the current UTC date and time, with <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> <code class="docutils literal notranslate">None</code>. This is like <a class="reference internal" href="#datetime.datetime.now" title="datetime.datetime.now"><code class="xref py py-meth docutils literal notranslate">now()</code></a>, but returns the current UTC date and time, as a naive <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object. An aware current UTC datetime can be obtained by calling <code class="docutils literal notranslate">datetime.now(timezone.utc)</code>. See also <a class="reference internal" href="#datetime.datetime.now" title="datetime.datetime.now"><code class="xref py py-meth docutils literal notranslate">now()</code></a>. <div class="admonition warning"> Warning Because naive <code class="docutils literal notranslate">datetime</code> objects are treated by many <code class="docutils literal notranslate">datetime</code> methods as local times, it is preferred to use aware datetimes to represent times in UTC. As such, the recommended way to create an object representing the current time in UTC is by calling <code class="docutils literal notranslate">datetime.now(timezone.utc)</code>. </div> <div class="deprecated"> Deprecated since version 3.12: Use <a class="reference internal" href="#datetime.datetime.now" title="datetime.datetime.now"><code class="xref py py-meth docutils literal notranslate">datetime.now()</code></a> with <a class="reference internal" href="#datetime.UTC" title="datetime.UTC"><code class="xref py py-attr docutils literal notranslate">UTC</code></a> instead. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.fromtimestamp"> classmethod datetime.fromtimestamp(timestamp, tz=None)<a class="headerlink" href="#datetime.datetime.fromtimestamp" title="Link to this definition">¶</a></dt> <dd>Return the local date and time corresponding to the POSIX timestamp, such as is returned by <a class="reference internal" href="time.html#time.time" title="time.time"><code class="xref py py-func docutils literal notranslate">time.time()</code></a>. If optional argument tz is <code class="docutils literal notranslate">None</code> or not specified, the timestamp is converted to the platform’s local date and time, and the returned <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object is naive. If tz is not <code class="docutils literal notranslate">None</code>, it must be an instance of a <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclass, and the timestamp is converted to tz’s time zone. <a class="reference internal" href="#datetime.datetime.fromtimestamp" title="datetime.datetime.fromtimestamp"><code class="xref py py-meth docutils literal notranslate">fromtimestamp()</code></a> may raise <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate">OverflowError</code></a>, if the timestamp is out of the range of values supported by the platform C <code class="xref c c-func docutils literal notranslate">localtime()</code> or <code class="xref c c-func docutils literal notranslate">gmtime()</code> functions, and <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate">OSError</code></a> on <code class="xref c c-func docutils literal notranslate">localtime()</code> or <code class="xref c c-func docutils literal notranslate">gmtime()</code> failure. It’s common for this to be restricted to years in 1970 through 2038. Note that on non-POSIX systems that include leap seconds in their notion of a timestamp, leap seconds are ignored by <a class="reference internal" href="#datetime.datetime.fromtimestamp" title="datetime.datetime.fromtimestamp"><code class="xref py py-meth docutils literal notranslate">fromtimestamp()</code></a>, and then it’s possible to have two timestamps differing by a second that yield identical <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> objects. This method is preferred over <a class="reference internal" href="#datetime.datetime.utcfromtimestamp" title="datetime.datetime.utcfromtimestamp"><code class="xref py py-meth docutils literal notranslate">utcfromtimestamp()</code></a>. <div class="versionchanged"> Changed in version 3.3: Raise <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate">OverflowError</code></a> instead of <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> if the timestamp is out of the range of values supported by the platform C <code class="xref c c-func docutils literal notranslate">localtime()</code> or <code class="xref c c-func docutils literal notranslate">gmtime()</code> functions. Raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate">OSError</code></a> instead of <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> on <code class="xref c c-func docutils literal notranslate">localtime()</code> or <code class="xref c c-func docutils literal notranslate">gmtime()</code> failure. </div> <div class="versionchanged"> Changed in version 3.6: <a class="reference internal" href="#datetime.datetime.fromtimestamp" title="datetime.datetime.fromtimestamp"><code class="xref py py-meth docutils literal notranslate">fromtimestamp()</code></a> may return instances with <a class="reference internal" href="#datetime.datetime.fold" title="datetime.datetime.fold"><code class="xref py py-attr docutils literal notranslate">fold</code></a> set to 1. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.utcfromtimestamp"> classmethod datetime.utcfromtimestamp(timestamp)<a class="headerlink" href="#datetime.datetime.utcfromtimestamp" title="Link to this definition">¶</a></dt> <dd>Return the UTC <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> corresponding to the POSIX timestamp, with <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> <code class="docutils literal notranslate">None</code>. (The resulting object is naive.) This may raise <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate">OverflowError</code></a>, if the timestamp is out of the range of values supported by the platform C <code class="xref c c-func docutils literal notranslate">gmtime()</code> function, and <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate">OSError</code></a> on <code class="xref c c-func docutils literal notranslate">gmtime()</code> failure. It’s common for this to be restricted to years in 1970 through 2038. To get an aware <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object, call <a class="reference internal" href="#datetime.datetime.fromtimestamp" title="datetime.datetime.fromtimestamp"><code class="xref py py-meth docutils literal notranslate">fromtimestamp()</code></a>: <div class="highlight-python3 notranslate"><div class="highlight"><pre>datetime.fromtimestamp(timestamp, timezone.utc) </pre></div> </div> On the POSIX compliant platforms, it is equivalent to the following expression: <div class="highlight-python3 notranslate"><div class="highlight"><pre>datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp) </pre></div> </div> except the latter formula always supports the full years range: between <a class="reference internal" href="#datetime.MINYEAR" title="datetime.MINYEAR"><code class="xref py py-const docutils literal notranslate">MINYEAR</code></a> and <a class="reference internal" href="#datetime.MAXYEAR" title="datetime.MAXYEAR"><code class="xref py py-const docutils literal notranslate">MAXYEAR</code></a> inclusive. <div class="admonition warning"> Warning Because naive <code class="docutils literal notranslate">datetime</code> objects are treated by many <code class="docutils literal notranslate">datetime</code> methods as local times, it is preferred to use aware datetimes to represent times in UTC. As such, the recommended way to create an object representing a specific timestamp in UTC is by calling <code class="docutils literal notranslate">datetime.fromtimestamp(timestamp, tz=timezone.utc)</code>. </div> <div class="versionchanged"> Changed in version 3.3: Raise <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate">OverflowError</code></a> instead of <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> if the timestamp is out of the range of values supported by the platform C <code class="xref c c-func docutils literal notranslate">gmtime()</code> function. Raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate">OSError</code></a> instead of <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> on <code class="xref c c-func docutils literal notranslate">gmtime()</code> failure. </div> <div class="deprecated"> Deprecated since version 3.12: Use <a class="reference internal" href="#datetime.datetime.fromtimestamp" title="datetime.datetime.fromtimestamp"><code class="xref py py-meth docutils literal notranslate">datetime.fromtimestamp()</code></a> with <a class="reference internal" href="#datetime.UTC" title="datetime.UTC"><code class="xref py py-attr docutils literal notranslate">UTC</code></a> instead. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.fromordinal"> classmethod datetime.fromordinal(ordinal)<a class="headerlink" href="#datetime.datetime.fromordinal" title="Link to this definition">¶</a></dt> <dd>Return the <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has ordinal 1. <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> is raised unless <code class="docutils literal notranslate">1 <= ordinal <= datetime.max.toordinal()</code>. The hour, minute, second and microsecond of the result are all 0, and <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> is <code class="docutils literal notranslate">None</code>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.combine"> classmethod datetime.combine(date, time, tzinfo=time.tzinfo)<a class="headerlink" href="#datetime.datetime.combine" title="Link to this definition">¶</a></dt> <dd>Return a new <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object whose date components are equal to the given <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> object’s, and whose time components are equal to the given <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> object’s. If the tzinfo argument is provided, its value is used to set the <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> attribute of the result, otherwise the <a class="reference internal" href="#datetime.time.tzinfo" title="datetime.time.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> attribute of the time argument is used. If the date argument is a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object, its time components and <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> attributes are ignored. For any <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object <code class="docutils literal notranslate">d</code>, <code class="docutils literal notranslate">d == datetime.combine(d.date(), d.time(), d.tzinfo)</code>. <div class="versionchanged"> Changed in version 3.6: Added the tzinfo argument. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.fromisoformat"> classmethod datetime.fromisoformat(date_string)<a class="headerlink" href="#datetime.datetime.fromisoformat" title="Link to this definition">¶</a></dt> <dd>Return a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> corresponding to a date_string in any valid ISO 8601 format, with the following exceptions: <ol class="arabic simple"> <li>Time zone offsets may have fractional seconds.</li> <li>The <code class="docutils literal notranslate">T</code> separator may be replaced by any single unicode character.</li> <li>Fractional hours and minutes are not supported.</li> <li>Reduced precision dates are not currently supported (<code class="docutils literal notranslate">YYYY-MM</code>, <code class="docutils literal notranslate">YYYY</code>).</li> <li>Extended date representations are not currently supported (<code class="docutils literal notranslate">±YYYYYY-MM-DD</code>).</li> <li>Ordinal dates are not currently supported (<code class="docutils literal notranslate">YYYY-OOO</code>).</li> </ol> Examples: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import datetime >>> datetime.fromisoformat('2011-11-04') datetime.datetime(2011, 11, 4, 0, 0) >>> datetime.fromisoformat('20111104') datetime.datetime(2011, 11, 4, 0, 0) >>> datetime.fromisoformat('2011-11-04T00:05:23') datetime.datetime(2011, 11, 4, 0, 5, 23) >>> datetime.fromisoformat('2011-11-04T00:05:23Z') datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc) >>> datetime.fromisoformat('20111104T000523') datetime.datetime(2011, 11, 4, 0, 5, 23) >>> datetime.fromisoformat('2011-W01-2T00:05:23.283') datetime.datetime(2011, 1, 4, 0, 5, 23, 283000) >>> datetime.fromisoformat('2011-11-04 00:05:23.283') datetime.datetime(2011, 11, 4, 0, 5, 23, 283000) >>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00') datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc) >>> datetime.fromisoformat('2011-11-04T00:05:23+04:00') datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400))) </pre></div> </div> <div class="versionadded"> Added in version 3.7. </div> <div class="versionchanged"> Changed in version 3.11: Previously, this method only supported formats that could be emitted by <a class="reference internal" href="#datetime.date.isoformat" title="datetime.date.isoformat"><code class="xref py py-meth docutils literal notranslate">date.isoformat()</code></a> or <a class="reference internal" href="#datetime.datetime.isoformat" title="datetime.datetime.isoformat"><code class="xref py py-meth docutils literal notranslate">datetime.isoformat()</code></a>. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.fromisocalendar"> classmethod datetime.fromisocalendar(year, week, day)<a class="headerlink" href="#datetime.datetime.fromisocalendar" title="Link to this definition">¶</a></dt> <dd>Return a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> corresponding to the ISO calendar date specified by year, week and day. The non-date components of the datetime are populated with their normal default values. This is the inverse of the function <a class="reference internal" href="#datetime.datetime.isocalendar" title="datetime.datetime.isocalendar"><code class="xref py py-meth docutils literal notranslate">datetime.isocalendar()</code></a>. <div class="versionadded"> Added in version 3.8. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.strptime"> classmethod datetime.strptime(date_string, format)<a class="headerlink" href="#datetime.datetime.strptime" title="Link to this definition">¶</a></dt> <dd>Return a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> corresponding to date_string, parsed according to format. If format does not contain microseconds or time zone information, this is equivalent to: <div class="highlight-python3 notranslate"><div class="highlight"><pre>datetime(*(time.strptime(date_string, format)[0:6])) </pre></div> </div> <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> is raised if the date_string and format can’t be parsed by <a class="reference internal" href="time.html#time.strptime" title="time.strptime"><code class="xref py py-func docutils literal notranslate">time.strptime()</code></a> or if it returns a value which isn’t a time tuple. See also <a class="reference internal" href="#strftime-strptime-behavior">strftime() and strptime() Behavior</a> and <a class="reference internal" href="#datetime.datetime.fromisoformat" title="datetime.datetime.fromisoformat"><code class="xref py py-meth docutils literal notranslate">datetime.fromisoformat()</code></a>. <div class="versionchanged"> Changed in version 3.13: If format specifies a day of month without a year a <a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate">DeprecationWarning</code></a> is now emitted. This is to avoid a quadrennial leap year bug in code seeking to parse only a month and day as the default year used in absence of one in the format is not a leap year. Such format values may raise an error as of Python 3.15. The workaround is to always include a year in your format. If parsing date_string values that do not have a year, explicitly add a year that is a leap year before parsing: <div class="highlight-pycon notranslate"><div class="highlight"><pre>>>> from datetime import datetime >>> date_string = "02/29" >>> when = datetime.strptime(f"{date_string};1984", "%m/%d;%Y") # Avoids leap year bug. >>> when.strftime("%B %d") 'February 29' </pre></div> </div> </div> </dd></dl> Class attributes: <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.datetime.min"> datetime.min<a class="headerlink" href="#datetime.datetime.min" title="Link to this definition">¶</a></dt> <dd>The earliest representable <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a>, <code class="docutils literal notranslate">datetime(MINYEAR, 1, 1, tzinfo=None)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.datetime.max"> datetime.max<a class="headerlink" href="#datetime.datetime.max" title="Link to this definition">¶</a></dt> <dd>The latest representable <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a>, <code class="docutils literal notranslate">datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.datetime.resolution"> datetime.resolution<a class="headerlink" href="#datetime.datetime.resolution" title="Link to this definition">¶</a></dt> <dd>The smallest possible difference between non-equal <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> objects, <code class="docutils literal notranslate">timedelta(microseconds=1)</code>. </dd></dl> Instance attributes (read-only): <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.datetime.year"> datetime.year<a class="headerlink" href="#datetime.datetime.year" title="Link to this definition">¶</a></dt> <dd>Between <a class="reference internal" href="#datetime.MINYEAR" title="datetime.MINYEAR"><code class="xref py py-const docutils literal notranslate">MINYEAR</code></a> and <a class="reference internal" href="#datetime.MAXYEAR" title="datetime.MAXYEAR"><code class="xref py py-const docutils literal notranslate">MAXYEAR</code></a> inclusive. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.datetime.month"> datetime.month<a class="headerlink" href="#datetime.datetime.month" title="Link to this definition">¶</a></dt> <dd>Between 1 and 12 inclusive. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.datetime.day"> datetime.day<a class="headerlink" href="#datetime.datetime.day" title="Link to this definition">¶</a></dt> <dd>Between 1 and the number of days in the given month of the given year. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.datetime.hour"> datetime.hour<a class="headerlink" href="#datetime.datetime.hour" title="Link to this definition">¶</a></dt> <dd>In <code class="docutils literal notranslate">range(24)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.datetime.minute"> datetime.minute<a class="headerlink" href="#datetime.datetime.minute" title="Link to this definition">¶</a></dt> <dd>In <code class="docutils literal notranslate">range(60)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.datetime.second"> datetime.second<a class="headerlink" href="#datetime.datetime.second" title="Link to this definition">¶</a></dt> <dd>In <code class="docutils literal notranslate">range(60)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.datetime.microsecond"> datetime.microsecond<a class="headerlink" href="#datetime.datetime.microsecond" title="Link to this definition">¶</a></dt> <dd>In <code class="docutils literal notranslate">range(1000000)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.datetime.tzinfo"> datetime.tzinfo<a class="headerlink" href="#datetime.datetime.tzinfo" title="Link to this definition">¶</a></dt> <dd>The object passed as the tzinfo argument to the <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> constructor, or <code class="docutils literal notranslate">None</code> if none was passed. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.datetime.fold"> datetime.fold<a class="headerlink" href="#datetime.datetime.fold" title="Link to this definition">¶</a></dt> <dd>In <code class="docutils literal notranslate">[0, 1]</code>. Used to disambiguate wall times during a repeated interval. (A repeated interval occurs when clocks are rolled back at the end of daylight saving time or when the UTC offset for the current zone is decreased for political reasons.) The values 0 and 1 represent, respectively, the earlier and later of the two moments with the same wall time representation. <div class="versionadded"> Added in version 3.6. </div> </dd></dl> Supported operations: <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Operation</th> <th class="head">Result</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">datetime2 = datetime1 + timedelta</code></td> <td>(1)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">datetime2 = datetime1 - timedelta</code></td> <td>(2)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">timedelta = datetime1 - datetime2</code></td> <td>(3)</td> </tr> <tr class="row-odd"><td><div class="line-block"> <div class="line"><code class="docutils literal notranslate">datetime1 == datetime2</code></div> <div class="line"><code class="docutils literal notranslate">datetime1 != datetime2</code></div> </div> </td> <td>Equality comparison. (4)</td> </tr> <tr class="row-even"><td><div class="line-block"> <div class="line"><code class="docutils literal notranslate">datetime1 < datetime2</code></div> <div class="line"><code class="docutils literal notranslate">datetime1 > datetime2</code></div> <div class="line"><code class="docutils literal notranslate">datetime1 <= datetime2</code></div> <div class="line"><code class="docutils literal notranslate">datetime1 >= datetime2</code></div> </div> </td> <td>Order comparison. (5)</td> </tr> </tbody> </table> <ol class="arabic"> <li><code class="docutils literal notranslate">datetime2</code> is a duration of <code class="docutils literal notranslate">timedelta</code> removed from <code class="docutils literal notranslate">datetime1</code>, moving forward in time if <code class="docutils literal notranslate">timedelta.days > 0</code>, or backward if <code class="docutils literal notranslate">timedelta.days < 0</code>. The result has the same <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> attribute as the input datetime, and <code class="docutils literal notranslate">datetime2 - datetime1 == timedelta</code> after. <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate">OverflowError</code></a> is raised if <code class="docutils literal notranslate">datetime2.year</code> would be smaller than <a class="reference internal" href="#datetime.MINYEAR" title="datetime.MINYEAR"><code class="xref py py-const docutils literal notranslate">MINYEAR</code></a> or larger than <a class="reference internal" href="#datetime.MAXYEAR" title="datetime.MAXYEAR"><code class="xref py py-const docutils literal notranslate">MAXYEAR</code></a>. Note that no time zone adjustments are done even if the input is an aware object.</li> <li>Computes the <code class="docutils literal notranslate">datetime2</code> such that <code class="docutils literal notranslate">datetime2 + timedelta == datetime1</code>. As for addition, the result has the same <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> attribute as the input datetime, and no time zone adjustments are done even if the input is aware.</li> <li>Subtraction of a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> from a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> is defined only if both operands are naive, or if both are aware. If one is aware and the other is naive, <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate">TypeError</code></a> is raised. If both are naive, or both are aware and have the same <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> attribute, the <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> attributes are ignored, and the result is a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object <code class="docutils literal notranslate">t</code> such that <code class="docutils literal notranslate">datetime2 + t == datetime1</code>. No time zone adjustments are done in this case. If both are aware and have different <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> attributes, <code class="docutils literal notranslate">a-b</code> acts as if <code class="docutils literal notranslate">a</code> and <code class="docutils literal notranslate">b</code> were first converted to naive UTC datetimes. The result is <code class="docutils literal notranslate">(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset())</code> except that the implementation never overflows. </li> <li><a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> objects are equal if they represent the same date and time, taking into account the time zone. Naive and aware <code class="xref py py-class docutils literal notranslate">datetime</code> objects are never equal. If both comparands are aware, and have the same <code class="xref py py-attr docutils literal notranslate">tzinfo</code> attribute, the <code class="xref py py-attr docutils literal notranslate">tzinfo</code> and <a class="reference internal" href="#datetime.datetime.fold" title="datetime.datetime.fold"><code class="xref py py-attr docutils literal notranslate">fold</code></a> attributes are ignored and the base datetimes are compared. If both comparands are aware and have different <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> attributes, the comparison acts as comparands were first converted to UTC datetimes except that the implementation never overflows. <code class="xref py py-class docutils literal notranslate">datetime</code> instances in a repeated interval are never equal to <code class="xref py py-class docutils literal notranslate">datetime</code> instances in other time zone. </li> <li>datetime1 is considered less than datetime2 when datetime1 precedes datetime2 in time, taking into account the time zone. Order comparison between naive and aware <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> objects raises <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate">TypeError</code></a>. If both comparands are aware, and have the same <code class="xref py py-attr docutils literal notranslate">tzinfo</code> attribute, the <code class="xref py py-attr docutils literal notranslate">tzinfo</code> and <a class="reference internal" href="#datetime.datetime.fold" title="datetime.datetime.fold"><code class="xref py py-attr docutils literal notranslate">fold</code></a> attributes are ignored and the base datetimes are compared. If both comparands are aware and have different <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> attributes, the comparison acts as comparands were first converted to UTC datetimes except that the implementation never overflows. </li> </ol> <div class="versionchanged"> Changed in version 3.3: Equality comparisons between aware and naive <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> instances don’t raise <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate">TypeError</code></a>. </div> <div class="versionchanged"> Changed in version 3.13: Comparison between <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object and an instance of the <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> subclass that is not a <code class="xref py py-class docutils literal notranslate">datetime</code> subclass no longer converts the latter to <code class="xref py py-class docutils literal notranslate">date</code>, ignoring the time part and the time zone. The default behavior can be changed by overriding the special comparison methods in subclasses. </div> Instance methods: <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.date"> datetime.date()<a class="headerlink" href="#datetime.datetime.date" title="Link to this definition">¶</a></dt> <dd>Return <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> object with same year, month and day. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.time"> datetime.time()<a class="headerlink" href="#datetime.datetime.time" title="Link to this definition">¶</a></dt> <dd>Return <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> object with same hour, minute, second, microsecond and fold. <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> is <code class="docutils literal notranslate">None</code>. See also method <a class="reference internal" href="#datetime.datetime.timetz" title="datetime.datetime.timetz"><code class="xref py py-meth docutils literal notranslate">timetz()</code></a>. <div class="versionchanged"> Changed in version 3.6: The fold value is copied to the returned <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> object. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.timetz"> datetime.timetz()<a class="headerlink" href="#datetime.datetime.timetz" title="Link to this definition">¶</a></dt> <dd>Return <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> object with same hour, minute, second, microsecond, fold, and tzinfo attributes. See also method <a class="reference internal" href="time.html#module-time" title="time: Time access and conversions."><code class="xref py py-meth docutils literal notranslate">time()</code></a>. <div class="versionchanged"> Changed in version 3.6: The fold value is copied to the returned <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> object. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.replace"> datetime.replace(year=self.year, month=self.month, day=self.day, hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)<a class="headerlink" href="#datetime.datetime.replace" title="Link to this definition">¶</a></dt> <dd>Return a datetime with the same attributes, except for those attributes given new values by whichever keyword arguments are specified. Note that <code class="docutils literal notranslate">tzinfo=None</code> can be specified to create a naive datetime from an aware datetime with no conversion of date and time data. <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> objects are also supported by generic function <a class="reference internal" href="copy.html#copy.replace" title="copy.replace"><code class="xref py py-func docutils literal notranslate">copy.replace()</code></a>. <div class="versionchanged"> Changed in version 3.6: Added the fold parameter. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.astimezone"> datetime.astimezone(tz=None)<a class="headerlink" href="#datetime.datetime.astimezone" title="Link to this definition">¶</a></dt> <dd>Return a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object with new <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> attribute tz, adjusting the date and time data so the result is the same UTC time as self, but in tz’s local time. If provided, tz must be an instance of a <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclass, and its <a class="reference internal" href="#datetime.datetime.utcoffset" title="datetime.datetime.utcoffset"><code class="xref py py-meth docutils literal notranslate">utcoffset()</code></a> and <a class="reference internal" href="#datetime.datetime.dst" title="datetime.datetime.dst"><code class="xref py py-meth docutils literal notranslate">dst()</code></a> methods must not return <code class="docutils literal notranslate">None</code>. If self is naive, it is presumed to represent time in the system time zone. If called without arguments (or with <code class="docutils literal notranslate">tz=None</code>) the system local time zone is assumed for the target time zone. The <code class="docutils literal notranslate">.tzinfo</code> attribute of the converted datetime instance will be set to an instance of <a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate">timezone</code></a> with the zone name and offset obtained from the OS. If <code class="docutils literal notranslate">self.tzinfo</code> is tz, <code class="docutils literal notranslate">self.astimezone(tz)</code> is equal to self: no adjustment of date or time data is performed. Else the result is local time in the time zone tz, representing the same UTC time as self: after <code class="docutils literal notranslate">astz = dt.astimezone(tz)</code>, <code class="docutils literal notranslate">astz - astz.utcoffset()</code> will have the same date and time data as <code class="docutils literal notranslate">dt - dt.utcoffset()</code>. If you merely want to attach a <a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate">timezone</code></a> object tz to a datetime dt without adjustment of date and time data, use <code class="docutils literal notranslate">dt.replace(tzinfo=tz)</code>. If you merely want to remove the <code class="xref py py-class docutils literal notranslate">timezone</code> object from an aware datetime dt without conversion of date and time data, use <code class="docutils literal notranslate">dt.replace(tzinfo=None)</code>. Note that the default <a class="reference internal" href="#datetime.tzinfo.fromutc" title="datetime.tzinfo.fromutc"><code class="xref py py-meth docutils literal notranslate">tzinfo.fromutc()</code></a> method can be overridden in a <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclass to affect the result returned by <a class="reference internal" href="#datetime.datetime.astimezone" title="datetime.datetime.astimezone"><code class="xref py py-meth docutils literal notranslate">astimezone()</code></a>. Ignoring error cases, <a class="reference internal" href="#datetime.datetime.astimezone" title="datetime.datetime.astimezone"><code class="xref py py-meth docutils literal notranslate">astimezone()</code></a> acts like: <div class="highlight-python3 notranslate"><div class="highlight"><pre>def astimezone(self, tz): if self.tzinfo is tz: return self # Convert self to UTC, and attach the new timezone object. utc = (self - self.utcoffset()).replace(tzinfo=tz) # Convert from UTC to tz's local time. return tz.fromutc(utc) </pre></div> </div> <div class="versionchanged"> Changed in version 3.3: tz now can be omitted. </div> <div class="versionchanged"> Changed in version 3.6: The <a class="reference internal" href="#datetime.datetime.astimezone" title="datetime.datetime.astimezone"><code class="xref py py-meth docutils literal notranslate">astimezone()</code></a> method can now be called on naive instances that are presumed to represent system local time. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.utcoffset"> datetime.utcoffset()<a class="headerlink" href="#datetime.datetime.utcoffset" title="Link to this definition">¶</a></dt> <dd>If <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> is <code class="docutils literal notranslate">None</code>, returns <code class="docutils literal notranslate">None</code>, else returns <code class="docutils literal notranslate">self.tzinfo.utcoffset(self)</code>, and raises an exception if the latter doesn’t return <code class="docutils literal notranslate">None</code> or a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object with magnitude less than one day. <div class="versionchanged"> Changed in version 3.7: The UTC offset is not restricted to a whole number of minutes. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.dst"> datetime.dst()<a class="headerlink" href="#datetime.datetime.dst" title="Link to this definition">¶</a></dt> <dd>If <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> is <code class="docutils literal notranslate">None</code>, returns <code class="docutils literal notranslate">None</code>, else returns <code class="docutils literal notranslate">self.tzinfo.dst(self)</code>, and raises an exception if the latter doesn’t return <code class="docutils literal notranslate">None</code> or a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object with magnitude less than one day. <div class="versionchanged"> Changed in version 3.7: The DST offset is not restricted to a whole number of minutes. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.tzname"> datetime.tzname()<a class="headerlink" href="#datetime.datetime.tzname" title="Link to this definition">¶</a></dt> <dd>If <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> is <code class="docutils literal notranslate">None</code>, returns <code class="docutils literal notranslate">None</code>, else returns <code class="docutils literal notranslate">self.tzinfo.tzname(self)</code>, raises an exception if the latter doesn’t return <code class="docutils literal notranslate">None</code> or a string object, </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.timetuple"> datetime.timetuple()<a class="headerlink" href="#datetime.datetime.timetuple" title="Link to this definition">¶</a></dt> <dd>Return a <a class="reference internal" href="time.html#time.struct_time" title="time.struct_time"><code class="xref py py-class docutils literal notranslate">time.struct_time</code></a> such as returned by <a class="reference internal" href="time.html#time.localtime" title="time.localtime"><code class="xref py py-func docutils literal notranslate">time.localtime()</code></a>. <code class="docutils literal notranslate">d.timetuple()</code> is equivalent to: <div class="highlight-python3 notranslate"><div class="highlight"><pre>time.struct_time((d.year, d.month, d.day, d.hour, d.minute, d.second, d.weekday(), yday, dst)) </pre></div> </div> where <code class="docutils literal notranslate">yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1</code> is the day number within the current year starting with 1 for January 1st. The <a class="reference internal" href="time.html#time.struct_time.tm_isdst" title="time.struct_time.tm_isdst"><code class="xref py py-attr docutils literal notranslate">tm_isdst</code></a> flag of the result is set according to the <a class="reference internal" href="#datetime.datetime.dst" title="datetime.datetime.dst"><code class="xref py py-meth docutils literal notranslate">dst()</code></a> method: <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> is <code class="docutils literal notranslate">None</code> or <a class="reference internal" href="#datetime.datetime.dst" title="datetime.datetime.dst"><code class="xref py py-meth docutils literal notranslate">dst()</code></a> returns <code class="docutils literal notranslate">None</code>, <code class="xref py py-attr docutils literal notranslate">tm_isdst</code> is set to <code class="docutils literal notranslate">-1</code>; else if <a class="reference internal" href="#datetime.datetime.dst" title="datetime.datetime.dst"><code class="xref py py-meth docutils literal notranslate">dst()</code></a> returns a non-zero value, <code class="xref py py-attr docutils literal notranslate">tm_isdst</code> is set to 1; else <code class="xref py py-attr docutils literal notranslate">tm_isdst</code> is set to 0. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.utctimetuple"> datetime.utctimetuple()<a class="headerlink" href="#datetime.datetime.utctimetuple" title="Link to this definition">¶</a></dt> <dd>If <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> instance <code class="docutils literal notranslate">d</code> is naive, this is the same as <code class="docutils literal notranslate">d.timetuple()</code> except that <a class="reference internal" href="time.html#time.struct_time.tm_isdst" title="time.struct_time.tm_isdst"><code class="xref py py-attr docutils literal notranslate">tm_isdst</code></a> is forced to 0 regardless of what <code class="docutils literal notranslate">d.dst()</code> returns. DST is never in effect for a UTC time. If <code class="docutils literal notranslate">d</code> is aware, <code class="docutils literal notranslate">d</code> is normalized to UTC time, by subtracting <code class="docutils literal notranslate">d.utcoffset()</code>, and a <a class="reference internal" href="time.html#time.struct_time" title="time.struct_time"><code class="xref py py-class docutils literal notranslate">time.struct_time</code></a> for the normalized time is returned. <code class="xref py py-attr docutils literal notranslate">tm_isdst</code> is forced to 0. Note that an <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate">OverflowError</code></a> may be raised if <code class="docutils literal notranslate">d.year</code> was <code class="docutils literal notranslate">MINYEAR</code> or <code class="docutils literal notranslate">MAXYEAR</code> and UTC adjustment spills over a year boundary. <div class="admonition warning"> Warning Because naive <code class="docutils literal notranslate">datetime</code> objects are treated by many <code class="docutils literal notranslate">datetime</code> methods as local times, it is preferred to use aware datetimes to represent times in UTC; as a result, using <a class="reference internal" href="#datetime.datetime.utctimetuple" title="datetime.datetime.utctimetuple"><code class="xref py py-meth docutils literal notranslate">datetime.utctimetuple()</code></a> may give misleading results. If you have a naive <code class="docutils literal notranslate">datetime</code> representing UTC, use <code class="docutils literal notranslate">datetime.replace(tzinfo=timezone.utc)</code> to make it aware, at which point you can use <a class="reference internal" href="#datetime.datetime.timetuple" title="datetime.datetime.timetuple"><code class="xref py py-meth docutils literal notranslate">datetime.timetuple()</code></a>. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.toordinal"> datetime.toordinal()<a class="headerlink" href="#datetime.datetime.toordinal" title="Link to this definition">¶</a></dt> <dd>Return the proleptic Gregorian ordinal of the date. The same as <code class="docutils literal notranslate">self.date().toordinal()</code>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.timestamp"> datetime.timestamp()<a class="headerlink" href="#datetime.datetime.timestamp" title="Link to this definition">¶</a></dt> <dd>Return POSIX timestamp corresponding to the <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> instance. The return value is a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate">float</code></a> similar to that returned by <a class="reference internal" href="time.html#time.time" title="time.time"><code class="xref py py-func docutils literal notranslate">time.time()</code></a>. Naive <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> instances are assumed to represent local time and this method relies on the platform C <code class="xref c c-func docutils literal notranslate">mktime()</code> function to perform the conversion. Since <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> supports wider range of values than <code class="xref c c-func docutils literal notranslate">mktime()</code> on many platforms, this method may raise <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate">OverflowError</code></a> or <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate">OSError</code></a> for times far in the past or far in the future. For aware <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> instances, the return value is computed as: <div class="highlight-python3 notranslate"><div class="highlight"><pre>(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds() </pre></div> </div> <div class="versionadded"> Added in version 3.3. </div> <div class="versionchanged"> Changed in version 3.6: The <a class="reference internal" href="#datetime.datetime.timestamp" title="datetime.datetime.timestamp"><code class="xref py py-meth docutils literal notranslate">timestamp()</code></a> method uses the <a class="reference internal" href="#datetime.datetime.fold" title="datetime.datetime.fold"><code class="xref py py-attr docutils literal notranslate">fold</code></a> attribute to disambiguate the times during a repeated interval. </div> <div class="admonition note"> Note There is no method to obtain the POSIX timestamp directly from a naive <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> instance representing UTC time. If your application uses this convention and your system time zone is not set to UTC, you can obtain the POSIX timestamp by supplying <code class="docutils literal notranslate">tzinfo=timezone.utc</code>: <div class="highlight-python3 notranslate"><div class="highlight"><pre>timestamp = dt.replace(tzinfo=timezone.utc).timestamp() </pre></div> </div> or by calculating the timestamp directly: <div class="highlight-python3 notranslate"><div class="highlight"><pre>timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1) </pre></div> </div> </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.weekday"> datetime.weekday()<a class="headerlink" href="#datetime.datetime.weekday" title="Link to this definition">¶</a></dt> <dd>Return the day of the week as an integer, where Monday is 0 and Sunday is 6. The same as <code class="docutils literal notranslate">self.date().weekday()</code>. See also <a class="reference internal" href="#datetime.datetime.isoweekday" title="datetime.datetime.isoweekday"><code class="xref py py-meth docutils literal notranslate">isoweekday()</code></a>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.isoweekday"> datetime.isoweekday()<a class="headerlink" href="#datetime.datetime.isoweekday" title="Link to this definition">¶</a></dt> <dd>Return the day of the week as an integer, where Monday is 1 and Sunday is 7. The same as <code class="docutils literal notranslate">self.date().isoweekday()</code>. See also <a class="reference internal" href="#datetime.datetime.weekday" title="datetime.datetime.weekday"><code class="xref py py-meth docutils literal notranslate">weekday()</code></a>, <a class="reference internal" href="#datetime.datetime.isocalendar" title="datetime.datetime.isocalendar"><code class="xref py py-meth docutils literal notranslate">isocalendar()</code></a>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.isocalendar"> datetime.isocalendar()<a class="headerlink" href="#datetime.datetime.isocalendar" title="Link to this definition">¶</a></dt> <dd>Return a <a class="reference internal" href="../glossary.html#term-named-tuple">named tuple</a> with three components: <code class="docutils literal notranslate">year</code>, <code class="docutils literal notranslate">week</code> and <code class="docutils literal notranslate">weekday</code>. The same as <code class="docutils literal notranslate">self.date().isocalendar()</code>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.isoformat"> datetime.isoformat(sep='T', timespec='auto')<a class="headerlink" href="#datetime.datetime.isoformat" title="Link to this definition">¶</a></dt> <dd>Return a string representing the date and time in ISO 8601 format: <ul class="simple"> <li><code class="docutils literal notranslate">YYYY-MM-DDTHH:MM:SS.ffffff</code>, if <a class="reference internal" href="#datetime.datetime.microsecond" title="datetime.datetime.microsecond"><code class="xref py py-attr docutils literal notranslate">microsecond</code></a> is not 0</li> <li><code class="docutils literal notranslate">YYYY-MM-DDTHH:MM:SS</code>, if <a class="reference internal" href="#datetime.datetime.microsecond" title="datetime.datetime.microsecond"><code class="xref py py-attr docutils literal notranslate">microsecond</code></a> is 0</li> </ul> If <a class="reference internal" href="#datetime.datetime.utcoffset" title="datetime.datetime.utcoffset"><code class="xref py py-meth docutils literal notranslate">utcoffset()</code></a> does not return <code class="docutils literal notranslate">None</code>, a string is appended, giving the UTC offset: <ul class="simple"> <li><code class="docutils literal notranslate">YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]</code>, if <a class="reference internal" href="#datetime.datetime.microsecond" title="datetime.datetime.microsecond"><code class="xref py py-attr docutils literal notranslate">microsecond</code></a> is not 0</li> <li><code class="docutils literal notranslate">YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]</code>, if <a class="reference internal" href="#datetime.datetime.microsecond" title="datetime.datetime.microsecond"><code class="xref py py-attr docutils literal notranslate">microsecond</code></a> is 0</li> </ul> Examples: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import datetime, timezone >>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat() '2019-05-18T15:17:08.132263' >>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat() '2019-05-18T15:17:00+00:00' </pre></div> </div> The optional argument sep (default <code class="docutils literal notranslate">'T'</code>) is a one-character separator, placed between the date and time portions of the result. For example: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import tzinfo, timedelta, datetime >>> class TZ(tzinfo): ... """A time zone with an arbitrary, constant -06:39 offset.""" ... def utcoffset(self, dt): ... return timedelta(hours=-6, minutes=-39) ... >>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ') '2002-12-25 00:00:00-06:39' >>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat() '2009-11-27T00:00:00.000100-06:39' </pre></div> </div> The optional argument timespec specifies the number of additional components of the time to include (the default is <code class="docutils literal notranslate">'auto'</code>). It can be one of the following: <ul class="simple"> <li><code class="docutils literal notranslate">'auto'</code>: Same as <code class="docutils literal notranslate">'seconds'</code> if <a class="reference internal" href="#datetime.datetime.microsecond" title="datetime.datetime.microsecond"><code class="xref py py-attr docutils literal notranslate">microsecond</code></a> is 0, same as <code class="docutils literal notranslate">'microseconds'</code> otherwise.</li> <li><code class="docutils literal notranslate">'hours'</code>: Include the <a class="reference internal" href="#datetime.datetime.hour" title="datetime.datetime.hour"><code class="xref py py-attr docutils literal notranslate">hour</code></a> in the two-digit <code class="docutils literal notranslate">HH</code> format.</li> <li><code class="docutils literal notranslate">'minutes'</code>: Include <a class="reference internal" href="#datetime.datetime.hour" title="datetime.datetime.hour"><code class="xref py py-attr docutils literal notranslate">hour</code></a> and <a class="reference internal" href="#datetime.datetime.minute" title="datetime.datetime.minute"><code class="xref py py-attr docutils literal notranslate">minute</code></a> in <code class="docutils literal notranslate">HH:MM</code> format.</li> <li><code class="docutils literal notranslate">'seconds'</code>: Include <a class="reference internal" href="#datetime.datetime.hour" title="datetime.datetime.hour"><code class="xref py py-attr docutils literal notranslate">hour</code></a>, <a class="reference internal" href="#datetime.datetime.minute" title="datetime.datetime.minute"><code class="xref py py-attr docutils literal notranslate">minute</code></a>, and <a class="reference internal" href="#datetime.datetime.second" title="datetime.datetime.second"><code class="xref py py-attr docutils literal notranslate">second</code></a> in <code class="docutils literal notranslate">HH:MM:SS</code> format.</li> <li><code class="docutils literal notranslate">'milliseconds'</code>: Include full time, but truncate fractional second part to milliseconds. <code class="docutils literal notranslate">HH:MM:SS.sss</code> format.</li> <li><code class="docutils literal notranslate">'microseconds'</code>: Include full time in <code class="docutils literal notranslate">HH:MM:SS.ffffff</code> format.</li> </ul> <div class="admonition note"> Note Excluded time components are truncated, not rounded. </div> <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> will be raised on an invalid timespec argument: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import datetime >>> datetime.now().isoformat(timespec='minutes') '2002-12-25T00:00' >>> dt = datetime(2015, 1, 1, 12, 30, 59, 0) >>> dt.isoformat(timespec='microseconds') '2015-01-01T12:30:59.000000' </pre></div> </div> <div class="versionchanged"> Changed in version 3.6: Added the timespec parameter. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.__str__"> datetime.__str__()<a class="headerlink" href="#datetime.datetime.__str__" title="Link to this definition">¶</a></dt> <dd>For a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> instance <code class="docutils literal notranslate">d</code>, <code class="docutils literal notranslate">str(d)</code> is equivalent to <code class="docutils literal notranslate">d.isoformat(' ')</code>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.ctime"> datetime.ctime()<a class="headerlink" href="#datetime.datetime.ctime" title="Link to this definition">¶</a></dt> <dd>Return a string representing the date and time: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import datetime >>> datetime(2002, 12, 4, 20, 30, 40).ctime() 'Wed Dec 4 20:30:40 2002' </pre></div> </div> The output string will not include time zone information, regardless of whether the input is aware or naive. <code class="docutils literal notranslate">d.ctime()</code> is equivalent to: <div class="highlight-python3 notranslate"><div class="highlight"><pre>time.ctime(time.mktime(d.timetuple())) </pre></div> </div> on platforms where the native C <code class="xref c c-func docutils literal notranslate">ctime()</code> function (which <a class="reference internal" href="time.html#time.ctime" title="time.ctime"><code class="xref py py-func docutils literal notranslate">time.ctime()</code></a> invokes, but which <a class="reference internal" href="#datetime.datetime.ctime" title="datetime.datetime.ctime"><code class="xref py py-meth docutils literal notranslate">datetime.ctime()</code></a> does not invoke) conforms to the C standard. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.strftime"> datetime.strftime(format)<a class="headerlink" href="#datetime.datetime.strftime" title="Link to this definition">¶</a></dt> <dd>Return a string representing the date and time, controlled by an explicit format string. See also <a class="reference internal" href="#strftime-strptime-behavior">strftime() and strptime() Behavior</a> and <a class="reference internal" href="#datetime.datetime.isoformat" title="datetime.datetime.isoformat"><code class="xref py py-meth docutils literal notranslate">datetime.isoformat()</code></a>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.datetime.__format__"> datetime.__format__(format)<a class="headerlink" href="#datetime.datetime.__format__" title="Link to this definition">¶</a></dt> <dd>Same as <a class="reference internal" href="#datetime.datetime.strftime" title="datetime.datetime.strftime"><code class="xref py py-meth docutils literal notranslate">datetime.strftime()</code></a>. This makes it possible to specify a format string for a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object in <a class="reference internal" href="../reference/lexical_analysis.html#f-strings">formatted string literals</a> and when using <a class="reference internal" href="stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal notranslate">str.format()</code></a>. See also <a class="reference internal" href="#strftime-strptime-behavior">strftime() and strptime() Behavior</a> and <a class="reference internal" href="#datetime.datetime.isoformat" title="datetime.datetime.isoformat"><code class="xref py py-meth docutils literal notranslate">datetime.isoformat()</code></a>. </dd></dl> <section id="examples-of-usage-datetime"> <h3>Examples of Usage: <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a><a class="headerlink" href="#examples-of-usage-datetime" title="Link to this heading">¶</a></h3> Examples of working with <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> objects: <div class="highlight-pycon notranslate"><div class="highlight"><pre>>>> from datetime import datetime, date, time, timezone >>> # 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() >>> datetime.now() datetime.datetime(2007, 12, 6, 16, 29, 43, 79043) # GMT +1 >>> datetime.now(timezone.utc) datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc) >>> # 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: ... 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: ... print(it) ... 2006 # ISO year 47 # ISO week 2 # ISO weekday >>> # Formatting a 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.' </pre></div> </div> The example below defines a <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclass capturing time zone information for Kabul, Afghanistan, which used +4 UTC until 1945 and then +4:30 UTC thereafter: <div class="highlight-python3 notranslate"><div class="highlight"><pre>from datetime import timedelta, datetime, tzinfo, timezone class KabulTz(tzinfo): # Kabul used +4 until 1945, when they moved to +4:30 UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc) def utcoffset(self, dt): if dt.year < 1945: return timedelta(hours=4) elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, 30): # An ambiguous ("imaginary") half-hour range representing # a 'fold' in time due to the shift from +4 to +4:30. # If dt falls in the imaginary range, use fold to decide how # to resolve. See PEP495. return timedelta(hours=4, minutes=(30 if dt.fold else 0)) else: return timedelta(hours=4, minutes=30) def fromutc(self, dt): # Follow same validations as in datetime.tzinfo if not isinstance(dt, datetime): raise TypeError("fromutc() requires a datetime argument") if dt.tzinfo is not self: raise ValueError("dt.tzinfo is not self") # A custom implementation is required for fromutc as # the input to this function is a datetime with utc values # but with a tzinfo set to self. # See datetime.astimezone or fromtimestamp. if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE: return dt + timedelta(hours=4, minutes=30) else: return dt + timedelta(hours=4) def dst(self, dt): # Kabul does not observe daylight saving time. return timedelta(0) def tzname(self, dt): if dt >= self.UTC_MOVE_DATE: return "+04:30" return "+04" </pre></div> </div> Usage of <code class="docutils literal notranslate">KabulTz</code> from above: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> tz1 = KabulTz() >>> # Datetime before the change >>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1) >>> print(dt1.utcoffset()) 4:00:00 >>> # Datetime after the change >>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1) >>> print(dt2.utcoffset()) 4:30:00 >>> # Convert datetime to another time zone >>> dt3 = dt2.astimezone(timezone.utc) >>> dt3 datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc) >>> dt2 datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz()) >>> dt2 == dt3 True </pre></div> </div> </section> </section> <section id="time-objects"> <h2><a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> Objects<a class="headerlink" href="#time-objects" title="Link to this heading">¶</a></h2> A <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> object represents a (local) time of day, independent of any particular day, and subject to adjustment via a <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> object. <dl class="py class"> <dt class="sig sig-object py" id="datetime.time"> class datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)<a class="headerlink" href="#datetime.time" title="Link to this definition">¶</a></dt> <dd>All arguments are optional. tzinfo may be <code class="docutils literal notranslate">None</code>, or an instance of a <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclass. The remaining arguments must be integers in the following ranges: <ul class="simple"> <li><code class="docutils literal notranslate">0 <= hour < 24</code>,</li> <li><code class="docutils literal notranslate">0 <= minute < 60</code>,</li> <li><code class="docutils literal notranslate">0 <= second < 60</code>,</li> <li><code class="docutils literal notranslate">0 <= microsecond < 1000000</code>,</li> <li><code class="docutils literal notranslate">fold in [0, 1]</code>.</li> </ul> If an argument outside those ranges is given, <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> is raised. All default to 0 except tzinfo, which defaults to <code class="docutils literal notranslate">None</code>. </dd></dl> Class attributes: <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.time.min"> time.min<a class="headerlink" href="#datetime.time.min" title="Link to this definition">¶</a></dt> <dd>The earliest representable <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a>, <code class="docutils literal notranslate">time(0, 0, 0, 0)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.time.max"> time.max<a class="headerlink" href="#datetime.time.max" title="Link to this definition">¶</a></dt> <dd>The latest representable <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a>, <code class="docutils literal notranslate">time(23, 59, 59, 999999)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.time.resolution"> time.resolution<a class="headerlink" href="#datetime.time.resolution" title="Link to this definition">¶</a></dt> <dd>The smallest possible difference between non-equal <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> objects, <code class="docutils literal notranslate">timedelta(microseconds=1)</code>, although note that arithmetic on <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> objects is not supported. </dd></dl> Instance attributes (read-only): <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.time.hour"> time.hour<a class="headerlink" href="#datetime.time.hour" title="Link to this definition">¶</a></dt> <dd>In <code class="docutils literal notranslate">range(24)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.time.minute"> time.minute<a class="headerlink" href="#datetime.time.minute" title="Link to this definition">¶</a></dt> <dd>In <code class="docutils literal notranslate">range(60)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.time.second"> time.second<a class="headerlink" href="#datetime.time.second" title="Link to this definition">¶</a></dt> <dd>In <code class="docutils literal notranslate">range(60)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.time.microsecond"> time.microsecond<a class="headerlink" href="#datetime.time.microsecond" title="Link to this definition">¶</a></dt> <dd>In <code class="docutils literal notranslate">range(1000000)</code>. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.time.tzinfo"> time.tzinfo<a class="headerlink" href="#datetime.time.tzinfo" title="Link to this definition">¶</a></dt> <dd>The object passed as the tzinfo argument to the <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> constructor, or <code class="docutils literal notranslate">None</code> if none was passed. </dd></dl> <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.time.fold"> time.fold<a class="headerlink" href="#datetime.time.fold" title="Link to this definition">¶</a></dt> <dd>In <code class="docutils literal notranslate">[0, 1]</code>. Used to disambiguate wall times during a repeated interval. (A repeated interval occurs when clocks are rolled back at the end of daylight saving time or when the UTC offset for the current zone is decreased for political reasons.) The values 0 and 1 represent, respectively, the earlier and later of the two moments with the same wall time representation. <div class="versionadded"> Added in version 3.6. </div> </dd></dl> <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> objects support equality and order comparisons, where <code class="docutils literal notranslate">a</code> is considered less than <code class="docutils literal notranslate">b</code> when <code class="docutils literal notranslate">a</code> precedes <code class="docutils literal notranslate">b</code> in time. Naive and aware <code class="xref py py-class docutils literal notranslate">time</code> objects are never equal. Order comparison between naive and aware <code class="xref py py-class docutils literal notranslate">time</code> objects raises <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate">TypeError</code></a>. If both comparands are aware, and have the same <a class="reference internal" href="#datetime.time.tzinfo" title="datetime.time.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> attribute, the <code class="xref py py-attr docutils literal notranslate">tzinfo</code> and <code class="xref py py-attr docutils literal notranslate">fold</code> attributes are ignored and the base times are compared. If both comparands are aware and have different <code class="xref py py-attr docutils literal notranslate">tzinfo</code> attributes, the comparands are first adjusted by subtracting their UTC offsets (obtained from <code class="docutils literal notranslate">self.utcoffset()</code>). <div class="versionchanged"> Changed in version 3.3: Equality comparisons between aware and naive <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> instances don’t raise <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate">TypeError</code></a>. </div> In Boolean contexts, a <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> object is always considered to be true. <div class="versionchanged"> Changed in version 3.5: Before Python 3.5, a <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> object was considered to be false if it represented midnight in UTC. This behavior was considered obscure and error-prone and has been removed in Python 3.5. See <a class="reference external" href="https://bugs.python.org/issue?@action=redirect&bpo=13936">bpo-13936</a> for full details. </div> Other constructor: <dl class="py method"> <dt class="sig sig-object py" id="datetime.time.fromisoformat"> classmethod time.fromisoformat(time_string)<a class="headerlink" href="#datetime.time.fromisoformat" title="Link to this definition">¶</a></dt> <dd>Return a <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> corresponding to a time_string in any valid ISO 8601 format, with the following exceptions: <ol class="arabic simple"> <li>Time zone offsets may have fractional seconds.</li> <li>The leading <code class="docutils literal notranslate">T</code>, normally required in cases where there may be ambiguity between a date and a time, is not required.</li> <li>Fractional seconds may have any number of digits (anything beyond 6 will be truncated).</li> <li>Fractional hours and minutes are not supported.</li> </ol> Examples: <div class="highlight-pycon notranslate"><div class="highlight"><pre>>>> from datetime import time >>> time.fromisoformat('04:23:01') datetime.time(4, 23, 1) >>> time.fromisoformat('T04:23:01') datetime.time(4, 23, 1) >>> time.fromisoformat('T042301') datetime.time(4, 23, 1) >>> time.fromisoformat('04:23:01.000384') datetime.time(4, 23, 1, 384) >>> time.fromisoformat('04:23:01,000384') datetime.time(4, 23, 1, 384) >>> time.fromisoformat('04:23:01+04:00') datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400))) >>> time.fromisoformat('04:23:01Z') datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc) >>> time.fromisoformat('04:23:01+00:00') datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc) </pre></div> </div> <div class="versionadded"> Added in version 3.7. </div> <div class="versionchanged"> Changed in version 3.11: Previously, this method only supported formats that could be emitted by <a class="reference internal" href="#datetime.time.isoformat" title="datetime.time.isoformat"><code class="xref py py-meth docutils literal notranslate">time.isoformat()</code></a>. </div> </dd></dl> Instance methods: <dl class="py method"> <dt class="sig sig-object py" id="datetime.time.replace"> time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)<a class="headerlink" href="#datetime.time.replace" title="Link to this definition">¶</a></dt> <dd>Return a <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> with the same value, except for those attributes given new values by whichever keyword arguments are specified. Note that <code class="docutils literal notranslate">tzinfo=None</code> can be specified to create a naive <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> from an aware <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a>, without conversion of the time data. <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> objects are also supported by generic function <a class="reference internal" href="copy.html#copy.replace" title="copy.replace"><code class="xref py py-func docutils literal notranslate">copy.replace()</code></a>. <div class="versionchanged"> Changed in version 3.6: Added the fold parameter. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.time.isoformat"> time.isoformat(timespec='auto')<a class="headerlink" href="#datetime.time.isoformat" title="Link to this definition">¶</a></dt> <dd>Return a string representing the time in ISO 8601 format, one of: <ul class="simple"> <li><code class="docutils literal notranslate">HH:MM:SS.ffffff</code>, if <a class="reference internal" href="#datetime.time.microsecond" title="datetime.time.microsecond"><code class="xref py py-attr docutils literal notranslate">microsecond</code></a> is not 0</li> <li><code class="docutils literal notranslate">HH:MM:SS</code>, if <a class="reference internal" href="#datetime.time.microsecond" title="datetime.time.microsecond"><code class="xref py py-attr docutils literal notranslate">microsecond</code></a> is 0</li> <li><code class="docutils literal notranslate">HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]</code>, if <a class="reference internal" href="#datetime.time.utcoffset" title="datetime.time.utcoffset"><code class="xref py py-meth docutils literal notranslate">utcoffset()</code></a> does not return <code class="docutils literal notranslate">None</code></li> <li><code class="docutils literal notranslate">HH:MM:SS+HH:MM[:SS[.ffffff]]</code>, if <a class="reference internal" href="#datetime.time.microsecond" title="datetime.time.microsecond"><code class="xref py py-attr docutils literal notranslate">microsecond</code></a> is 0 and <a class="reference internal" href="#datetime.time.utcoffset" title="datetime.time.utcoffset"><code class="xref py py-meth docutils literal notranslate">utcoffset()</code></a> does not return <code class="docutils literal notranslate">None</code></li> </ul> The optional argument timespec specifies the number of additional components of the time to include (the default is <code class="docutils literal notranslate">'auto'</code>). It can be one of the following: <ul class="simple"> <li><code class="docutils literal notranslate">'auto'</code>: Same as <code class="docutils literal notranslate">'seconds'</code> if <a class="reference internal" href="#datetime.time.microsecond" title="datetime.time.microsecond"><code class="xref py py-attr docutils literal notranslate">microsecond</code></a> is 0, same as <code class="docutils literal notranslate">'microseconds'</code> otherwise.</li> <li><code class="docutils literal notranslate">'hours'</code>: Include the <a class="reference internal" href="#datetime.time.hour" title="datetime.time.hour"><code class="xref py py-attr docutils literal notranslate">hour</code></a> in the two-digit <code class="docutils literal notranslate">HH</code> format.</li> <li><code class="docutils literal notranslate">'minutes'</code>: Include <a class="reference internal" href="#datetime.time.hour" title="datetime.time.hour"><code class="xref py py-attr docutils literal notranslate">hour</code></a> and <a class="reference internal" href="#datetime.time.minute" title="datetime.time.minute"><code class="xref py py-attr docutils literal notranslate">minute</code></a> in <code class="docutils literal notranslate">HH:MM</code> format.</li> <li><code class="docutils literal notranslate">'seconds'</code>: Include <a class="reference internal" href="#datetime.time.hour" title="datetime.time.hour"><code class="xref py py-attr docutils literal notranslate">hour</code></a>, <a class="reference internal" href="#datetime.time.minute" title="datetime.time.minute"><code class="xref py py-attr docutils literal notranslate">minute</code></a>, and <a class="reference internal" href="#datetime.time.second" title="datetime.time.second"><code class="xref py py-attr docutils literal notranslate">second</code></a> in <code class="docutils literal notranslate">HH:MM:SS</code> format.</li> <li><code class="docutils literal notranslate">'milliseconds'</code>: Include full time, but truncate fractional second part to milliseconds. <code class="docutils literal notranslate">HH:MM:SS.sss</code> format.</li> <li><code class="docutils literal notranslate">'microseconds'</code>: Include full time in <code class="docutils literal notranslate">HH:MM:SS.ffffff</code> format.</li> </ul> <div class="admonition note"> Note Excluded time components are truncated, not rounded. </div> <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> will be raised on an invalid timespec argument. Example: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import time >>> time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes') '12:34' >>> dt = time(hour=12, minute=34, second=56, microsecond=0) >>> dt.isoformat(timespec='microseconds') '12:34:56.000000' >>> dt.isoformat(timespec='auto') '12:34:56' </pre></div> </div> <div class="versionchanged"> Changed in version 3.6: Added the timespec parameter. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.time.__str__"> time.__str__()<a class="headerlink" href="#datetime.time.__str__" title="Link to this definition">¶</a></dt> <dd>For a time <code class="docutils literal notranslate">t</code>, <code class="docutils literal notranslate">str(t)</code> is equivalent to <code class="docutils literal notranslate">t.isoformat()</code>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.time.strftime"> time.strftime(format)<a class="headerlink" href="#datetime.time.strftime" title="Link to this definition">¶</a></dt> <dd>Return a string representing the time, controlled by an explicit format string. See also <a class="reference internal" href="#strftime-strptime-behavior">strftime() and strptime() Behavior</a> and <a class="reference internal" href="#datetime.time.isoformat" title="datetime.time.isoformat"><code class="xref py py-meth docutils literal notranslate">time.isoformat()</code></a>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.time.__format__"> time.__format__(format)<a class="headerlink" href="#datetime.time.__format__" title="Link to this definition">¶</a></dt> <dd>Same as <a class="reference internal" href="#datetime.time.strftime" title="datetime.time.strftime"><code class="xref py py-meth docutils literal notranslate">time.strftime()</code></a>. This makes it possible to specify a format string for a <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> object in <a class="reference internal" href="../reference/lexical_analysis.html#f-strings">formatted string literals</a> and when using <a class="reference internal" href="stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal notranslate">str.format()</code></a>. See also <a class="reference internal" href="#strftime-strptime-behavior">strftime() and strptime() Behavior</a> and <a class="reference internal" href="#datetime.time.isoformat" title="datetime.time.isoformat"><code class="xref py py-meth docutils literal notranslate">time.isoformat()</code></a>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.time.utcoffset"> time.utcoffset()<a class="headerlink" href="#datetime.time.utcoffset" title="Link to this definition">¶</a></dt> <dd>If <a class="reference internal" href="#datetime.time.tzinfo" title="datetime.time.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> is <code class="docutils literal notranslate">None</code>, returns <code class="docutils literal notranslate">None</code>, else returns <code class="docutils literal notranslate">self.tzinfo.utcoffset(None)</code>, and raises an exception if the latter doesn’t return <code class="docutils literal notranslate">None</code> or a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object with magnitude less than one day. <div class="versionchanged"> Changed in version 3.7: The UTC offset is not restricted to a whole number of minutes. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.time.dst"> time.dst()<a class="headerlink" href="#datetime.time.dst" title="Link to this definition">¶</a></dt> <dd>If <a class="reference internal" href="#datetime.time.tzinfo" title="datetime.time.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> is <code class="docutils literal notranslate">None</code>, returns <code class="docutils literal notranslate">None</code>, else returns <code class="docutils literal notranslate">self.tzinfo.dst(None)</code>, and raises an exception if the latter doesn’t return <code class="docutils literal notranslate">None</code>, or a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object with magnitude less than one day. <div class="versionchanged"> Changed in version 3.7: The DST offset is not restricted to a whole number of minutes. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.time.tzname"> time.tzname()<a class="headerlink" href="#datetime.time.tzname" title="Link to this definition">¶</a></dt> <dd>If <a class="reference internal" href="#datetime.time.tzinfo" title="datetime.time.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> is <code class="docutils literal notranslate">None</code>, returns <code class="docutils literal notranslate">None</code>, else returns <code class="docutils literal notranslate">self.tzinfo.tzname(None)</code>, or raises an exception if the latter doesn’t return <code class="docutils literal notranslate">None</code> or a string object. </dd></dl> <section id="examples-of-usage-time"> <h3>Examples of Usage: <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a><a class="headerlink" href="#examples-of-usage-time" title="Link to this heading">¶</a></h3> Examples of working with a <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> object: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import time, tzinfo, timedelta >>> class TZ1(tzinfo): ... def utcoffset(self, dt): ... return timedelta(hours=1) ... def dst(self, dt): ... return timedelta(0) ... def tzname(self,dt): ... return "+01:00" ... def __repr__(self): ... return f"{self.__class__.__name__}()" ... >>> t = time(12, 10, 30, tzinfo=TZ1()) >>> t datetime.time(12, 10, 30, tzinfo=TZ1()) >>> t.isoformat() '12:10:30+01:00' >>> t.dst() datetime.timedelta(0) >>> t.tzname() '+01:00' >>> t.strftime("%H:%M:%S %Z") '12:10:30 +01:00' >>> 'The {} is {:%H:%M}.'.format("time", t) 'The time is 12:10.' </pre></div> </div> </section> </section> <section id="tzinfo-objects"> <h2><a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> Objects<a class="headerlink" href="#tzinfo-objects" title="Link to this heading">¶</a></h2> <dl class="py class"> <dt class="sig sig-object py" id="datetime.tzinfo"> class datetime.tzinfo<a class="headerlink" href="#datetime.tzinfo" title="Link to this definition">¶</a></dt> <dd>This is an abstract base class, meaning that this class should not be instantiated directly. Define a subclass of <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> to capture information about a particular time zone. An instance of (a concrete subclass of) <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> can be passed to the constructors for <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> and <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> objects. The latter objects view their attributes as being in local time, and the <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> 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. You need to derive a concrete subclass, and (at least) supply implementations of the standard <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> methods needed by the <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> methods you use. The <code class="xref py py-mod docutils literal notranslate">datetime</code> module provides <a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate">timezone</code></a>, a simple concrete subclass of <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> which can represent time zones with fixed offset from UTC such as UTC itself or North American EST and EDT. Special requirement for pickling: A <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclass must have an <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate">__init__()</code></a> method that can be called with no arguments, otherwise 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 <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> may need to implement the following methods. Exactly which methods are needed depends on the uses made of aware <code class="xref py py-mod docutils literal notranslate">datetime</code> objects. If in doubt, simply implement all of them. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.tzinfo.utcoffset"> tzinfo.utcoffset(dt)<a class="headerlink" href="#datetime.tzinfo.utcoffset" title="Link to this definition">¶</a></dt> <dd>Return offset of local time from UTC, as a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object that is positive east of UTC. If local time is west of UTC, this should be negative. This represents the total offset from UTC; for example, if a <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> object represents both time zone and DST adjustments, <a class="reference internal" href="#datetime.tzinfo.utcoffset" title="datetime.tzinfo.utcoffset"><code class="xref py py-meth docutils literal notranslate">utcoffset()</code></a> should return their sum. If the UTC offset isn’t known, return <code class="docutils literal notranslate">None</code>. Else the value returned must be a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object strictly between <code class="docutils literal notranslate">-timedelta(hours=24)</code> and <code class="docutils literal notranslate">timedelta(hours=24)</code> (the magnitude of the offset must be less than one day). Most implementations of <a class="reference internal" href="#datetime.tzinfo.utcoffset" title="datetime.tzinfo.utcoffset"><code class="xref py py-meth docutils literal notranslate">utcoffset()</code></a> will probably look like one of these two: <div class="highlight-python3 notranslate"><div class="highlight"><pre>return CONSTANT # fixed-offset class return CONSTANT + self.dst(dt) # daylight-aware class </pre></div> </div> If <a class="reference internal" href="#datetime.tzinfo.utcoffset" title="datetime.tzinfo.utcoffset"><code class="xref py py-meth docutils literal notranslate">utcoffset()</code></a> does not return <code class="docutils literal notranslate">None</code>, <a class="reference internal" href="#datetime.tzinfo.dst" title="datetime.tzinfo.dst"><code class="xref py py-meth docutils literal notranslate">dst()</code></a> should not return <code class="docutils literal notranslate">None</code> either. The default implementation of <a class="reference internal" href="#datetime.tzinfo.utcoffset" title="datetime.tzinfo.utcoffset"><code class="xref py py-meth docutils literal notranslate">utcoffset()</code></a> raises <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate">NotImplementedError</code></a>. <div class="versionchanged"> Changed in version 3.7: The UTC offset is not restricted to a whole number of minutes. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.tzinfo.dst"> tzinfo.dst(dt)<a class="headerlink" href="#datetime.tzinfo.dst" title="Link to this definition">¶</a></dt> <dd>Return the daylight saving time (DST) adjustment, as a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object or <code class="docutils literal notranslate">None</code> if DST information isn’t known. Return <code class="docutils literal notranslate">timedelta(0)</code> if DST is not in effect. If DST is in effect, return the offset as a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object (see <a class="reference internal" href="#datetime.tzinfo.utcoffset" title="datetime.tzinfo.utcoffset"><code class="xref py py-meth docutils literal notranslate">utcoffset()</code></a> for details). Note that DST offset, if applicable, has already been added to the UTC offset returned by <a class="reference internal" href="#datetime.tzinfo.utcoffset" title="datetime.tzinfo.utcoffset"><code class="xref py py-meth docutils literal notranslate">utcoffset()</code></a>, so there’s no need to consult <a class="reference internal" href="#datetime.tzinfo.dst" title="datetime.tzinfo.dst"><code class="xref py py-meth docutils literal notranslate">dst()</code></a> unless you’re interested in obtaining DST info separately. For example, <a class="reference internal" href="#datetime.datetime.timetuple" title="datetime.datetime.timetuple"><code class="xref py py-meth docutils literal notranslate">datetime.timetuple()</code></a> calls its <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate">tzinfo</code></a> attribute’s <a class="reference internal" href="#datetime.tzinfo.dst" title="datetime.tzinfo.dst"><code class="xref py py-meth docutils literal notranslate">dst()</code></a> method to determine how the <a class="reference internal" href="time.html#time.struct_time.tm_isdst" title="time.struct_time.tm_isdst"><code class="xref py py-attr docutils literal notranslate">tm_isdst</code></a> flag should be set, and <a class="reference internal" href="#datetime.tzinfo.fromutc" title="datetime.tzinfo.fromutc"><code class="xref py py-meth docutils literal notranslate">tzinfo.fromutc()</code></a> calls <a class="reference internal" href="#datetime.tzinfo.dst" title="datetime.tzinfo.dst"><code class="xref py py-meth docutils literal notranslate">dst()</code></a> to account for DST changes when crossing time zones. An instance tz of a <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclass that models both standard and daylight times must be consistent in this sense: <code class="docutils literal notranslate">tz.utcoffset(dt) - tz.dst(dt)</code> must return the same result for every <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> dt with <code class="docutils literal notranslate">dt.tzinfo == tz</code>. For sane <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclasses, this expression yields the time zone’s “standard offset”, which should not depend on the date or the time, but only on geographic location. The implementation of <a class="reference internal" href="#datetime.datetime.astimezone" title="datetime.datetime.astimezone"><code class="xref py py-meth docutils literal notranslate">datetime.astimezone()</code></a> relies on this, but cannot detect violations; it’s the programmer’s responsibility to ensure it. If a <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclass cannot guarantee this, it may be able to override the default implementation of <a class="reference internal" href="#datetime.tzinfo.fromutc" title="datetime.tzinfo.fromutc"><code class="xref py py-meth docutils literal notranslate">tzinfo.fromutc()</code></a> to work correctly with <a class="reference internal" href="#datetime.datetime.astimezone" title="datetime.datetime.astimezone"><code class="xref py py-meth docutils literal notranslate">astimezone()</code></a> regardless. Most implementations of <a class="reference internal" href="#datetime.tzinfo.dst" title="datetime.tzinfo.dst"><code class="xref py py-meth docutils literal notranslate">dst()</code></a> will probably look like one of these two: <div class="highlight-python3 notranslate"><div class="highlight"><pre>def dst(self, dt): # a fixed-offset class: doesn't account for DST return timedelta(0) </pre></div> </div> or: <div class="highlight-python3 notranslate"><div class="highlight"><pre>def dst(self, dt): # Code to set dston and dstoff to the time zone's DST # transition times based on the input dt.year, and expressed # in standard local time. if dston <= dt.replace(tzinfo=None) < dstoff: return timedelta(hours=1) else: return timedelta(0) </pre></div> </div> The default implementation of <a class="reference internal" href="#datetime.tzinfo.dst" title="datetime.tzinfo.dst"><code class="xref py py-meth docutils literal notranslate">dst()</code></a> raises <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate">NotImplementedError</code></a>. <div class="versionchanged"> Changed in version 3.7: The DST offset is not restricted to a whole number of minutes. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.tzinfo.tzname"> tzinfo.tzname(dt)<a class="headerlink" href="#datetime.tzinfo.tzname" title="Link to this definition">¶</a></dt> <dd>Return the time zone name corresponding to the <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object dt, as a string. Nothing about string names is defined by the <code class="xref py py-mod docutils literal notranslate">datetime</code> module, and there’s no requirement that it mean anything in particular. For example, <code class="docutils literal notranslate">"GMT"</code>, <code class="docutils literal notranslate">"UTC"</code>, <code class="docutils literal notranslate">"-500"</code>, <code class="docutils literal notranslate">"-5:00"</code>, <code class="docutils literal notranslate">"EDT"</code>, <code class="docutils literal notranslate">"US/Eastern"</code>, <code class="docutils literal notranslate">"America/New York"</code> are all valid replies. Return <code class="docutils literal notranslate">None</code> if a string name isn’t known. Note that this is a method rather than a fixed string primarily because some <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclasses will wish to return different names depending on the specific value of dt passed, especially if the <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> class is accounting for daylight time. The default implementation of <a class="reference internal" href="#datetime.tzinfo.tzname" title="datetime.tzinfo.tzname"><code class="xref py py-meth docutils literal notranslate">tzname()</code></a> raises <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate">NotImplementedError</code></a>. </dd></dl> These methods are called by a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> or <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> object, in response to their methods of the same names. A <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object passes itself as the argument, and a <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> object passes <code class="docutils literal notranslate">None</code> as the argument. A <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclass’s methods should therefore be prepared to accept a dt argument of <code class="docutils literal notranslate">None</code>, or of class <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a>. When <code class="docutils literal notranslate">None</code> is passed, it’s up to the class designer to decide the best response. For example, returning <code class="docutils literal notranslate">None</code> is appropriate if the class wishes to say that time objects don’t participate in the <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> protocols. It may be more useful for <code class="docutils literal notranslate">utcoffset(None)</code> to return the standard UTC offset, as there is no other convention for discovering the standard offset. When a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object is passed in response to a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> method, <code class="docutils literal notranslate">dt.tzinfo</code> is the same object as self. <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> methods can rely on this, unless user code calls <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> methods directly. The intent is that the <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> methods interpret dt as being in local time, and not need worry about objects in other time zones. There is one more <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> method that a subclass may wish to override: <dl class="py method"> <dt class="sig sig-object py" id="datetime.tzinfo.fromutc"> tzinfo.fromutc(dt)<a class="headerlink" href="#datetime.tzinfo.fromutc" title="Link to this definition">¶</a></dt> <dd>This is called from the default <a class="reference internal" href="#datetime.datetime.astimezone" title="datetime.datetime.astimezone"><code class="xref py py-meth docutils literal notranslate">datetime.astimezone()</code></a> implementation. When called from that, <code class="docutils literal notranslate">dt.tzinfo</code> is self, and dt’s date and time data are to be viewed as expressing a UTC time. The purpose of <a class="reference internal" href="#datetime.tzinfo.fromutc" title="datetime.tzinfo.fromutc"><code class="xref py py-meth docutils literal notranslate">fromutc()</code></a> is to adjust the date and time data, returning an equivalent datetime in self’s local time. Most <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclasses should be able to inherit the default <a class="reference internal" href="#datetime.tzinfo.fromutc" title="datetime.tzinfo.fromutc"><code class="xref py py-meth docutils literal notranslate">fromutc()</code></a> implementation without problems. It’s strong enough to handle fixed-offset time zones, and time zones accounting for both standard and daylight time, and the latter even if the DST transition times differ in different years. An example of a time zone the default <a class="reference internal" href="#datetime.tzinfo.fromutc" title="datetime.tzinfo.fromutc"><code class="xref py py-meth docutils literal notranslate">fromutc()</code></a> implementation may not handle correctly in all cases is one where the standard offset (from UTC) depends on the specific date and time passed, which can happen for political reasons. The default implementations of <a class="reference internal" href="#datetime.datetime.astimezone" title="datetime.datetime.astimezone"><code class="xref py py-meth docutils literal notranslate">astimezone()</code></a> and <a class="reference internal" href="#datetime.tzinfo.fromutc" title="datetime.tzinfo.fromutc"><code class="xref py py-meth docutils literal notranslate">fromutc()</code></a> may not produce the result you want if the result is one of the hours straddling the moment the standard offset changes. Skipping code for error cases, the default <a class="reference internal" href="#datetime.tzinfo.fromutc" title="datetime.tzinfo.fromutc"><code class="xref py py-meth docutils literal notranslate">fromutc()</code></a> implementation acts like: <div class="highlight-python3 notranslate"><div class="highlight"><pre>def fromutc(self, dt): # raise ValueError error if dt.tzinfo is not self dtoff = dt.utcoffset() dtdst = dt.dst() # raise ValueError if dtoff is None or dtdst is None delta = dtoff - dtdst # this is self's standard offset if delta: dt += delta # convert to standard local time dtdst = dt.dst() # raise ValueError if dtdst is None if dtdst: return dt + dtdst else: return dt </pre></div> </div> </dd></dl> In the following <a class="reference download internal" download="" href="../_downloads/6dc1f3f4f0e6ca13cb42ddf4d6cbc8af/tzinfo_examples.py"><code class="xref download docutils literal notranslate">tzinfo_examples.py</code></a> file there are some examples of <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> classes: <div class="highlight-python3 notranslate"><div class="highlight"><pre>from datetime import tzinfo, timedelta, datetime ZERO = timedelta(0) HOUR = timedelta(hours=1) SECOND = timedelta(seconds=1) # A class capturing the platform's idea of local time. # (May result in wrong values on historical times in # timezones where UTC offset and/or the DST rules had # changed in the past.) import time as _time STDOFFSET = timedelta(seconds = -_time.timezone) if _time.daylight: DSTOFFSET = timedelta(seconds = -_time.altzone) else: DSTOFFSET = STDOFFSET DSTDIFF = DSTOFFSET - STDOFFSET class LocalTimezone(tzinfo): def fromutc(self, dt): assert dt.tzinfo is self stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND args = _time.localtime(stamp)[:6] dst_diff = DSTDIFF // SECOND # Detect fold fold = (args == _time.localtime(stamp - dst_diff)) return datetime(*args, microsecond=dt.microsecond, tzinfo=self, fold=fold) def utcoffset(self, dt): if self._isdst(dt): return DSTOFFSET else: return STDOFFSET def dst(self, dt): if self._isdst(dt): return DSTDIFF else: return ZERO def tzname(self, dt): return _time.tzname[self._isdst(dt)] def _isdst(self, dt): tt = (dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second, dt.weekday(), 0, 0) stamp = _time.mktime(tt) tt = _time.localtime(stamp) return tt.tm_isdst > 0 Local = LocalTimezone() # A complete implementation of current DST rules for major US time zones. def first_sunday_on_or_after(dt): days_to_go = 6 - dt.weekday() if days_to_go: dt += timedelta(days_to_go) return dt # US DST Rules # # This is a simplified (i.e., wrong for a few cases) set of rules for US # DST start and end times. For a complete and up-to-date set of DST rules # and timezone definitions, visit the Olson Database (or try pytz): # http://www.twinsun.com/tz/tz-link.htm # https://sourceforge.net/projects/pytz/ (might not be up-to-date) # # In the US, since 2007, DST starts at 2am (standard time) on the second # Sunday in March, which is the first Sunday on or after Mar 8. DSTSTART_2007 = datetime(1, 3, 8, 2) # and ends at 2am (DST time) on the first Sunday of Nov. DSTEND_2007 = datetime(1, 11, 1, 2) # From 1987 to 2006, DST used to start at 2am (standard time) on the first # Sunday in April and to end at 2am (DST time) on the last # Sunday of October, which is the first Sunday on or after Oct 25. DSTSTART_1987_2006 = datetime(1, 4, 1, 2) DSTEND_1987_2006 = datetime(1, 10, 25, 2) # From 1967 to 1986, DST used to start at 2am (standard time) on the last # Sunday in April (the one on or after April 24) and to end at 2am (DST time) # on the last Sunday of October, which is the first Sunday # on or after Oct 25. DSTSTART_1967_1986 = datetime(1, 4, 24, 2) DSTEND_1967_1986 = DSTEND_1987_2006 def us_dst_range(year): # Find start and end times for US DST. For years before 1967, return # start = end for no DST. if 2006 < year: dststart, dstend = DSTSTART_2007, DSTEND_2007 elif 1986 < year < 2007: dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006 elif 1966 < year < 1987: dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986 else: return (datetime(year, 1, 1), ) * 2 start = first_sunday_on_or_after(dststart.replace(year=year)) end = first_sunday_on_or_after(dstend.replace(year=year)) return start, end class USTimeZone(tzinfo): def __init__(self, hours, reprname, stdname, dstname): self.stdoffset = timedelta(hours=hours) self.reprname = reprname self.stdname = stdname self.dstname = dstname def __repr__(self): return self.reprname def tzname(self, dt): if self.dst(dt): return self.dstname else: return self.stdname def utcoffset(self, dt): return self.stdoffset + self.dst(dt) def dst(self, dt): if dt is None or dt.tzinfo is None: # An exception may be sensible here, in one or both cases. # It depends on how you want to treat them. The default # fromutc() implementation (called by the default astimezone() # implementation) passes a datetime with dt.tzinfo is self. return ZERO assert dt.tzinfo is self start, end = us_dst_range(dt.year) # Can't compare naive to aware objects, so strip the timezone from # dt first. dt = dt.replace(tzinfo=None) if start + HOUR <= dt < end - HOUR: # DST is in effect. return HOUR if end - HOUR <= dt < end: # Fold (an ambiguous hour): use dt.fold to disambiguate. return ZERO if dt.fold else HOUR if start <= dt < start + HOUR: # Gap (a non-existent hour): reverse the fold rule. return HOUR if dt.fold else ZERO # DST is off. return ZERO def fromutc(self, dt): assert dt.tzinfo is self start, end = us_dst_range(dt.year) start = start.replace(tzinfo=self) end = end.replace(tzinfo=self) std_time = dt + self.stdoffset dst_time = std_time + HOUR if end <= dst_time < end + HOUR: # Repeated hour return std_time.replace(fold=1) if std_time < start or dst_time >= end: # Standard time return std_time if start <= std_time < end - HOUR: # Daylight saving time return dst_time Eastern = USTimeZone(-5, "Eastern", "EST", "EDT") Central = USTimeZone(-6, "Central", "CST", "CDT") Mountain = USTimeZone(-7, "Mountain", "MST", "MDT") Pacific = USTimeZone(-8, "Pacific", "PST", "PDT") </pre></div> </div> Note that there are unavoidable subtleties twice per year in a <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> 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: <div class="highlight-python3 notranslate"><div class="highlight"><pre> 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 </pre></div> </div> 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 <code class="docutils literal notranslate">astimezone(Eastern)</code> won’t deliver a result with <code class="docutils literal notranslate">hour == 2</code> on the day DST begins. For example, at the Spring forward transition of 2016, we get: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from datetime import datetime, timezone >>> from tzinfo_examples import HOUR, Eastern >>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc) >>> for i in range(4): ... u = u0 + i*HOUR ... t = u.astimezone(Eastern) ... print(u.time(), 'UTC =', t.time(), t.tzname()) ... 05:00:00 UTC = 00:00:00 EST 06:00:00 UTC = 01:00:00 EST 07:00:00 UTC = 03:00:00 EDT 08:00:00 UTC = 04:00:00 EDT </pre></div> </div> 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. <a class="reference internal" href="#datetime.datetime.astimezone" title="datetime.datetime.astimezone"><code class="xref py py-meth docutils literal notranslate">astimezone()</code></a> 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, but earlier times have the <a class="reference internal" href="#datetime.datetime.fold" title="datetime.datetime.fold"><code class="xref py py-attr docutils literal notranslate">fold</code></a> attribute set to 0 and the later times have it set to 1. For example, at the Fall back transition of 2016, we get: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc) >>> for i in range(4): ... u = u0 + i*HOUR ... t = u.astimezone(Eastern) ... print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold) ... 04:00:00 UTC = 00:00:00 EDT 0 05:00:00 UTC = 01:00:00 EDT 0 06:00:00 UTC = 01:00:00 EST 1 07:00:00 UTC = 02:00:00 EST 0 </pre></div> </div> Note that the <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> instances that differ only by the value of the <a class="reference internal" href="#datetime.datetime.fold" title="datetime.datetime.fold"><code class="xref py py-attr docutils literal notranslate">fold</code></a> attribute are considered equal in comparisons. Applications that can’t bear wall-time ambiguities should explicitly check the value of the <a class="reference internal" href="#datetime.datetime.fold" title="datetime.datetime.fold"><code class="xref py py-attr docutils literal notranslate">fold</code></a> attribute or avoid using hybrid <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclasses; there are no ambiguities when using <a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate">timezone</code></a>, or any other fixed-offset <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a> subclass (such as a class representing only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)). <div class="admonition seealso"> See also <blockquote> <div><dl> <dt><a class="reference internal" href="zoneinfo.html#module-zoneinfo" title="zoneinfo: IANA time zone support"><code class="xref py py-mod docutils literal notranslate">zoneinfo</code></a></dt><dd>The <code class="xref py py-mod docutils literal notranslate">datetime</code> module has a basic <a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate">timezone</code></a> class (for handling arbitrary fixed offsets from UTC) and its <a class="reference internal" href="#datetime.timezone.utc" title="datetime.timezone.utc"><code class="xref py py-attr docutils literal notranslate">timezone.utc</code></a> attribute (a UTC <code class="xref py py-class docutils literal notranslate">timezone</code> instance). <code class="docutils literal notranslate">zoneinfo</code> brings the IANA time zone database (also known as the Olson database) to Python, and its usage is recommended. </dd> </dl> </div></blockquote> <dl class="simple"> <dt><a class="reference external" href="https://www.iana.org/time-zones">IANA time zone database</a></dt><dd>The Time Zone Database (often called tz, tzdata or zoneinfo) contains code and data that represent the history of local time for many representative locations around the globe. It is updated periodically to reflect changes made by political bodies to time zone boundaries, UTC offsets, and daylight-saving rules. </dd> </dl> </div> </section> <section id="timezone-objects"> <h2><a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate">timezone</code></a> Objects<a class="headerlink" href="#timezone-objects" title="Link to this heading">¶</a></h2> The <a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate">timezone</code></a> class is a subclass of <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate">tzinfo</code></a>, each instance of which represents a time zone defined by a fixed offset from UTC. Objects of this class cannot be used to represent time zone 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. <dl class="py class"> <dt class="sig sig-object py" id="datetime.timezone"> class datetime.timezone(offset, name=None)<a class="headerlink" href="#datetime.timezone" title="Link to this definition">¶</a></dt> <dd>The offset argument must be specified as a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> object representing the difference between the local time and UTC. It must be strictly between <code class="docutils literal notranslate">-timedelta(hours=24)</code> and <code class="docutils literal notranslate">timedelta(hours=24)</code>, otherwise <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> is raised. The name argument is optional. If specified it must be a string that will be used as the value returned by the <a class="reference internal" href="#datetime.datetime.tzname" title="datetime.datetime.tzname"><code class="xref py py-meth docutils literal notranslate">datetime.tzname()</code></a> method. <div class="versionadded"> Added in version 3.2. </div> <div class="versionchanged"> Changed in version 3.7: The UTC offset is not restricted to a whole number of minutes. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.timezone.utcoffset"> timezone.utcoffset(dt)<a class="headerlink" href="#datetime.timezone.utcoffset" title="Link to this definition">¶</a></dt> <dd>Return the fixed value specified when the <a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate">timezone</code></a> instance is constructed. The dt argument is ignored. The return value is a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate">timedelta</code></a> instance equal to the difference between the local time and UTC. <div class="versionchanged"> Changed in version 3.7: The UTC offset is not restricted to a whole number of minutes. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.timezone.tzname"> timezone.tzname(dt)<a class="headerlink" href="#datetime.timezone.tzname" title="Link to this definition">¶</a></dt> <dd>Return the fixed value specified when the <a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate">timezone</code></a> instance is constructed. If name is not provided in the constructor, the name returned by <code class="docutils literal notranslate">tzname(dt)</code> is generated from the value of the <code class="docutils literal notranslate">offset</code> as follows. If offset is <code class="docutils literal notranslate">timedelta(0)</code>, the name is “UTC”, otherwise it is a string in the format <code class="docutils literal notranslate">UTC±HH:MM</code>, where ± is the sign of <code class="docutils literal notranslate">offset</code>, HH and MM are two digits of <code class="docutils literal notranslate">offset.hours</code> and <code class="docutils literal notranslate">offset.minutes</code> respectively. <div class="versionchanged"> Changed in version 3.6: Name generated from <code class="docutils literal notranslate">offset=timedelta(0)</code> is now plain <code class="docutils literal notranslate">'UTC'</code>, not <code class="docutils literal notranslate">'UTC+00:00'</code>. </div> </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.timezone.dst"> timezone.dst(dt)<a class="headerlink" href="#datetime.timezone.dst" title="Link to this definition">¶</a></dt> <dd>Always returns <code class="docutils literal notranslate">None</code>. </dd></dl> <dl class="py method"> <dt class="sig sig-object py" id="datetime.timezone.fromutc"> timezone.fromutc(dt)<a class="headerlink" href="#datetime.timezone.fromutc" title="Link to this definition">¶</a></dt> <dd>Return <code class="docutils literal notranslate">dt + offset</code>. The dt argument must be an aware <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> instance, with <code class="docutils literal notranslate">tzinfo</code> set to <code class="docutils literal notranslate">self</code>. </dd></dl> Class attributes: <dl class="py attribute"> <dt class="sig sig-object py" id="datetime.timezone.utc"> timezone.utc<a class="headerlink" href="#datetime.timezone.utc" title="Link to this definition">¶</a></dt> <dd>The UTC time zone, <code class="docutils literal notranslate">timezone(timedelta(0))</code>. </dd></dl> </section> <section id="strftime-and-strptime-behavior"> <h2><a class="reference internal" href="#datetime.datetime.strftime" title="datetime.datetime.strftime"><code class="xref py py-meth docutils literal notranslate">strftime()</code></a> and <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">strptime()</code></a> Behavior<a class="headerlink" href="#strftime-and-strptime-behavior" title="Link to this heading">¶</a></h2> <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a>, <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a>, and <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> objects all support a <code class="docutils literal notranslate">strftime(format)</code> method, to create a string representing the time under the control of an explicit format string. Conversely, the <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">datetime.strptime()</code></a> class method creates a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object from a string representing a date and time and a corresponding format string. The table below provides a high-level comparison of <a class="reference internal" href="#datetime.datetime.strftime" title="datetime.datetime.strftime"><code class="xref py py-meth docutils literal notranslate">strftime()</code></a> versus <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">strptime()</code></a>: <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head"></th> <th class="head"><code class="docutils literal notranslate">strftime</code></th> <th class="head"><code class="docutils literal notranslate">strptime</code></th> </tr> </thead> <tbody> <tr class="row-even"><td>Usage</td> <td>Convert object to a string according to a given format</td> <td>Parse a string into a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object given a corresponding format</td> </tr> <tr class="row-odd"><td>Type of method</td> <td>Instance method</td> <td>Class method</td> </tr> <tr class="row-even"><td>Method of</td> <td><a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a>; <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a>; <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a></td> <td><a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a></td> </tr> <tr class="row-odd"><td>Signature</td> <td><code class="docutils literal notranslate">strftime(format)</code></td> <td><code class="docutils literal notranslate">strptime(date_string, format)</code></td> </tr> </tbody> </table> <blockquote> <div></div></blockquote> <section id="strftime-and-strptime-format-codes"> <h3><a class="reference internal" href="#datetime.datetime.strftime" title="datetime.datetime.strftime"><code class="xref py py-meth docutils literal notranslate">strftime()</code></a> and <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">strptime()</code></a> Format Codes<a class="headerlink" href="#strftime-and-strptime-format-codes" title="Link to this heading">¶</a></h3> These methods accept format codes that can be used to parse and format dates: <div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> datetime.strptime('31/01/22 23:59:59.999999', ... '%d/%m/%y %H:%M:%S.%f') datetime.datetime(2022, 1, 31, 23, 59, 59, 999999) >>> _.strftime('%a %d %b %Y, %I:%M%p') 'Mon 31 Jan 2022, 11:59PM' </pre></div> </div> The following is a list of all the format codes that the 1989 C standard requires, and these work on all platforms with a standard C implementation. <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Directive</th> <th class="head">Meaning</th> <th class="head">Example</th> <th class="head">Notes</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">%a</code></td> <td>Weekday as locale’s abbreviated name.</td> <td><div class="line-block"> <div class="line">Sun, Mon, …, Sat (en_US);</div> <div class="line">So, Mo, …, Sa (de_DE)</div> </div> </td> <td>(1)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">%A</code></td> <td>Weekday as locale’s full name.</td> <td><div class="line-block"> <div class="line">Sunday, Monday, …, Saturday (en_US);</div> <div class="line">Sonntag, Montag, …, Samstag (de_DE)</div> </div> </td> <td>(1)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">%w</code></td> <td>Weekday as a decimal number, where 0 is Sunday and 6 is Saturday.</td> <td>0, 1, …, 6</td> <td></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">%d</code></td> <td>Day of the month as a zero-padded decimal number.</td> <td>01, 02, …, 31</td> <td>(9)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">%b</code></td> <td>Month as locale’s abbreviated name.</td> <td><div class="line-block"> <div class="line">Jan, Feb, …, Dec (en_US);</div> <div class="line">Jan, Feb, …, Dez (de_DE)</div> </div> </td> <td>(1)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">%B</code></td> <td>Month as locale’s full name.</td> <td><div class="line-block"> <div class="line">January, February, …, December (en_US);</div> <div class="line">Januar, Februar, …, Dezember (de_DE)</div> </div> </td> <td>(1)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">%m</code></td> <td>Month as a zero-padded decimal number.</td> <td>01, 02, …, 12</td> <td>(9)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">%y</code></td> <td>Year without century as a zero-padded decimal number.</td> <td>00, 01, …, 99</td> <td>(9)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">%Y</code></td> <td>Year with century as a decimal number.</td> <td>0001, 0002, …, 2013, 2014, …, 9998, 9999</td> <td>(2)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">%H</code></td> <td>Hour (24-hour clock) as a zero-padded decimal number.</td> <td>00, 01, …, 23</td> <td>(9)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">%I</code></td> <td>Hour (12-hour clock) as a zero-padded decimal number.</td> <td>01, 02, …, 12</td> <td>(9)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">%p</code></td> <td>Locale’s equivalent of either AM or PM.</td> <td><div class="line-block"> <div class="line">AM, PM (en_US);</div> <div class="line">am, pm (de_DE)</div> </div> </td> <td>(1), (3)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">%M</code></td> <td>Minute as a zero-padded decimal number.</td> <td>00, 01, …, 59</td> <td>(9)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">%S</code></td> <td>Second as a zero-padded decimal number.</td> <td>00, 01, …, 59</td> <td>(4), (9)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">%f</code></td> <td>Microsecond as a decimal number, zero-padded to 6 digits.</td> <td>000000, 000001, …, 999999</td> <td>(5)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">%z</code></td> <td>UTC offset in the form <code class="docutils literal notranslate">±HHMM[SS[.ffffff]]</code> (empty string if the object is naive).</td> <td>(empty), +0000, -0400, +1030, +063415, -030712.345216</td> <td>(6)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">%Z</code></td> <td>Time zone name (empty string if the object is naive).</td> <td>(empty), UTC, GMT</td> <td>(6)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">%j</code></td> <td>Day of the year as a zero-padded decimal number.</td> <td>001, 002, …, 366</td> <td>(9)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">%U</code></td> <td>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.</td> <td>00, 01, …, 53</td> <td>(7), (9)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">%W</code></td> <td>Week number of the year (Monday as the first day of the week) as a zero-padded decimal number. All days in a new year preceding the first Monday are considered to be in week 0.</td> <td>00, 01, …, 53</td> <td>(7), (9)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">%c</code></td> <td>Locale’s appropriate date and time representation.</td> <td><div class="line-block"> <div class="line">Tue Aug 16 21:30:00 1988 (en_US);</div> <div class="line">Di 16 Aug 21:30:00 1988 (de_DE)</div> </div> </td> <td>(1)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">%x</code></td> <td>Locale’s appropriate date representation.</td> <td><div class="line-block"> <div class="line">08/16/88 (None);</div> <div class="line">08/16/1988 (en_US);</div> <div class="line">16.08.1988 (de_DE)</div> </div> </td> <td>(1)</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">%X</code></td> <td>Locale’s appropriate time representation.</td> <td><div class="line-block"> <div class="line">21:30:00 (en_US);</div> <div class="line">21:30:00 (de_DE)</div> </div> </td> <td>(1)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">%%</code></td> <td>A literal <code class="docutils literal notranslate">'%'</code> character.</td> <td>%</td> <td></td> </tr> </tbody> </table> Several additional directives not required by the C89 standard are included for convenience. These parameters all correspond to ISO 8601 date values. <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">Directive</th> <th class="head">Meaning</th> <th class="head">Example</th> <th class="head">Notes</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">%G</code></td> <td>ISO 8601 year with century representing the year that contains the greater part of the ISO week (<code class="docutils literal notranslate">%V</code>).</td> <td>0001, 0002, …, 2013, 2014, …, 9998, 9999</td> <td>(8)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">%u</code></td> <td>ISO 8601 weekday as a decimal number where 1 is Monday.</td> <td>1, 2, …, 7</td> <td></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">%V</code></td> <td>ISO 8601 week as a decimal number with Monday as the first day of the week. Week 01 is the week containing Jan 4.</td> <td>01, 02, …, 53</td> <td>(8), (9)</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">%:z</code></td> <td>UTC offset in the form <code class="docutils literal notranslate">±HH:MM[:SS[.ffffff]]</code> (empty string if the object is naive).</td> <td>(empty), +00:00, -04:00, +10:30, +06:34:15, -03:07:12.345216</td> <td>(6)</td> </tr> </tbody> </table> These may not be available on all platforms when used with the <a class="reference internal" href="#datetime.datetime.strftime" title="datetime.datetime.strftime"><code class="xref py py-meth docutils literal notranslate">strftime()</code></a> method. The ISO 8601 year and ISO 8601 week directives are not interchangeable with the year and week number directives above. Calling <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">strptime()</code></a> with incomplete or ambiguous ISO 8601 directives will raise a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a>. The full set of format codes supported varies across platforms, because Python calls the platform C library’s <code class="xref c c-func docutils literal notranslate">strftime()</code> function, and platform variations are common. To see the full set of format codes supported on your platform, consult the <a class="manpage reference external" href="https://manpages.debian.org/strftime(3)">strftime(3)</a> documentation. There are also differences between platforms in handling of unsupported format specifiers. <div class="versionadded"> Added in version 3.6: <code class="docutils literal notranslate">%G</code>, <code class="docutils literal notranslate">%u</code> and <code class="docutils literal notranslate">%V</code> were added. </div> <div class="versionadded"> Added in version 3.12: <code class="docutils literal notranslate">%:z</code> was added. </div> </section> <section id="technical-detail"> <h3>Technical Detail<a class="headerlink" href="#technical-detail" title="Link to this heading">¶</a></h3> Broadly speaking, <code class="docutils literal notranslate">d.strftime(fmt)</code> acts like the <a class="reference internal" href="time.html#module-time" title="time: Time access and conversions."><code class="xref py py-mod docutils literal notranslate">time</code></a> module’s <code class="docutils literal notranslate">time.strftime(fmt, d.timetuple())</code> although not all objects support a <a class="reference internal" href="#datetime.date.timetuple" title="datetime.date.timetuple"><code class="xref py py-meth docutils literal notranslate">timetuple()</code></a> method. For the <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">datetime.strptime()</code></a> class method, the default value is <code class="docutils literal notranslate">1900-01-01T00:00:00.000</code>: any components not specified in the format string will be pulled from the default value. <a class="footnote-reference brackets" href="#id8" id="id4" role="doc-noteref">[4]</a> Using <code class="docutils literal notranslate">datetime.strptime(date_string, format)</code> is equivalent to: <div class="highlight-python3 notranslate"><div class="highlight"><pre>datetime(*(time.strptime(date_string, format)[0:6])) </pre></div> </div> except when the format includes sub-second components or time zone offset information, which are supported in <code class="docutils literal notranslate">datetime.strptime</code> but are discarded by <code class="docutils literal notranslate">time.strptime</code>. For <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate">time</code></a> objects, the format codes for year, month, and day should not be used, as <code class="xref py py-class docutils literal notranslate">time</code> objects have no such values. If they’re used anyway, 1900 is substituted for the year, and 1 for the month and day. For <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> objects, the format codes for hours, minutes, seconds, and microseconds should not be used, as <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate">date</code></a> objects have no such values. If they’re used anyway, 0 is substituted for them. For the same reason, handling of format strings containing Unicode code points that can’t be represented in the charset of the current locale is also platform-dependent. On some platforms such code points are preserved intact in the output, while on others <code class="docutils literal notranslate">strftime</code> may raise <a class="reference internal" href="exceptions.html#UnicodeError" title="UnicodeError"><code class="xref py py-exc docutils literal notranslate">UnicodeError</code></a> or return an empty string instead. Notes: <ol class="arabic"> <li>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 non-ASCII characters.</li> <li>The <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">strptime()</code></a> method can parse years in the full [1, 9999] range, but years < 1000 must be zero-filled to 4-digit width. <div class="versionchanged"> Changed in version 3.2: In previous versions, <a class="reference internal" href="#datetime.datetime.strftime" title="datetime.datetime.strftime"><code class="xref py py-meth docutils literal notranslate">strftime()</code></a> method was restricted to years >= 1900. </div> <div class="versionchanged"> Changed in version 3.3: In version 3.2, <a class="reference internal" href="#datetime.datetime.strftime" title="datetime.datetime.strftime"><code class="xref py py-meth docutils literal notranslate">strftime()</code></a> method was restricted to years >= 1000. </div> </li> <li>When used with the <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">strptime()</code></a> method, the <code class="docutils literal notranslate">%p</code> directive only affects the output hour field if the <code class="docutils literal notranslate">%I</code> directive is used to parse the hour.</li> <li>Unlike the <a class="reference internal" href="time.html#module-time" title="time: Time access and conversions."><code class="xref py py-mod docutils literal notranslate">time</code></a> module, the <code class="xref py py-mod docutils literal notranslate">datetime</code> module does not support leap seconds.</li> <li>When used with the <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">strptime()</code></a> method, the <code class="docutils literal notranslate">%f</code> directive accepts from one to six digits and zero pads on the right. <code class="docutils literal notranslate">%f</code> is an extension to the set of format characters in the C standard (but implemented separately in datetime objects, and therefore always available).</li> <li>For a naive object, the <code class="docutils literal notranslate">%z</code>, <code class="docutils literal notranslate">%:z</code> and <code class="docutils literal notranslate">%Z</code> format codes are replaced by empty strings. For an aware object: <dl class="simple"> <dt><code class="docutils literal notranslate">%z</code></dt><dd><a class="reference internal" href="#datetime.datetime.utcoffset" title="datetime.datetime.utcoffset"><code class="xref py py-meth docutils literal notranslate">utcoffset()</code></a> is transformed into a string of the form <code class="docutils literal notranslate">±HHMM[SS[.ffffff]]</code>, where <code class="docutils literal notranslate">HH</code> is a 2-digit string giving the number of UTC offset hours, <code class="docutils literal notranslate">MM</code> is a 2-digit string giving the number of UTC offset minutes, <code class="docutils literal notranslate">SS</code> is a 2-digit string giving the number of UTC offset seconds and <code class="docutils literal notranslate">ffffff</code> is a 6-digit string giving the number of UTC offset microseconds. The <code class="docutils literal notranslate">ffffff</code> part is omitted when the offset is a whole number of seconds and both the <code class="docutils literal notranslate">ffffff</code> and the <code class="docutils literal notranslate">SS</code> part is omitted when the offset is a whole number of minutes. For example, if <a class="reference internal" href="#datetime.datetime.utcoffset" title="datetime.datetime.utcoffset"><code class="xref py py-meth docutils literal notranslate">utcoffset()</code></a> returns <code class="docutils literal notranslate">timedelta(hours=-3, minutes=-30)</code>, <code class="docutils literal notranslate">%z</code> is replaced with the string <code class="docutils literal notranslate">'-0330'</code>. </dd> </dl> <div class="versionchanged"> Changed in version 3.7: The UTC offset is not restricted to a whole number of minutes. </div> <div class="versionchanged"> Changed in version 3.7: When the <code class="docutils literal notranslate">%z</code> directive is provided to the <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">strptime()</code></a> method, the UTC offsets can have a colon as a separator between hours, minutes and seconds. For example, <code class="docutils literal notranslate">'+01:00:00'</code> will be parsed as an offset of one hour. In addition, providing <code class="docutils literal notranslate">'Z'</code> is identical to <code class="docutils literal notranslate">'+00:00'</code>. </div> <dl> <dt><code class="docutils literal notranslate">%:z</code></dt><dd>Behaves exactly as <code class="docutils literal notranslate">%z</code>, but has a colon separator added between hours, minutes and seconds. </dd> <dt><code class="docutils literal notranslate">%Z</code></dt><dd>In <a class="reference internal" href="#datetime.datetime.strftime" title="datetime.datetime.strftime"><code class="xref py py-meth docutils literal notranslate">strftime()</code></a>, <code class="docutils literal notranslate">%Z</code> is replaced by an empty string if <a class="reference internal" href="#datetime.datetime.tzname" title="datetime.datetime.tzname"><code class="xref py py-meth docutils literal notranslate">tzname()</code></a> returns <code class="docutils literal notranslate">None</code>; otherwise <code class="docutils literal notranslate">%Z</code> is replaced by the returned value, which must be a string. <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">strptime()</code></a> only accepts certain values for <code class="docutils literal notranslate">%Z</code>: <ol class="arabic simple"> <li>any value in <code class="docutils literal notranslate">time.tzname</code> for your machine’s locale</li> <li>the hard-coded values <code class="docutils literal notranslate">UTC</code> and <code class="docutils literal notranslate">GMT</code></li> </ol> So someone living in Japan may have <code class="docutils literal notranslate">JST</code>, <code class="docutils literal notranslate">UTC</code>, and <code class="docutils literal notranslate">GMT</code> as valid values, but probably not <code class="docutils literal notranslate">EST</code>. It will raise <code class="docutils literal notranslate">ValueError</code> for invalid values. </dd> </dl> <div class="versionchanged"> Changed in version 3.2: When the <code class="docutils literal notranslate">%z</code> directive is provided to the <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">strptime()</code></a> method, an aware <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate">datetime</code></a> object will be produced. The <code class="docutils literal notranslate">tzinfo</code> of the result will be set to a <a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate">timezone</code></a> instance. </div> </li> <li>When used with the <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">strptime()</code></a> method, <code class="docutils literal notranslate">%U</code> and <code class="docutils literal notranslate">%W</code> are only used in calculations when the day of the week and the calendar year (<code class="docutils literal notranslate">%Y</code>) are specified.</li> <li>Similar to <code class="docutils literal notranslate">%U</code> and <code class="docutils literal notranslate">%W</code>, <code class="docutils literal notranslate">%V</code> is only used in calculations when the day of the week and the ISO year (<code class="docutils literal notranslate">%G</code>) are specified in a <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">strptime()</code></a> format string. Also note that <code class="docutils literal notranslate">%G</code> and <code class="docutils literal notranslate">%Y</code> are not interchangeable.</li> <li>When used with the <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">strptime()</code></a> method, the leading zero is optional for formats <code class="docutils literal notranslate">%d</code>, <code class="docutils literal notranslate">%m</code>, <code class="docutils literal notranslate">%H</code>, <code class="docutils literal notranslate">%I</code>, <code class="docutils literal notranslate">%M</code>, <code class="docutils literal notranslate">%S</code>, <code class="docutils literal notranslate">%j</code>, <code class="docutils literal notranslate">%U</code>, <code class="docutils literal notranslate">%W</code>, and <code class="docutils literal notranslate">%V</code>. Format <code class="docutils literal notranslate">%y</code> does require a leading zero.</li> <li>When parsing a month and day using <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">strptime()</code></a>, always include a year in the format. If the value you need to parse lacks a year, append an explicit dummy leap year. Otherwise your code will raise an exception when it encounters leap day because the default year used by the parser is not a leap year. Users run into this bug every four years… <div class="highlight-pycon notranslate"><div class="highlight"><pre>>>> month_day = "02/29" >>> datetime.strptime(f"{month_day};1984", "%m/%d;%Y") # No leap year bug. datetime.datetime(1984, 2, 29, 0, 0) </pre></div> </div> <div class="deprecated-removed"> Deprecated since version 3.13, will be removed in version 3.15: <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate">strptime()</code></a> calls using a format string containing a day of month without a year now emit a <a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate">DeprecationWarning</code></a>. In 3.15 or later we may change this into an error or change the default year to a leap year. See <a class="reference external" href="https://github.com/python/cpython/issues/70647">gh-70647</a>. </div> </li> </ol> Footnotes <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id5" role="doc-footnote"> [<a role="doc-backlink" href="#id1">1</a>] If, that is, we ignore the effects of Relativity </aside> <aside class="footnote brackets" id="id6" role="doc-footnote"> [<a role="doc-backlink" href="#id2">2</a>] 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. </aside> <aside class="footnote brackets" id="id7" role="doc-footnote"> [<a role="doc-backlink" href="#id3">3</a>] See R. H. van Gent’s <a class="reference external" href="https://web.archive.org/web/20220531051136/https://webspace.science.uu.nl/~gent0113/calendar/isocalendar.htm">guide to the mathematics of the ISO 8601 calendar</a> for a good explanation. </aside> <aside class="footnote brackets" id="id8" role="doc-footnote"> [<a role="doc-backlink" href="#id4">4</a>] Passing <code class="docutils literal notranslate">datetime.strptime('Feb 29', '%b %d')</code> will fail since 1900 is not a leap year. </aside> </aside> </section> </section> </section> <div class="clearer"></div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="Main"> <div class="sphinxsidebarwrapper"> <div> <h3><a href="../contents.html">Table of Contents</a></h3> <ul> <li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate">datetime</code> — Basic date and time types</a><ul> <li><a class="reference internal" href="#aware-and-naive-objects">Aware and Naive Objects</a></li> <li><a class="reference internal" href="#constants">Constants</a><ul> <li><a class="reference internal" href="#datetime.MINYEAR"><code class="docutils literal notranslate">MINYEAR</code></a></li> <li><a class="reference internal" href="#datetime.MAXYEAR"><code class="docutils literal notranslate">MAXYEAR</code></a></li> <li><a class="reference internal" href="#datetime.UTC"><code class="docutils literal notranslate">UTC</code></a></li> </ul> </li> <li><a class="reference internal" href="#available-types">Available Types</a><ul> <li><a class="reference internal" href="#common-properties">Common Properties</a></li> <li><a class="reference internal" href="#determining-if-an-object-is-aware-or-naive">Determining if an Object is Aware or Naive</a></li> </ul> </li> <li><a class="reference internal" href="#timedelta-objects"><code class="xref py py-class docutils literal notranslate">timedelta</code> Objects</a><ul> <li><a class="reference internal" href="#datetime.timedelta"><code class="docutils literal notranslate">timedelta</code></a></li> <li><a class="reference internal" href="#datetime.timedelta.min"><code class="docutils literal notranslate">min</code></a></li> <li><a class="reference internal" href="#datetime.timedelta.max"><code class="docutils literal notranslate">max</code></a></li> <li><a class="reference internal" href="#datetime.timedelta.resolution"><code class="docutils literal notranslate">resolution</code></a></li> <li><a class="reference internal" href="#datetime.timedelta.days"><code class="docutils literal notranslate">days</code></a></li> <li><a class="reference internal" href="#datetime.timedelta.seconds"><code class="docutils literal notranslate">seconds</code></a></li> <li><a class="reference internal" href="#datetime.timedelta.microseconds"><code class="docutils literal notranslate">microseconds</code></a></li> <li><a class="reference internal" href="#datetime.timedelta.total_seconds"><code class="docutils literal notranslate">total_seconds()</code></a></li> <li><a class="reference internal" href="#examples-of-usage-timedelta">Examples of usage: <code class="xref py py-class docutils literal notranslate">timedelta</code></a></li> </ul> </li> <li><a class="reference internal" href="#date-objects"><code class="xref py py-class docutils literal notranslate">date</code> Objects</a><ul> <li><a class="reference internal" href="#datetime.date"><code class="docutils literal notranslate">date</code></a></li> <li><a class="reference internal" href="#datetime.date.today"><code class="docutils literal notranslate">today()</code></a></li> <li><a class="reference internal" href="#datetime.date.fromtimestamp"><code class="docutils literal notranslate">fromtimestamp()</code></a></li> <li><a class="reference internal" href="#datetime.date.fromordinal"><code class="docutils literal notranslate">fromordinal()</code></a></li> <li><a class="reference internal" href="#datetime.date.fromisoformat"><code class="docutils literal notranslate">fromisoformat()</code></a></li> <li><a class="reference internal" href="#datetime.date.fromisocalendar"><code class="docutils literal notranslate">fromisocalendar()</code></a></li> <li><a class="reference internal" href="#datetime.date.min"><code class="docutils literal notranslate">min</code></a></li> <li><a class="reference internal" href="#datetime.date.max"><code class="docutils literal notranslate">max</code></a></li> <li><a class="reference internal" href="#datetime.date.resolution"><code class="docutils literal notranslate">resolution</code></a></li> <li><a class="reference internal" href="#datetime.date.year"><code class="docutils literal notranslate">year</code></a></li> <li><a class="reference internal" href="#datetime.date.month"><code class="docutils literal notranslate">month</code></a></li> <li><a class="reference internal" href="#datetime.date.day"><code class="docutils literal notranslate">day</code></a></li> <li><a class="reference internal" href="#datetime.date.replace"><code class="docutils literal notranslate">replace()</code></a></li> <li><a class="reference internal" href="#datetime.date.timetuple"><code class="docutils literal notranslate">timetuple()</code></a></li> <li><a class="reference internal" href="#datetime.date.toordinal"><code class="docutils literal notranslate">toordinal()</code></a></li> <li><a class="reference internal" href="#datetime.date.weekday"><code class="docutils literal notranslate">weekday()</code></a></li> <li><a class="reference internal" href="#datetime.date.isoweekday"><code class="docutils literal notranslate">isoweekday()</code></a></li> <li><a class="reference internal" href="#datetime.date.isocalendar"><code class="docutils literal notranslate">isocalendar()</code></a></li> <li><a class="reference internal" href="#datetime.date.isoformat"><code class="docutils literal notranslate">isoformat()</code></a></li> <li><a class="reference internal" href="#datetime.date.__str__"><code class="docutils literal notranslate">__str__()</code></a></li> <li><a class="reference internal" href="#datetime.date.ctime"><code class="docutils literal notranslate">ctime()</code></a></li> <li><a class="reference internal" href="#datetime.date.strftime"><code class="docutils literal notranslate">strftime()</code></a></li> <li><a class="reference internal" href="#datetime.date.__format__"><code class="docutils literal notranslate">__format__()</code></a></li> <li><a class="reference internal" href="#examples-of-usage-date">Examples of Usage: <code class="xref py py-class docutils literal notranslate">date</code></a></li> </ul> </li> <li><a class="reference internal" href="#datetime-objects"><code class="xref py py-class docutils literal notranslate">datetime</code> Objects</a><ul> <li><a class="reference internal" href="#datetime.datetime"><code class="docutils literal notranslate">datetime</code></a></li> <li><a class="reference internal" href="#datetime.datetime.today"><code class="docutils literal notranslate">today()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.now"><code class="docutils literal notranslate">now()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.utcnow"><code class="docutils literal notranslate">utcnow()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.fromtimestamp"><code class="docutils literal notranslate">fromtimestamp()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.utcfromtimestamp"><code class="docutils literal notranslate">utcfromtimestamp()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.fromordinal"><code class="docutils literal notranslate">fromordinal()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.combine"><code class="docutils literal notranslate">combine()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.fromisoformat"><code class="docutils literal notranslate">fromisoformat()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.fromisocalendar"><code class="docutils literal notranslate">fromisocalendar()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.strptime"><code class="docutils literal notranslate">strptime()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.min"><code class="docutils literal notranslate">min</code></a></li> <li><a class="reference internal" href="#datetime.datetime.max"><code class="docutils literal notranslate">max</code></a></li> <li><a class="reference internal" href="#datetime.datetime.resolution"><code class="docutils literal notranslate">resolution</code></a></li> <li><a class="reference internal" href="#datetime.datetime.year"><code class="docutils literal notranslate">year</code></a></li> <li><a class="reference internal" href="#datetime.datetime.month"><code class="docutils literal notranslate">month</code></a></li> <li><a class="reference internal" href="#datetime.datetime.day"><code class="docutils literal notranslate">day</code></a></li> <li><a class="reference internal" href="#datetime.datetime.hour"><code class="docutils literal notranslate">hour</code></a></li> <li><a class="reference internal" href="#datetime.datetime.minute"><code class="docutils literal notranslate">minute</code></a></li> <li><a class="reference internal" href="#datetime.datetime.second"><code class="docutils literal notranslate">second</code></a></li> <li><a class="reference internal" href="#datetime.datetime.microsecond"><code class="docutils literal notranslate">microsecond</code></a></li> <li><a class="reference internal" href="#datetime.datetime.tzinfo"><code class="docutils literal notranslate">tzinfo</code></a></li> <li><a class="reference internal" href="#datetime.datetime.fold"><code class="docutils literal notranslate">fold</code></a></li> <li><a class="reference internal" href="#datetime.datetime.date"><code class="docutils literal notranslate">date()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.time"><code class="docutils literal notranslate">time()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.timetz"><code class="docutils literal notranslate">timetz()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.replace"><code class="docutils literal notranslate">replace()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.astimezone"><code class="docutils literal notranslate">astimezone()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.utcoffset"><code class="docutils literal notranslate">utcoffset()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.dst"><code class="docutils literal notranslate">dst()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.tzname"><code class="docutils literal notranslate">tzname()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.timetuple"><code class="docutils literal notranslate">timetuple()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.utctimetuple"><code class="docutils literal notranslate">utctimetuple()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.toordinal"><code class="docutils literal notranslate">toordinal()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.timestamp"><code class="docutils literal notranslate">timestamp()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.weekday"><code class="docutils literal notranslate">weekday()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.isoweekday"><code class="docutils literal notranslate">isoweekday()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.isocalendar"><code class="docutils literal notranslate">isocalendar()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.isoformat"><code class="docutils literal notranslate">isoformat()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.__str__"><code class="docutils literal notranslate">__str__()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.ctime"><code class="docutils literal notranslate">ctime()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.strftime"><code class="docutils literal notranslate">strftime()</code></a></li> <li><a class="reference internal" href="#datetime.datetime.__format__"><code class="docutils literal notranslate">__format__()</code></a></li> <li><a class="reference internal" href="#examples-of-usage-datetime">Examples of Usage: <code class="xref py py-class docutils literal notranslate">datetime</code></a></li> </ul> </li> <li><a class="reference internal" href="#time-objects"><code class="xref py py-class docutils literal notranslate">time</code> Objects</a><ul> <li><a class="reference internal" href="#datetime.time"><code class="docutils literal notranslate">time</code></a></li> <li><a class="reference internal" href="#datetime.time.min"><code class="docutils literal notranslate">min</code></a></li> <li><a class="reference internal" href="#datetime.time.max"><code class="docutils literal notranslate">max</code></a></li> <li><a class="reference internal" href="#datetime.time.resolution"><code class="docutils literal notranslate">resolution</code></a></li> <li><a class="reference internal" href="#datetime.time.hour"><code class="docutils literal notranslate">hour</code></a></li> <li><a class="reference internal" href="#datetime.time.minute"><code class="docutils literal notranslate">minute</code></a></li> <li><a class="reference internal" href="#datetime.time.second"><code class="docutils literal notranslate">second</code></a></li> <li><a class="reference internal" href="#datetime.time.microsecond"><code class="docutils literal notranslate">microsecond</code></a></li> <li><a class="reference internal" href="#datetime.time.tzinfo"><code class="docutils literal notranslate">tzinfo</code></a></li> <li><a class="reference internal" href="#datetime.time.fold"><code class="docutils literal notranslate">fold</code></a></li> <li><a class="reference internal" href="#datetime.time.fromisoformat"><code class="docutils literal notranslate">fromisoformat()</code></a></li> <li><a class="reference internal" href="#datetime.time.replace"><code class="docutils literal notranslate">replace()</code></a></li> <li><a class="reference internal" href="#datetime.time.isoformat"><code class="docutils literal notranslate">isoformat()</code></a></li> <li><a class="reference internal" href="#datetime.time.__str__"><code class="docutils literal notranslate">__str__()</code></a></li> <li><a class="reference internal" href="#datetime.time.strftime"><code class="docutils literal notranslate">strftime()</code></a></li> <li><a class="reference internal" href="#datetime.time.__format__"><code class="docutils literal notranslate">__format__()</code></a></li> <li><a class="reference internal" href="#datetime.time.utcoffset"><code class="docutils literal notranslate">utcoffset()</code></a></li> <li><a class="reference internal" href="#datetime.time.dst"><code class="docutils literal notranslate">dst()</code></a></li> <li><a class="reference internal" href="#datetime.time.tzname"><code class="docutils literal notranslate">tzname()</code></a></li> <li><a class="reference internal" href="#examples-of-usage-time">Examples of Usage: <code class="xref py py-class docutils literal notranslate">time</code></a></li> </ul> </li> <li><a class="reference internal" href="#tzinfo-objects"><code class="xref py py-class docutils literal notranslate">tzinfo</code> Objects</a><ul> <li><a class="reference internal" href="#datetime.tzinfo"><code class="docutils literal notranslate">tzinfo</code></a></li> <li><a class="reference internal" href="#datetime.tzinfo.utcoffset"><code class="docutils literal notranslate">utcoffset()</code></a></li> <li><a class="reference internal" href="#datetime.tzinfo.dst"><code class="docutils literal notranslate">dst()</code></a></li> <li><a class="reference internal" href="#datetime.tzinfo.tzname"><code class="docutils literal notranslate">tzname()</code></a></li> <li><a class="reference internal" href="#datetime.tzinfo.fromutc"><code class="docutils literal notranslate">fromutc()</code></a></li> </ul> </li> <li><a class="reference internal" href="#timezone-objects"><code class="xref py py-class docutils literal notranslate">timezone</code> Objects</a><ul> <li><a class="reference internal" href="#datetime.timezone"><code class="docutils literal notranslate">timezone</code></a></li> <li><a class="reference internal" href="#datetime.timezone.utcoffset"><code class="docutils literal notranslate">utcoffset()</code></a></li> <li><a class="reference internal" href="#datetime.timezone.tzname"><code class="docutils literal notranslate">tzname()</code></a></li> <li><a class="reference internal" href="#datetime.timezone.dst"><code class="docutils literal notranslate">dst()</code></a></li> <li><a class="reference internal" href="#datetime.timezone.fromutc"><code class="docutils literal notranslate">fromutc()</code></a></li> <li><a class="reference internal" href="#datetime.timezone.utc"><code class="docutils literal notranslate">utc</code></a></li> </ul> </li> <li><a class="reference internal" href="#strftime-and-strptime-behavior"><code class="xref py py-meth docutils literal notranslate">strftime()</code> and <code class="xref py py-meth docutils literal notranslate">strptime()</code> Behavior</a><ul> <li><a class="reference internal" href="#strftime-and-strptime-format-codes"><code class="xref py py-meth docutils literal notranslate">strftime()</code> and <code class="xref py py-meth docutils literal notranslate">strptime()</code> Format Codes</a></li> <li><a class="reference internal" href="#technical-detail">Technical Detail</a></li> </ul> </li> </ul> </li> </ul> </div> <div> <h4>Previous topic</h4> <a href="datatypes.html" title="previous chapter">Data Types</a> </div> <div> <h4>Next topic</h4> <a href="zoneinfo.html" title="next chapter"><code class="xref py py-mod docutils literal notranslate">zoneinfo</code> — IANA time zone support</a> </div> <div role="note" aria-label="source link"> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../bugs.html">Report a Bug</a></li> <li> <a href="https://github.com/python/cpython/blob/main/Doc/library/datetime.rst" rel="nofollow">Show Source </a> </li> </ul> </div> </div> <div id="sidebarbutton" title="Collapse sidebar"> « </div> </div> <div class="clearer"></div> </div> <div class="related" role="navigation" aria-label="Related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="../py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="zoneinfo.html" title="zoneinfo — IANA time zone support" >next</a> |</li> <li class="right" > <a href="datatypes.html" title="Data Types" >previous</a> |</li> <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="https://www.python.org/">Python</a> »</li> <li class="switchers"> <div class="language_switcher_placeholder"></div> <div class="version_switcher_placeholder"></div> </li> <li> </li> <li id="cpython-language-and-version"> <a href="../index.html">3.13.0 Documentation</a> » </li> <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li> <li class="nav-item nav-item-2"><a href="datatypes.html" >Data Types</a> »</li> <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate">datetime</code> — Basic date and time types</a></li> <li class="right"> <div class="inline-search" role="search"> <form class="inline-search" action="../search.html" method="get"> <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" /> <input type="submit" value="Go" /> </form> </div> | </li> <li class="right"> <label class="theme-selector-label"> Theme <select class="theme-selector" oninput="activateTheme(this.value)"> <option value="auto" selected>Auto</option> <option value="light">Light</option> <option value="dark">Dark</option> </select> </label> |</li> </ul> </div> <div class="footer"> © <a href="../copyright.html"> Copyright </a> 2001-2024, Python Software Foundation. This page is licensed under the Python Software Foundation License Version 2. Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License. See <a href="/license.html">History and License</a> for more information. The Python Software Foundation is a non-profit corporation. <a href="https://www.python.org/psf/donations/">Please donate.</a> Last updated on Nov 24, 2024 (17:50 UTC). <a href="/bugs.html">Found a bug</a>? Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.1.3. </div> <script type="text/javascript" src="../_static/switchers.js"></script> </body> </html>