3448 lines
401 KiB
HTML
3448 lines
401 KiB
HTML
<!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.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=23252803" />
|
||
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />
|
||
|
||
<script src="../_static/documentation_options.js?v=5d57ca2d"></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.3 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" />
|
||
|
||
<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">
|
||
<span></span>
|
||
</label>
|
||
<span class="nav-items-wrapper">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Python logo"/>
|
||
</a>
|
||
<span class="version_switcher_placeholder"></span>
|
||
<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>
|
||
</span>
|
||
</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"><span class="pre">datetime</span></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></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"><span class="pre">timedelta</span></code> Objects</a><ul>
|
||
<li><a class="reference internal" href="#examples-of-usage-timedelta">Examples of usage: <code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#date-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code> Objects</a><ul>
|
||
<li><a class="reference internal" href="#examples-of-usage-date">Examples of Usage: <code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#datetime-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code> Objects</a><ul>
|
||
<li><a class="reference internal" href="#examples-of-usage-datetime">Examples of Usage: <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#time-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code> Objects</a><ul>
|
||
<li><a class="reference internal" href="#examples-of-usage-time">Examples of Usage: <code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#tzinfo-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></code> Objects</a></li>
|
||
<li><a class="reference internal" href="#timezone-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">timezone</span></code> Objects</a></li>
|
||
<li><a class="reference internal" href="#strftime-and-strptime-behavior"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strftime()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">strptime()</span></code> Behavior</a><ul>
|
||
<li><a class="reference internal" href="#strftime-and-strptime-format-codes"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strftime()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">strptime()</span></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>
|
||
<p class="topless"><a href="datatypes.html"
|
||
title="previous chapter">Data Types</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="zoneinfo.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">zoneinfo</span></code> — IANA time zone support</a></p>
|
||
</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.3 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"><span class="pre">datetime</span></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">
|
||
<span id="datetime-basic-date-and-time-types"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">datetime</span></code> — Basic date and time types<a class="headerlink" href="#module-datetime" title="Link to this heading">¶</a></h1>
|
||
<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.13/Lib/datetime.py">Lib/datetime.py</a></p>
|
||
<hr class="docutils" />
|
||
<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">datetime</span></code> module supplies classes for manipulating dates and times.</p>
|
||
<p>While date and time arithmetic is supported, the focus of the implementation is
|
||
on efficient attribute extraction for output formatting and manipulation.</p>
|
||
<div class="admonition tip">
|
||
<p class="admonition-title">Tip</p>
|
||
<p>Skip to <a class="reference internal" href="#format-codes"><span class="std std-ref">the format codes</span></a>.</p>
|
||
</div>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<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"><span class="pre">calendar</span></code></a></dt><dd><p>General calendar related functions.</p>
|
||
</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"><span class="pre">time</span></code></a></dt><dd><p>Time access and conversions.</p>
|
||
</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"><span class="pre">zoneinfo</span></code></a></dt><dd><p>Concrete time zones representing the IANA time zone database.</p>
|
||
</dd>
|
||
<dt>Package <a class="reference external" href="https://dateutil.readthedocs.io/en/stable/">dateutil</a></dt><dd><p>Third-party library with expanded time zone and parsing support.</p>
|
||
</dd>
|
||
<dt>Package <a class="extlink-pypi reference external" href="https://pypi.org/project/DateType/">DateType</a></dt><dd><p>Third-party library that introduces distinct static types to e.g. allow
|
||
<a class="reference internal" href="../glossary.html#term-static-type-checker"><span class="xref std std-term">static type checkers</span></a>
|
||
to differentiate between naive and aware datetimes.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<section id="aware-and-naive-objects">
|
||
<span id="datetime-naive-aware"></span><h2>Aware and Naive Objects<a class="headerlink" href="#aware-and-naive-objects" title="Link to this heading">¶</a></h2>
|
||
<p>Date and time objects may be categorized as “aware” or “naive” depending on
|
||
whether or not they include time zone information.</p>
|
||
<p>With sufficient knowledge of applicable algorithmic and political time
|
||
adjustments, such as time zone and daylight saving time information,
|
||
an <strong>aware</strong> 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"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p>
|
||
<p>A <strong>naive</strong> 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.</p>
|
||
<p>For applications requiring aware objects, <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> and <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a>
|
||
objects have an optional time zone information attribute, <code class="xref py py-attr docutils literal notranslate"><span class="pre">tzinfo</span></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"><span class="pre">tzinfo</span></code></a> class.
|
||
These <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></code></a> objects capture information about the offset from UTC
|
||
time, the time zone name, and whether daylight saving time is in effect.</p>
|
||
<p>Only one concrete <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></code></a> class, the <a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate"><span class="pre">timezone</span></code></a> class, is
|
||
supplied by the <code class="xref py py-mod docutils literal notranslate"><span class="pre">datetime</span></code> module. The <code class="xref py py-class docutils literal notranslate"><span class="pre">timezone</span></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.</p>
|
||
</section>
|
||
<section id="constants">
|
||
<h2>Constants<a class="headerlink" href="#constants" title="Link to this heading">¶</a></h2>
|
||
<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">datetime</span></code> module exports the following constants:</p>
|
||
<dl class="py data">
|
||
<dt class="sig sig-object py" id="datetime.MINYEAR">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">MINYEAR</span></span><a class="headerlink" href="#datetime.MINYEAR" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">date</span></code></a> or <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> object.
|
||
<a class="reference internal" href="#datetime.MINYEAR" title="datetime.MINYEAR"><code class="xref py py-const docutils literal notranslate"><span class="pre">MINYEAR</span></code></a> is 1.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py data">
|
||
<dt class="sig sig-object py" id="datetime.MAXYEAR">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">MAXYEAR</span></span><a class="headerlink" href="#datetime.MAXYEAR" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">date</span></code></a> or <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> object.
|
||
<a class="reference internal" href="#datetime.MAXYEAR" title="datetime.MAXYEAR"><code class="xref py py-const docutils literal notranslate"><span class="pre">MAXYEAR</span></code></a> is 9999.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py data">
|
||
<dt class="sig sig-object py" id="datetime.UTC">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">UTC</span></span><a class="headerlink" href="#datetime.UTC" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">datetime.timezone.utc</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.11.</span></p>
|
||
</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">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">date</span></span></dt>
|
||
<dd><p>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"><span class="pre">year</span></code></a>, <a class="reference internal" href="#datetime.date.month" title="datetime.date.month"><code class="xref py py-attr docutils literal notranslate"><span class="pre">month</span></code></a>, and
|
||
<a class="reference internal" href="#datetime.date.day" title="datetime.date.day"><code class="xref py py-attr docutils literal notranslate"><span class="pre">day</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">time</span></span></dt>
|
||
<dd><p>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"><span class="pre">hour</span></code></a>, <a class="reference internal" href="#datetime.time.minute" title="datetime.time.minute"><code class="xref py py-attr docutils literal notranslate"><span class="pre">minute</span></code></a>, <a class="reference internal" href="#datetime.time.second" title="datetime.time.second"><code class="xref py py-attr docutils literal notranslate"><span class="pre">second</span></code></a>, <a class="reference internal" href="#datetime.time.microsecond" title="datetime.time.microsecond"><code class="xref py py-attr docutils literal notranslate"><span class="pre">microsecond</span></code></a>,
|
||
and <a class="reference internal" href="#datetime.time.tzinfo" title="datetime.time.tzinfo"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tzinfo</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">datetime</span></span></dt>
|
||
<dd><p>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"><span class="pre">year</span></code></a>, <a class="reference internal" href="#datetime.datetime.month" title="datetime.datetime.month"><code class="xref py py-attr docutils literal notranslate"><span class="pre">month</span></code></a>,
|
||
<a class="reference internal" href="#datetime.datetime.day" title="datetime.datetime.day"><code class="xref py py-attr docutils literal notranslate"><span class="pre">day</span></code></a>, <a class="reference internal" href="#datetime.datetime.hour" title="datetime.datetime.hour"><code class="xref py py-attr docutils literal notranslate"><span class="pre">hour</span></code></a>, <a class="reference internal" href="#datetime.datetime.minute" title="datetime.datetime.minute"><code class="xref py py-attr docutils literal notranslate"><span class="pre">minute</span></code></a>, <a class="reference internal" href="#datetime.datetime.second" title="datetime.datetime.second"><code class="xref py py-attr docutils literal notranslate"><span class="pre">second</span></code></a>, <a class="reference internal" href="#datetime.datetime.microsecond" title="datetime.datetime.microsecond"><code class="xref py py-attr docutils literal notranslate"><span class="pre">microsecond</span></code></a>,
|
||
and <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tzinfo</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">timedelta</span></span></dt>
|
||
<dd><p>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"><span class="pre">datetime</span></code></a>
|
||
or <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a> instances to microsecond resolution.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">tzinfo</span></span></dt>
|
||
<dd><p>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"><span class="pre">datetime</span></code></a> and <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a> classes to provide a customizable notion of
|
||
time adjustment (for example, to account for time zone and/or daylight saving
|
||
time).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">timezone</span></span></dt>
|
||
<dd><p>A class that implements the <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></code></a> abstract base class as a
|
||
fixed offset from the UTC.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>Objects of these types are immutable.</p>
|
||
<p>Subclass relationships:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nb">object</span>
|
||
<span class="n">timedelta</span>
|
||
<span class="n">tzinfo</span>
|
||
<span class="n">timezone</span>
|
||
<span class="n">time</span>
|
||
<span class="n">date</span>
|
||
<span class="n">datetime</span>
|
||
</pre></div>
|
||
</div>
|
||
<section id="common-properties">
|
||
<h3>Common Properties<a class="headerlink" href="#common-properties" title="Link to this heading">¶</a></h3>
|
||
<p>The <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a>, <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a>, <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a>, and <a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate"><span class="pre">timezone</span></code></a> types
|
||
share these common features:</p>
|
||
<ul class="simple">
|
||
<li><p>Objects of these types are immutable.</p></li>
|
||
<li><p>Objects of these types are <a class="reference internal" href="../glossary.html#term-hashable"><span class="xref std std-term">hashable</span></a>, meaning that they can be used as
|
||
dictionary keys.</p></li>
|
||
<li><p>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"><span class="pre">pickle</span></code></a> module.</p></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>
|
||
<p>Objects of the <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a> type are always naive.</p>
|
||
<p>An object of type <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a> or <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> may be aware or naive.</p>
|
||
<p>A <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> object <code class="docutils literal notranslate"><span class="pre">d</span></code> is aware if both of the following hold:</p>
|
||
<ol class="arabic simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">d.tzinfo</span></code> is not <code class="docutils literal notranslate"><span class="pre">None</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">d.tzinfo.utcoffset(d)</span></code> does not return <code class="docutils literal notranslate"><span class="pre">None</span></code></p></li>
|
||
</ol>
|
||
<p>Otherwise, <code class="docutils literal notranslate"><span class="pre">d</span></code> is naive.</p>
|
||
<p>A <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a> object <code class="docutils literal notranslate"><span class="pre">t</span></code> is aware if both of the following hold:</p>
|
||
<ol class="arabic simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">t.tzinfo</span></code> is not <code class="docutils literal notranslate"><span class="pre">None</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">t.tzinfo.utcoffset(None)</span></code> does not return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>
|
||
</ol>
|
||
<p>Otherwise, <code class="docutils literal notranslate"><span class="pre">t</span></code> is naive.</p>
|
||
<p>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"><span class="pre">timedelta</span></code></a>
|
||
objects.</p>
|
||
</section>
|
||
</section>
|
||
<section id="timedelta-objects">
|
||
<span id="datetime-timedelta"></span><h2><a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></code></a> Objects<a class="headerlink" href="#timedelta-objects" title="Link to this heading">¶</a></h2>
|
||
<p>A <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></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"><span class="pre">datetime</span></code></a> or <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a> instances.</p>
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="datetime.timedelta">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">timedelta</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">days</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">seconds</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">microseconds</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">milliseconds</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">minutes</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">hours</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">weeks</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.timedelta" title="Link to this definition">¶</a></dt>
|
||
<dd><p>All arguments are optional and default to 0. Arguments may be integers
|
||
or floats, and may be positive or negative.</p>
|
||
<p>Only <em>days</em>, <em>seconds</em> and <em>microseconds</em> are stored internally.
|
||
Arguments are converted to those units:</p>
|
||
<ul class="simple">
|
||
<li><p>A millisecond is converted to 1000 microseconds.</p></li>
|
||
<li><p>A minute is converted to 60 seconds.</p></li>
|
||
<li><p>An hour is converted to 3600 seconds.</p></li>
|
||
<li><p>A week is converted to 7 days.</p></li>
|
||
</ul>
|
||
<p>and days, seconds and microseconds are then normalized so that the
|
||
representation is unique, with</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre"><=</span> <span class="pre">microseconds</span> <span class="pre"><</span> <span class="pre">1000000</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre"><=</span> <span class="pre">seconds</span> <span class="pre"><</span> <span class="pre">3600*24</span></code> (the number of seconds in one day)</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">-999999999</span> <span class="pre"><=</span> <span class="pre">days</span> <span class="pre"><=</span> <span class="pre">999999999</span></code></p></li>
|
||
</ul>
|
||
<p>The following example illustrates how any arguments besides
|
||
<em>days</em>, <em>seconds</em> and <em>microseconds</em> are “merged” and normalized into those
|
||
three resulting attributes:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">timedelta</span>
|
||
<span class="gp">>>> </span><span class="n">delta</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span>
|
||
<span class="gp">... </span> <span class="n">days</span><span class="o">=</span><span class="mi">50</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="n">seconds</span><span class="o">=</span><span class="mi">27</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="n">microseconds</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="n">milliseconds</span><span class="o">=</span><span class="mi">29000</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="n">minutes</span><span class="o">=</span><span class="mi">5</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="n">hours</span><span class="o">=</span><span class="mi">8</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="n">weeks</span><span class="o">=</span><span class="mi">2</span>
|
||
<span class="gp">... </span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="c1"># Only days, seconds, and microseconds remain</span>
|
||
<span class="gp">>>> </span><span class="n">delta</span>
|
||
<span class="go">datetime.timedelta(days=64, seconds=29156, microseconds=10)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>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).</p>
|
||
<p>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"><span class="pre">OverflowError</span></code></a> is raised.</p>
|
||
<p>Note that normalization of negative values may be surprising at first. For
|
||
example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">timedelta</span>
|
||
<span class="gp">>>> </span><span class="n">d</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">microseconds</span><span class="o">=-</span><span class="mi">1</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="p">(</span><span class="n">d</span><span class="o">.</span><span class="n">days</span><span class="p">,</span> <span class="n">d</span><span class="o">.</span><span class="n">seconds</span><span class="p">,</span> <span class="n">d</span><span class="o">.</span><span class="n">microseconds</span><span class="p">)</span>
|
||
<span class="go">(-1, 86399, 999999)</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>Class attributes:</p>
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.timedelta.min">
|
||
<span class="sig-prename descclassname"><span class="pre">timedelta.</span></span><span class="sig-name descname"><span class="pre">min</span></span><a class="headerlink" href="#datetime.timedelta.min" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The most negative <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></code></a> object, <code class="docutils literal notranslate"><span class="pre">timedelta(-999999999)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.timedelta.max">
|
||
<span class="sig-prename descclassname"><span class="pre">timedelta.</span></span><span class="sig-name descname"><span class="pre">max</span></span><a class="headerlink" href="#datetime.timedelta.max" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The most positive <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></code></a> object, <code class="docutils literal notranslate"><span class="pre">timedelta(days=999999999,</span>
|
||
<span class="pre">hours=23,</span> <span class="pre">minutes=59,</span> <span class="pre">seconds=59,</span> <span class="pre">microseconds=999999)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.timedelta.resolution">
|
||
<span class="sig-prename descclassname"><span class="pre">timedelta.</span></span><span class="sig-name descname"><span class="pre">resolution</span></span><a class="headerlink" href="#datetime.timedelta.resolution" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">timedelta</span></code></a> objects,
|
||
<code class="docutils literal notranslate"><span class="pre">timedelta(microseconds=1)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<p>Note that, because of normalization, <code class="docutils literal notranslate"><span class="pre">timedelta.max</span></code> is greater than <code class="docutils literal notranslate"><span class="pre">-timedelta.min</span></code>.
|
||
<code class="docutils literal notranslate"><span class="pre">-timedelta.max</span></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"><span class="pre">timedelta</span></code></a> object.</p>
|
||
<p>Instance attributes (read-only):</p>
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.timedelta.days">
|
||
<span class="sig-prename descclassname"><span class="pre">timedelta.</span></span><span class="sig-name descname"><span class="pre">days</span></span><a class="headerlink" href="#datetime.timedelta.days" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Between -999,999,999 and 999,999,999 inclusive.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.timedelta.seconds">
|
||
<span class="sig-prename descclassname"><span class="pre">timedelta.</span></span><span class="sig-name descname"><span class="pre">seconds</span></span><a class="headerlink" href="#datetime.timedelta.seconds" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Between 0 and 86,399 inclusive.</p>
|
||
<div class="admonition caution">
|
||
<p class="admonition-title">Caution</p>
|
||
<p>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"><span class="pre">total_seconds()</span></code></a>
|
||
value instead:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">timedelta</span>
|
||
<span class="gp">>>> </span><span class="n">duration</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">seconds</span><span class="o">=</span><span class="mi">11235813</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">duration</span><span class="o">.</span><span class="n">days</span><span class="p">,</span> <span class="n">duration</span><span class="o">.</span><span class="n">seconds</span>
|
||
<span class="go">(130, 3813)</span>
|
||
<span class="gp">>>> </span><span class="n">duration</span><span class="o">.</span><span class="n">total_seconds</span><span class="p">()</span>
|
||
<span class="go">11235813.0</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.timedelta.microseconds">
|
||
<span class="sig-prename descclassname"><span class="pre">timedelta.</span></span><span class="sig-name descname"><span class="pre">microseconds</span></span><a class="headerlink" href="#datetime.timedelta.microseconds" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Between 0 and 999,999 inclusive.</p>
|
||
</dd></dl>
|
||
|
||
<p>Supported operations:</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Operation</p></th>
|
||
<th class="head"><p>Result</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">t1</span> <span class="pre">=</span> <span class="pre">t2</span> <span class="pre">+</span> <span class="pre">t3</span></code></p></td>
|
||
<td><p>Sum of <code class="docutils literal notranslate"><span class="pre">t2</span></code> and <code class="docutils literal notranslate"><span class="pre">t3</span></code>.
|
||
Afterwards <code class="docutils literal notranslate"><span class="pre">t1</span> <span class="pre">-</span> <span class="pre">t2</span> <span class="pre">==</span> <span class="pre">t3</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">t1</span> <span class="pre">-</span> <span class="pre">t3</span> <span class="pre">==</span> <span class="pre">t2</span></code> are true. (1)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">t1</span> <span class="pre">=</span> <span class="pre">t2</span> <span class="pre">-</span> <span class="pre">t3</span></code></p></td>
|
||
<td><p>Difference of <code class="docutils literal notranslate"><span class="pre">t2</span></code> and <code class="docutils literal notranslate"><span class="pre">t3</span></code>. Afterwards
|
||
<code class="docutils literal notranslate"><span class="pre">t1</span> <span class="pre">==</span> <span class="pre">t2</span> <span class="pre">-</span> <span class="pre">t3</span></code> and <code class="docutils literal notranslate"><span class="pre">t2</span> <span class="pre">==</span> <span class="pre">t1</span> <span class="pre">+</span> <span class="pre">t3</span></code> are
|
||
true. (1)(6)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">t1</span> <span class="pre">=</span> <span class="pre">t2</span> <span class="pre">*</span> <span class="pre">i</span> <span class="pre">or</span> <span class="pre">t1</span> <span class="pre">=</span> <span class="pre">i</span> <span class="pre">*</span> <span class="pre">t2</span></code></p></td>
|
||
<td><p>Delta multiplied by an integer.
|
||
Afterwards <code class="docutils literal notranslate"><span class="pre">t1</span> <span class="pre">//</span> <span class="pre">i</span> <span class="pre">==</span> <span class="pre">t2</span></code> is true,
|
||
provided <code class="docutils literal notranslate"><span class="pre">i</span> <span class="pre">!=</span> <span class="pre">0</span></code>.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td></td>
|
||
<td><p>In general, <code class="docutils literal notranslate"><span class="pre">t1</span>  <span class="pre">*</span> <span class="pre">i</span> <span class="pre">==</span> <span class="pre">t1</span> <span class="pre">*</span> <span class="pre">(i-1)</span> <span class="pre">+</span> <span class="pre">t1</span></code>
|
||
is true. (1)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">t1</span> <span class="pre">=</span> <span class="pre">t2</span> <span class="pre">*</span> <span class="pre">f</span> <span class="pre">or</span> <span class="pre">t1</span> <span class="pre">=</span> <span class="pre">f</span> <span class="pre">*</span> <span class="pre">t2</span></code></p></td>
|
||
<td><p>Delta multiplied by a float. The result is
|
||
rounded to the nearest multiple of
|
||
timedelta.resolution using round-half-to-even.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">f</span> <span class="pre">=</span> <span class="pre">t2</span> <span class="pre">/</span> <span class="pre">t3</span></code></p></td>
|
||
<td><p>Division (3) of overall duration <code class="docutils literal notranslate"><span class="pre">t2</span></code> by
|
||
interval unit <code class="docutils literal notranslate"><span class="pre">t3</span></code>. Returns a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>
|
||
object.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">t1</span> <span class="pre">=</span> <span class="pre">t2</span> <span class="pre">/</span> <span class="pre">f</span> <span class="pre">or</span> <span class="pre">t1</span> <span class="pre">=</span> <span class="pre">t2</span> <span class="pre">/</span> <span class="pre">i</span></code></p></td>
|
||
<td><p>Delta divided by a float or an int. The result
|
||
is rounded to the nearest multiple of
|
||
timedelta.resolution using round-half-to-even.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">t1</span> <span class="pre">=</span> <span class="pre">t2</span> <span class="pre">//</span> <span class="pre">i</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">t1</span> <span class="pre">=</span> <span class="pre">t2</span> <span class="pre">//</span> <span class="pre">t3</span></code></p></td>
|
||
<td><p>The floor is computed and the remainder (if
|
||
any) is thrown away. In the second case, an
|
||
integer is returned. (3)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">t1</span> <span class="pre">=</span> <span class="pre">t2</span> <span class="pre">%</span> <span class="pre">t3</span></code></p></td>
|
||
<td><p>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"><span class="pre">timedelta</span></code></a> object. (3)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">q,</span> <span class="pre">r</span> <span class="pre">=</span> <span class="pre">divmod(t1,</span> <span class="pre">t2)</span></code></p></td>
|
||
<td><p>Computes the quotient and the remainder:
|
||
<code class="docutils literal notranslate"><span class="pre">q</span> <span class="pre">=</span> <span class="pre">t1</span> <span class="pre">//</span> <span class="pre">t2</span></code> (3) and <code class="docutils literal notranslate"><span class="pre">r</span> <span class="pre">=</span> <span class="pre">t1</span> <span class="pre">%</span> <span class="pre">t2</span></code>.
|
||
<code class="docutils literal notranslate"><span class="pre">q</span></code> is an integer and <code class="docutils literal notranslate"><span class="pre">r</span></code> is a
|
||
<a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></code></a> object.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">+t1</span></code></p></td>
|
||
<td><p>Returns a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></code></a> object with the
|
||
same value. (2)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-t1</span></code></p></td>
|
||
<td><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">timedelta(-t1.days,</span>
|
||
<span class="pre">-t1.seconds,</span> <span class="pre">-t1.microseconds)</span></code>,
|
||
and to <code class="docutils literal notranslate"><span class="pre">t1</span> <span class="pre">*</span> <span class="pre">-1</span></code>. (1)(4)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">abs(t)</span></code></p></td>
|
||
<td><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">+t</span></code> when <code class="docutils literal notranslate"><span class="pre">t.days</span> <span class="pre">>=</span> <span class="pre">0</span></code>,
|
||
and to <code class="docutils literal notranslate"><span class="pre">-t</span></code> when <code class="docutils literal notranslate"><span class="pre">t.days</span> <span class="pre"><</span> <span class="pre">0</span></code>. (2)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">str(t)</span></code></p></td>
|
||
<td><p>Returns a string in the form
|
||
<code class="docutils literal notranslate"><span class="pre">[D</span> <span class="pre">day[s],</span> <span class="pre">][H]H:MM:SS[.UUUUUU]</span></code>, where D
|
||
is negative for negative <code class="docutils literal notranslate"><span class="pre">t</span></code>. (5)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">repr(t)</span></code></p></td>
|
||
<td><p>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"><span class="pre">timedelta</span></code></a> object as a constructor
|
||
call with canonical attribute values.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Notes:</p>
|
||
<ol class="arabic">
|
||
<li><p>This is exact but may overflow.</p></li>
|
||
<li><p>This is exact and cannot overflow.</p></li>
|
||
<li><p>Division by zero raises <a class="reference internal" href="exceptions.html#ZeroDivisionError" title="ZeroDivisionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ZeroDivisionError</span></code></a>.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">-timedelta.max</span></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"><span class="pre">timedelta</span></code></a> object.</p></li>
|
||
<li><p>String representations of <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></code></a> objects are normalized
|
||
similarly to their internal representation. This leads to somewhat
|
||
unusual results for negative timedeltas. For example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=-</span><span class="mi">5</span><span class="p">)</span>
|
||
<span class="go">datetime.timedelta(days=-1, seconds=68400)</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">_</span><span class="p">)</span>
|
||
<span class="go">-1 day, 19:00:00</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>The expression <code class="docutils literal notranslate"><span class="pre">t2</span> <span class="pre">-</span> <span class="pre">t3</span></code> will always be equal to the expression <code class="docutils literal notranslate"><span class="pre">t2</span> <span class="pre">+</span> <span class="pre">(-t3)</span></code> except
|
||
when t3 is equal to <code class="docutils literal notranslate"><span class="pre">timedelta.max</span></code>; in that case the former will produce a result
|
||
while the latter will overflow.</p></li>
|
||
</ol>
|
||
<p>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"><span class="pre">timedelta</span></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"><span class="pre">date</span></code></a> and <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a>
|
||
objects (see below).</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>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"><span class="pre">timedelta</span></code></a> object by another
|
||
<a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></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"><span class="pre">divmod()</span></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"><span class="pre">timedelta</span></code></a> object by a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a> object are now supported.</p>
|
||
</div>
|
||
<p><a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></code></a> objects support equality and order comparisons.</p>
|
||
<p>In Boolean contexts, a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></code></a> object is
|
||
considered to be true if and only if it isn’t equal to <code class="docutils literal notranslate"><span class="pre">timedelta(0)</span></code>.</p>
|
||
<p>Instance methods:</p>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.timedelta.total_seconds">
|
||
<span class="sig-prename descclassname"><span class="pre">timedelta.</span></span><span class="sig-name descname"><span class="pre">total_seconds</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.timedelta.total_seconds" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return the total number of seconds contained in the duration. Equivalent to
|
||
<code class="docutils literal notranslate"><span class="pre">td</span> <span class="pre">/</span> <span class="pre">timedelta(seconds=1)</span></code>. For interval units other than seconds, use the
|
||
division form directly (e.g. <code class="docutils literal notranslate"><span class="pre">td</span> <span class="pre">/</span> <span class="pre">timedelta(microseconds=1)</span></code>).</p>
|
||
<p>Note that for very large time intervals (greater than 270 years on
|
||
most platforms) this method will lose microsecond accuracy.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.2.</span></p>
|
||
</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"><span class="pre">timedelta</span></code></a><a class="headerlink" href="#examples-of-usage-timedelta" title="Link to this heading">¶</a></h3>
|
||
<p>An additional example of normalization:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="c1"># Components of another_year add up to exactly 365 days</span>
|
||
<span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">timedelta</span>
|
||
<span class="gp">>>> </span><span class="n">year</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">days</span><span class="o">=</span><span class="mi">365</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">another_year</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">weeks</span><span class="o">=</span><span class="mi">40</span><span class="p">,</span> <span class="n">days</span><span class="o">=</span><span class="mi">84</span><span class="p">,</span> <span class="n">hours</span><span class="o">=</span><span class="mi">23</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="n">minutes</span><span class="o">=</span><span class="mi">50</span><span class="p">,</span> <span class="n">seconds</span><span class="o">=</span><span class="mi">600</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">year</span> <span class="o">==</span> <span class="n">another_year</span>
|
||
<span class="go">True</span>
|
||
<span class="gp">>>> </span><span class="n">year</span><span class="o">.</span><span class="n">total_seconds</span><span class="p">()</span>
|
||
<span class="go">31536000.0</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Examples of <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></code></a> arithmetic:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">timedelta</span>
|
||
<span class="gp">>>> </span><span class="n">year</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">days</span><span class="o">=</span><span class="mi">365</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">ten_years</span> <span class="o">=</span> <span class="mi">10</span> <span class="o">*</span> <span class="n">year</span>
|
||
<span class="gp">>>> </span><span class="n">ten_years</span>
|
||
<span class="go">datetime.timedelta(days=3650)</span>
|
||
<span class="gp">>>> </span><span class="n">ten_years</span><span class="o">.</span><span class="n">days</span> <span class="o">//</span> <span class="mi">365</span>
|
||
<span class="go">10</span>
|
||
<span class="gp">>>> </span><span class="n">nine_years</span> <span class="o">=</span> <span class="n">ten_years</span> <span class="o">-</span> <span class="n">year</span>
|
||
<span class="gp">>>> </span><span class="n">nine_years</span>
|
||
<span class="go">datetime.timedelta(days=3285)</span>
|
||
<span class="gp">>>> </span><span class="n">three_years</span> <span class="o">=</span> <span class="n">nine_years</span> <span class="o">//</span> <span class="mi">3</span>
|
||
<span class="gp">>>> </span><span class="n">three_years</span><span class="p">,</span> <span class="n">three_years</span><span class="o">.</span><span class="n">days</span> <span class="o">//</span> <span class="mi">365</span>
|
||
<span class="go">(datetime.timedelta(days=1095), 3)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="date-objects">
|
||
<span id="datetime-date"></span><h2><a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a> Objects<a class="headerlink" href="#date-objects" title="Link to this heading">¶</a></h2>
|
||
<p>A <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a> object represents a date (year, month and day) in an idealized
|
||
calendar, the current Gregorian calendar indefinitely extended in both
|
||
directions.</p>
|
||
<p>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"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a></p>
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="datetime.date">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">date</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">year</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">month</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">day</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date" title="Link to this definition">¶</a></dt>
|
||
<dd><p>All arguments are required. Arguments must be integers, in the following
|
||
ranges:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">MINYEAR</span> <span class="pre"><=</span> <span class="pre">year</span> <span class="pre"><=</span> <span class="pre">MAXYEAR</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">1</span> <span class="pre"><=</span> <span class="pre">month</span> <span class="pre"><=</span> <span class="pre">12</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">1</span> <span class="pre"><=</span> <span class="pre">day</span> <span class="pre"><=</span> <span class="pre">number</span> <span class="pre">of</span> <span class="pre">days</span> <span class="pre">in</span> <span class="pre">the</span> <span class="pre">given</span> <span class="pre">month</span> <span class="pre">and</span> <span class="pre">year</span></code></p></li>
|
||
</ul>
|
||
<p>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"><span class="pre">ValueError</span></code></a> is raised.</p>
|
||
</dd></dl>
|
||
|
||
<p>Other constructors, all class methods:</p>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.today">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">today</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.today" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return the current local date.</p>
|
||
<p>This is equivalent to <code class="docutils literal notranslate"><span class="pre">date.fromtimestamp(time.time())</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.fromtimestamp">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">fromtimestamp</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">timestamp</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.fromtimestamp" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">time.time()</span></code></a>.</p>
|
||
<p>This may raise <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></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"><span class="pre">localtime()</span></code>
|
||
function, and <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> on <code class="xref c c-func docutils literal notranslate"><span class="pre">localtime()</span></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"><span class="pre">fromtimestamp()</span></code></a>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>Raise <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> instead of <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></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"><span class="pre">localtime()</span></code> function. Raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> instead of
|
||
<a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> on <code class="xref c c-func docutils literal notranslate"><span class="pre">localtime()</span></code> failure.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.fromordinal">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">fromordinal</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">ordinal</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.fromordinal" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return the date corresponding to the proleptic Gregorian ordinal, where
|
||
January 1 of year 1 has ordinal 1.</p>
|
||
<p><a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised unless <code class="docutils literal notranslate"><span class="pre">1</span> <span class="pre"><=</span> <span class="pre">ordinal</span> <span class="pre"><=</span>
|
||
<span class="pre">date.max.toordinal()</span></code>. For any date <code class="docutils literal notranslate"><span class="pre">d</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">date.fromordinal(d.toordinal())</span> <span class="pre">==</span> <span class="pre">d</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.fromisoformat">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">fromisoformat</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">date_string</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.fromisoformat" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a> corresponding to a <em>date_string</em> given in any valid
|
||
ISO 8601 format, with the following exceptions:</p>
|
||
<ol class="arabic simple">
|
||
<li><p>Reduced precision dates are not currently supported (<code class="docutils literal notranslate"><span class="pre">YYYY-MM</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">YYYY</span></code>).</p></li>
|
||
<li><p>Extended date representations are not currently supported
|
||
(<code class="docutils literal notranslate"><span class="pre">±YYYYYY-MM-DD</span></code>).</p></li>
|
||
<li><p>Ordinal dates are not currently supported (<code class="docutils literal notranslate"><span class="pre">YYYY-OOO</span></code>).</p></li>
|
||
</ol>
|
||
<p>Examples:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">date</span>
|
||
<span class="gp">>>> </span><span class="n">date</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'2019-12-04'</span><span class="p">)</span>
|
||
<span class="go">datetime.date(2019, 12, 4)</span>
|
||
<span class="gp">>>> </span><span class="n">date</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'20191204'</span><span class="p">)</span>
|
||
<span class="go">datetime.date(2019, 12, 4)</span>
|
||
<span class="gp">>>> </span><span class="n">date</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'2021-W01-1'</span><span class="p">)</span>
|
||
<span class="go">datetime.date(2021, 1, 4)</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.7.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span>Previously, this method only supported the format <code class="docutils literal notranslate"><span class="pre">YYYY-MM-DD</span></code>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.fromisocalendar">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">fromisocalendar</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">year</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">week</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">day</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.fromisocalendar" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></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"><span class="pre">date.isocalendar()</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.8.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>Class attributes:</p>
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.date.min">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">min</span></span><a class="headerlink" href="#datetime.date.min" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The earliest representable date, <code class="docutils literal notranslate"><span class="pre">date(MINYEAR,</span> <span class="pre">1,</span> <span class="pre">1)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.date.max">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">max</span></span><a class="headerlink" href="#datetime.date.max" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The latest representable date, <code class="docutils literal notranslate"><span class="pre">date(MAXYEAR,</span> <span class="pre">12,</span> <span class="pre">31)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.date.resolution">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">resolution</span></span><a class="headerlink" href="#datetime.date.resolution" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The smallest possible difference between non-equal date objects,
|
||
<code class="docutils literal notranslate"><span class="pre">timedelta(days=1)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<p>Instance attributes (read-only):</p>
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.date.year">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">year</span></span><a class="headerlink" href="#datetime.date.year" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Between <a class="reference internal" href="#datetime.MINYEAR" title="datetime.MINYEAR"><code class="xref py py-const docutils literal notranslate"><span class="pre">MINYEAR</span></code></a> and <a class="reference internal" href="#datetime.MAXYEAR" title="datetime.MAXYEAR"><code class="xref py py-const docutils literal notranslate"><span class="pre">MAXYEAR</span></code></a> inclusive.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.date.month">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">month</span></span><a class="headerlink" href="#datetime.date.month" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Between 1 and 12 inclusive.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.date.day">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">day</span></span><a class="headerlink" href="#datetime.date.day" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Between 1 and the number of days in the given month of the given year.</p>
|
||
</dd></dl>
|
||
|
||
<p>Supported operations:</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Operation</p></th>
|
||
<th class="head"><p>Result</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">date2</span> <span class="pre">=</span> <span class="pre">date1</span> <span class="pre">+</span> <span class="pre">timedelta</span></code></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">date2</span></code> will be <code class="docutils literal notranslate"><span class="pre">timedelta.days</span></code> days
|
||
after <code class="docutils literal notranslate"><span class="pre">date1</span></code>. (1)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">date2</span> <span class="pre">=</span> <span class="pre">date1</span> <span class="pre">-</span> <span class="pre">timedelta</span></code></p></td>
|
||
<td><p>Computes <code class="docutils literal notranslate"><span class="pre">date2</span></code> such that <code class="docutils literal notranslate"><span class="pre">date2</span> <span class="pre">+</span>
|
||
<span class="pre">timedelta</span> <span class="pre">==</span> <span class="pre">date1</span></code>. (2)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">timedelta</span> <span class="pre">=</span> <span class="pre">date1</span> <span class="pre">-</span> <span class="pre">date2</span></code></p></td>
|
||
<td><p>(3)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><div class="line-block">
|
||
<div class="line"><code class="docutils literal notranslate"><span class="pre">date1</span> <span class="pre">==</span> <span class="pre">date2</span></code></div>
|
||
<div class="line"><code class="docutils literal notranslate"><span class="pre">date1</span> <span class="pre">!=</span> <span class="pre">date2</span></code></div>
|
||
</div>
|
||
</td>
|
||
<td><p>Equality comparison. (4)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><div class="line-block">
|
||
<div class="line"><code class="docutils literal notranslate"><span class="pre">date1</span> <span class="pre"><</span> <span class="pre">date2</span></code></div>
|
||
<div class="line"><code class="docutils literal notranslate"><span class="pre">date1</span> <span class="pre">></span> <span class="pre">date2</span></code></div>
|
||
<div class="line"><code class="docutils literal notranslate"><span class="pre">date1</span> <span class="pre"><=</span> <span class="pre">date2</span></code></div>
|
||
<div class="line"><code class="docutils literal notranslate"><span class="pre">date1</span> <span class="pre">>=</span> <span class="pre">date2</span></code></div>
|
||
</div>
|
||
</td>
|
||
<td><p>Order comparison. (5)</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Notes:</p>
|
||
<ol class="arabic">
|
||
<li><p><em>date2</em> is moved forward in time if <code class="docutils literal notranslate"><span class="pre">timedelta.days</span> <span class="pre">></span> <span class="pre">0</span></code>, or backward if
|
||
<code class="docutils literal notranslate"><span class="pre">timedelta.days</span> <span class="pre"><</span> <span class="pre">0</span></code>. Afterward <code class="docutils literal notranslate"><span class="pre">date2</span> <span class="pre">-</span> <span class="pre">date1</span> <span class="pre">==</span> <span class="pre">timedelta.days</span></code>.
|
||
<code class="docutils literal notranslate"><span class="pre">timedelta.seconds</span></code> and <code class="docutils literal notranslate"><span class="pre">timedelta.microseconds</span></code> are ignored.
|
||
<a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> is raised if <code class="docutils literal notranslate"><span class="pre">date2.year</span></code> would be smaller than
|
||
<a class="reference internal" href="#datetime.MINYEAR" title="datetime.MINYEAR"><code class="xref py py-const docutils literal notranslate"><span class="pre">MINYEAR</span></code></a> or larger than <a class="reference internal" href="#datetime.MAXYEAR" title="datetime.MAXYEAR"><code class="xref py py-const docutils literal notranslate"><span class="pre">MAXYEAR</span></code></a>.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">timedelta.seconds</span></code> and <code class="docutils literal notranslate"><span class="pre">timedelta.microseconds</span></code> are ignored.</p></li>
|
||
<li><p>This is exact, and cannot overflow. <code class="docutils literal notranslate"><span class="pre">timedelta.seconds</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">timedelta.microseconds</span></code> are 0, and <code class="docutils literal notranslate"><span class="pre">date2</span> <span class="pre">+</span> <span class="pre">timedelta</span> <span class="pre">==</span> <span class="pre">date1</span></code> after.</p></li>
|
||
<li><p><a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a> objects are equal if they represent the same date.</p>
|
||
<p><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></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"><span class="pre">datetime</span></code></a> instances
|
||
are never equal to <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code> objects, even if they represent
|
||
the same date.</p>
|
||
</li>
|
||
<li><p><em>date1</em> is considered less than <em>date2</em> when <em>date1</em> precedes <em>date2</em> in time.
|
||
In other words, <code class="docutils literal notranslate"><span class="pre">date1</span> <span class="pre"><</span> <span class="pre">date2</span></code> if and only if <code class="docutils literal notranslate"><span class="pre">date1.toordinal()</span> <span class="pre"><</span>
|
||
<span class="pre">date2.toordinal()</span></code>.</p>
|
||
<p>Order comparison between a <code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></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"><span class="pre">datetime</span></code></a> instance and a <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code> object raises
|
||
<a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>
|
||
</li>
|
||
</ol>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.13: </span>Comparison between <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">date</span></code></a> subclass that is not a <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code> subclass
|
||
no longer converts the latter to <code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code>, ignoring the time part
|
||
and the time zone.
|
||
The default behavior can be changed by overriding the special comparison
|
||
methods in subclasses.</p>
|
||
</div>
|
||
<p>In Boolean contexts, all <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a> objects are considered to be true.</p>
|
||
<p>Instance methods:</p>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.replace">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">replace</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">year</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.year</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">month</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.month</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">day</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.day</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.replace" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a new <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a> object with the same values, but with specified
|
||
parameters updated.</p>
|
||
<p>Example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">date</span>
|
||
<span class="gp">>>> </span><span class="n">d</span> <span class="o">=</span> <span class="n">date</span><span class="p">(</span><span class="mi">2002</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">31</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">d</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">day</span><span class="o">=</span><span class="mi">26</span><span class="p">)</span>
|
||
<span class="go">datetime.date(2002, 12, 26)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The generic function <a class="reference internal" href="copy.html#copy.replace" title="copy.replace"><code class="xref py py-func docutils literal notranslate"><span class="pre">copy.replace()</span></code></a> also supports <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a>
|
||
objects.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.timetuple">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">timetuple</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.timetuple" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">time.struct_time</span></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"><span class="pre">time.localtime()</span></code></a>.</p>
|
||
<p>The hours, minutes and seconds are 0, and the DST flag is -1.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">d.timetuple()</span></code> is equivalent to:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">time</span><span class="o">.</span><span class="n">struct_time</span><span class="p">((</span><span class="n">d</span><span class="o">.</span><span class="n">year</span><span class="p">,</span> <span class="n">d</span><span class="o">.</span><span class="n">month</span><span class="p">,</span> <span class="n">d</span><span class="o">.</span><span class="n">day</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">d</span><span class="o">.</span><span class="n">weekday</span><span class="p">(),</span> <span class="n">yday</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>where <code class="docutils literal notranslate"><span class="pre">yday</span> <span class="pre">=</span> <span class="pre">d.toordinal()</span> <span class="pre">-</span> <span class="pre">date(d.year,</span> <span class="pre">1,</span> <span class="pre">1).toordinal()</span> <span class="pre">+</span> <span class="pre">1</span></code>
|
||
is the day number within the current year starting with 1 for January 1st.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.toordinal">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">toordinal</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.toordinal" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">date</span></code></a> object <code class="docutils literal notranslate"><span class="pre">d</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">date.fromordinal(d.toordinal())</span> <span class="pre">==</span> <span class="pre">d</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.weekday">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">weekday</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.weekday" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return the day of the week as an integer, where Monday is 0 and Sunday is 6.
|
||
For example, <code class="docutils literal notranslate"><span class="pre">date(2002,</span> <span class="pre">12,</span> <span class="pre">4).weekday()</span> <span class="pre">==</span> <span class="pre">2</span></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"><span class="pre">isoweekday()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.isoweekday">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">isoweekday</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.isoweekday" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
|
||
For example, <code class="docutils literal notranslate"><span class="pre">date(2002,</span> <span class="pre">12,</span> <span class="pre">4).isoweekday()</span> <span class="pre">==</span> <span class="pre">3</span></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"><span class="pre">weekday()</span></code></a>, <a class="reference internal" href="#datetime.date.isocalendar" title="datetime.date.isocalendar"><code class="xref py py-meth docutils literal notranslate"><span class="pre">isocalendar()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.isocalendar">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">isocalendar</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.isocalendar" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a> object with three components: <code class="docutils literal notranslate"><span class="pre">year</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">week</span></code> and <code class="docutils literal notranslate"><span class="pre">weekday</span></code>.</p>
|
||
<p>The ISO calendar is a widely used variant of the Gregorian calendar. <a class="footnote-reference brackets" href="#id7" id="id3" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a></p>
|
||
<p>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.</p>
|
||
<p>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:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">date</span>
|
||
<span class="gp">>>> </span><span class="n">date</span><span class="p">(</span><span class="mi">2003</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">29</span><span class="p">)</span><span class="o">.</span><span class="n">isocalendar</span><span class="p">()</span>
|
||
<span class="go">datetime.IsoCalendarDate(year=2004, week=1, weekday=1)</span>
|
||
<span class="gp">>>> </span><span class="n">date</span><span class="p">(</span><span class="mi">2004</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">4</span><span class="p">)</span><span class="o">.</span><span class="n">isocalendar</span><span class="p">()</span>
|
||
<span class="go">datetime.IsoCalendarDate(year=2004, week=1, weekday=7)</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.9: </span>Result changed from a tuple to a <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.isoformat">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">isoformat</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.isoformat" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a string representing the date in ISO 8601 format, <code class="docutils literal notranslate"><span class="pre">YYYY-MM-DD</span></code>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">date</span>
|
||
<span class="gp">>>> </span><span class="n">date</span><span class="p">(</span><span class="mi">2002</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">4</span><span class="p">)</span><span class="o">.</span><span class="n">isoformat</span><span class="p">()</span>
|
||
<span class="go">'2002-12-04'</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.__str__">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">__str__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.__str__" title="Link to this definition">¶</a></dt>
|
||
<dd><p>For a date <code class="docutils literal notranslate"><span class="pre">d</span></code>, <code class="docutils literal notranslate"><span class="pre">str(d)</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">d.isoformat()</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.ctime">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">ctime</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.ctime" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a string representing the date:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">date</span>
|
||
<span class="gp">>>> </span><span class="n">date</span><span class="p">(</span><span class="mi">2002</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">4</span><span class="p">)</span><span class="o">.</span><span class="n">ctime</span><span class="p">()</span>
|
||
<span class="go">'Wed Dec 4 00:00:00 2002'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><code class="docutils literal notranslate"><span class="pre">d.ctime()</span></code> is equivalent to:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">time</span><span class="o">.</span><span class="n">ctime</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">mktime</span><span class="p">(</span><span class="n">d</span><span class="o">.</span><span class="n">timetuple</span><span class="p">()))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>on platforms where the native C
|
||
<code class="xref c c-func docutils literal notranslate"><span class="pre">ctime()</span></code> function (which <a class="reference internal" href="time.html#time.ctime" title="time.ctime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.ctime()</span></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"><span class="pre">date.ctime()</span></code></a> does not invoke) conforms to the C standard.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.strftime">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">strftime</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">format</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.strftime" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="std std-ref">strftime() and strptime() Behavior</span></a> and <a class="reference internal" href="#datetime.date.isoformat" title="datetime.date.isoformat"><code class="xref py py-meth docutils literal notranslate"><span class="pre">date.isoformat()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.date.__format__">
|
||
<span class="sig-prename descclassname"><span class="pre">date.</span></span><span class="sig-name descname"><span class="pre">__format__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">format</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.date.__format__" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Same as <a class="reference internal" href="#datetime.date.strftime" title="datetime.date.strftime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">date.strftime()</span></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"><span class="pre">date</span></code></a> object in <a class="reference internal" href="../reference/lexical_analysis.html#f-strings"><span class="std std-ref">formatted string
|
||
literals</span></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"><span class="pre">str.format()</span></code></a>.
|
||
See also <a class="reference internal" href="#strftime-strptime-behavior"><span class="std std-ref">strftime() and strptime() Behavior</span></a> and <a class="reference internal" href="#datetime.date.isoformat" title="datetime.date.isoformat"><code class="xref py py-meth docutils literal notranslate"><span class="pre">date.isoformat()</span></code></a>.</p>
|
||
</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"><span class="pre">date</span></code></a><a class="headerlink" href="#examples-of-usage-date" title="Link to this heading">¶</a></h3>
|
||
<p>Example of counting days to an event:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">time</span>
|
||
<span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">date</span>
|
||
<span class="gp">>>> </span><span class="n">today</span> <span class="o">=</span> <span class="n">date</span><span class="o">.</span><span class="n">today</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">today</span>
|
||
<span class="go">datetime.date(2007, 12, 5)</span>
|
||
<span class="gp">>>> </span><span class="n">today</span> <span class="o">==</span> <span class="n">date</span><span class="o">.</span><span class="n">fromtimestamp</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">())</span>
|
||
<span class="go">True</span>
|
||
<span class="gp">>>> </span><span class="n">my_birthday</span> <span class="o">=</span> <span class="n">date</span><span class="p">(</span><span class="n">today</span><span class="o">.</span><span class="n">year</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">24</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="k">if</span> <span class="n">my_birthday</span> <span class="o"><</span> <span class="n">today</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="n">my_birthday</span> <span class="o">=</span> <span class="n">my_birthday</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">year</span><span class="o">=</span><span class="n">today</span><span class="o">.</span><span class="n">year</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">>>> </span><span class="n">my_birthday</span>
|
||
<span class="go">datetime.date(2008, 6, 24)</span>
|
||
<span class="gp">>>> </span><span class="n">time_to_birthday</span> <span class="o">=</span> <span class="nb">abs</span><span class="p">(</span><span class="n">my_birthday</span> <span class="o">-</span> <span class="n">today</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">time_to_birthday</span><span class="o">.</span><span class="n">days</span>
|
||
<span class="go">202</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>More examples of working with <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a>:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">date</span>
|
||
<span class="gp">>>> </span><span class="n">d</span> <span class="o">=</span> <span class="n">date</span><span class="o">.</span><span class="n">fromordinal</span><span class="p">(</span><span class="mi">730920</span><span class="p">)</span> <span class="c1"># 730920th day after 1. 1. 0001</span>
|
||
<span class="gp">>>> </span><span class="n">d</span>
|
||
<span class="go">datetime.date(2002, 3, 11)</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Methods related to formatting string output</span>
|
||
<span class="gp">>>> </span><span class="n">d</span><span class="o">.</span><span class="n">isoformat</span><span class="p">()</span>
|
||
<span class="go">'2002-03-11'</span>
|
||
<span class="gp">>>> </span><span class="n">d</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s2">"</span><span class="si">%d</span><span class="s2">/%m/%y"</span><span class="p">)</span>
|
||
<span class="go">'11/03/02'</span>
|
||
<span class="gp">>>> </span><span class="n">d</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s2">"%A </span><span class="si">%d</span><span class="s2">. %B %Y"</span><span class="p">)</span>
|
||
<span class="go">'Monday 11. March 2002'</span>
|
||
<span class="gp">>>> </span><span class="n">d</span><span class="o">.</span><span class="n">ctime</span><span class="p">()</span>
|
||
<span class="go">'Mon Mar 11 00:00:00 2002'</span>
|
||
<span class="gp">>>> </span><span class="s1">'The </span><span class="si">{1}</span><span class="s1"> is {0:</span><span class="si">%d</span><span class="s1">}, the </span><span class="si">{2}</span><span class="s1"> is {0:%B}.'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">d</span><span class="p">,</span> <span class="s2">"day"</span><span class="p">,</span> <span class="s2">"month"</span><span class="p">)</span>
|
||
<span class="go">'The day is 11, the month is March.'</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Methods for to extracting 'components' under different calendars</span>
|
||
<span class="gp">>>> </span><span class="n">t</span> <span class="o">=</span> <span class="n">d</span><span class="o">.</span><span class="n">timetuple</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">t</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">i</span><span class="p">)</span>
|
||
<span class="go">2002 # year</span>
|
||
<span class="go">3 # month</span>
|
||
<span class="go">11 # day</span>
|
||
<span class="go">0</span>
|
||
<span class="go">0</span>
|
||
<span class="go">0</span>
|
||
<span class="go">0 # weekday (0 = Monday)</span>
|
||
<span class="go">70 # 70th day in the year</span>
|
||
<span class="go">-1</span>
|
||
<span class="gp">>>> </span><span class="n">ic</span> <span class="o">=</span> <span class="n">d</span><span class="o">.</span><span class="n">isocalendar</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">ic</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">i</span><span class="p">)</span>
|
||
<span class="go">2002 # ISO year</span>
|
||
<span class="go">11 # ISO week number</span>
|
||
<span class="go">1 # ISO day number ( 1 = Monday )</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># A date object is immutable; all operations produce a new object</span>
|
||
<span class="gp">>>> </span><span class="n">d</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">year</span><span class="o">=</span><span class="mi">2005</span><span class="p">)</span>
|
||
<span class="go">datetime.date(2005, 3, 11)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="datetime-objects">
|
||
<span id="datetime-datetime"></span><h2><a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> Objects<a class="headerlink" href="#datetime-objects" title="Link to this heading">¶</a></h2>
|
||
<p>A <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">date</span></code></a> object and a <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a> object.</p>
|
||
<p>Like a <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a> object, <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">time</span></code></a> object,
|
||
<a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> assumes there are exactly 3600*24 seconds in every day.</p>
|
||
<p>Constructor:</p>
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="datetime.datetime">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">datetime</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">year</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">month</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">day</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">hour</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">minute</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">second</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">microsecond</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tzinfo</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">fold</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The <em>year</em>, <em>month</em> and <em>day</em> arguments are required. <em>tzinfo</em> may be <code class="docutils literal notranslate"><span class="pre">None</span></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"><span class="pre">tzinfo</span></code></a> subclass. The remaining arguments must be integers
|
||
in the following ranges:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">MINYEAR</span> <span class="pre"><=</span> <span class="pre">year</span> <span class="pre"><=</span> <span class="pre">MAXYEAR</span></code>,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">1</span> <span class="pre"><=</span> <span class="pre">month</span> <span class="pre"><=</span> <span class="pre">12</span></code>,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">1</span> <span class="pre"><=</span> <span class="pre">day</span> <span class="pre"><=</span> <span class="pre">number</span> <span class="pre">of</span> <span class="pre">days</span> <span class="pre">in</span> <span class="pre">the</span> <span class="pre">given</span> <span class="pre">month</span> <span class="pre">and</span> <span class="pre">year</span></code>,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre"><=</span> <span class="pre">hour</span> <span class="pre"><</span> <span class="pre">24</span></code>,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre"><=</span> <span class="pre">minute</span> <span class="pre"><</span> <span class="pre">60</span></code>,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre"><=</span> <span class="pre">second</span> <span class="pre"><</span> <span class="pre">60</span></code>,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre"><=</span> <span class="pre">microsecond</span> <span class="pre"><</span> <span class="pre">1000000</span></code>,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">fold</span> <span class="pre">in</span> <span class="pre">[0,</span> <span class="pre">1]</span></code>.</p></li>
|
||
</ul>
|
||
<p>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"><span class="pre">ValueError</span></code></a> is raised.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Added the <em>fold</em> parameter.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>Other constructors, all class methods:</p>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.today">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">today</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.today" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">tzinfo</span></code></a> <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
<p>Equivalent to:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">datetime</span><span class="o">.</span><span class="n">fromtimestamp</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">())</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>See also <a class="reference internal" href="#datetime.datetime.now" title="datetime.datetime.now"><code class="xref py py-meth docutils literal notranslate"><span class="pre">now()</span></code></a>, <a class="reference internal" href="#datetime.datetime.fromtimestamp" title="datetime.datetime.fromtimestamp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">fromtimestamp()</span></code></a>.</p>
|
||
<p>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"><span class="pre">now()</span></code></a>, but without a
|
||
<code class="docutils literal notranslate"><span class="pre">tz</span></code> parameter.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.now">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">now</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tz</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.now" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return the current local date and time.</p>
|
||
<p>If optional argument <em>tz</em> is <code class="docutils literal notranslate"><span class="pre">None</span></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"><span class="pre">today()</span></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"><span class="pre">time.time()</span></code></a> timestamp
|
||
(for example, this may be possible on platforms supplying the C
|
||
<code class="xref c c-func docutils literal notranslate"><span class="pre">gettimeofday()</span></code> function).</p>
|
||
<p>If <em>tz</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></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"><span class="pre">tzinfo</span></code></a> subclass,
|
||
and the current date and time are converted to <em>tz</em>’s time zone.</p>
|
||
<p>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"><span class="pre">today()</span></code></a> and <a class="reference internal" href="#datetime.datetime.utcnow" title="datetime.datetime.utcnow"><code class="xref py py-meth docutils literal notranslate"><span class="pre">utcnow()</span></code></a>.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Subsequent calls to <code class="xref py py-meth docutils literal notranslate"><span class="pre">datetime.now()</span></code> may return the same
|
||
instant depending on the precision of the underlying clock.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.utcnow">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">utcnow</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.utcnow" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">tzinfo</span></code></a> <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
<p>This is like <a class="reference internal" href="#datetime.datetime.now" title="datetime.datetime.now"><code class="xref py py-meth docutils literal notranslate"><span class="pre">now()</span></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"><span class="pre">datetime</span></code></a> object. An aware current UTC datetime can be obtained by
|
||
calling <code class="docutils literal notranslate"><span class="pre">datetime.now(timezone.utc)</span></code>. See also <a class="reference internal" href="#datetime.datetime.now" title="datetime.datetime.now"><code class="xref py py-meth docutils literal notranslate"><span class="pre">now()</span></code></a>.</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>Because naive <code class="docutils literal notranslate"><span class="pre">datetime</span></code> objects are treated by many <code class="docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">datetime.now(timezone.utc)</span></code>.</p>
|
||
</div>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.12: </span>Use <a class="reference internal" href="#datetime.datetime.now" title="datetime.datetime.now"><code class="xref py py-meth docutils literal notranslate"><span class="pre">datetime.now()</span></code></a> with <a class="reference internal" href="#datetime.UTC" title="datetime.UTC"><code class="xref py py-const docutils literal notranslate"><span class="pre">UTC</span></code></a> instead.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.fromtimestamp">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">fromtimestamp</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">timestamp</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tz</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.fromtimestamp" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">time.time()</span></code></a>. If optional argument <em>tz</em> is <code class="docutils literal notranslate"><span class="pre">None</span></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"><span class="pre">datetime</span></code></a> object is naive.</p>
|
||
<p>If <em>tz</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></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"><span class="pre">tzinfo</span></code></a> subclass, and the
|
||
timestamp is converted to <em>tz</em>’s time zone.</p>
|
||
<p><a class="reference internal" href="#datetime.datetime.fromtimestamp" title="datetime.datetime.fromtimestamp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">fromtimestamp()</span></code></a> may raise <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></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"><span class="pre">localtime()</span></code> or
|
||
<code class="xref c c-func docutils literal notranslate"><span class="pre">gmtime()</span></code> functions, and <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> on <code class="xref c c-func docutils literal notranslate"><span class="pre">localtime()</span></code> or
|
||
<code class="xref c c-func docutils literal notranslate"><span class="pre">gmtime()</span></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"><span class="pre">fromtimestamp()</span></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"><span class="pre">datetime</span></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"><span class="pre">utcfromtimestamp()</span></code></a>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>Raise <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> instead of <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></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"><span class="pre">localtime()</span></code> or <code class="xref c c-func docutils literal notranslate"><span class="pre">gmtime()</span></code> functions. Raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>
|
||
instead of <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> on <code class="xref c c-func docutils literal notranslate"><span class="pre">localtime()</span></code> or <code class="xref c c-func docutils literal notranslate"><span class="pre">gmtime()</span></code>
|
||
failure.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span><a class="reference internal" href="#datetime.datetime.fromtimestamp" title="datetime.datetime.fromtimestamp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">fromtimestamp()</span></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"><span class="pre">fold</span></code></a> set to 1.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.utcfromtimestamp">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">utcfromtimestamp</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">timestamp</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.utcfromtimestamp" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return the UTC <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">tzinfo</span></code></a> <code class="docutils literal notranslate"><span class="pre">None</span></code>. (The resulting object is naive.)</p>
|
||
<p>This may raise <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></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"><span class="pre">gmtime()</span></code> function,
|
||
and <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> on <code class="xref c c-func docutils literal notranslate"><span class="pre">gmtime()</span></code> failure.
|
||
It’s common for this to be restricted to years in 1970 through 2038.</p>
|
||
<p>To get an aware <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">fromtimestamp()</span></code></a>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">datetime</span><span class="o">.</span><span class="n">fromtimestamp</span><span class="p">(</span><span class="n">timestamp</span><span class="p">,</span> <span class="n">timezone</span><span class="o">.</span><span class="n">utc</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>On the POSIX compliant platforms, it is equivalent to the following
|
||
expression:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">datetime</span><span class="p">(</span><span class="mi">1970</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">timezone</span><span class="o">.</span><span class="n">utc</span><span class="p">)</span> <span class="o">+</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">seconds</span><span class="o">=</span><span class="n">timestamp</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>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"><span class="pre">MINYEAR</span></code></a> and <a class="reference internal" href="#datetime.MAXYEAR" title="datetime.MAXYEAR"><code class="xref py py-const docutils literal notranslate"><span class="pre">MAXYEAR</span></code></a> inclusive.</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>Because naive <code class="docutils literal notranslate"><span class="pre">datetime</span></code> objects are treated by many <code class="docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">datetime.fromtimestamp(timestamp,</span> <span class="pre">tz=timezone.utc)</span></code>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>Raise <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> instead of <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></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"><span class="pre">gmtime()</span></code> function. Raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> instead of
|
||
<a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> on <code class="xref c c-func docutils literal notranslate"><span class="pre">gmtime()</span></code> failure.</p>
|
||
</div>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.12: </span>Use <a class="reference internal" href="#datetime.datetime.fromtimestamp" title="datetime.datetime.fromtimestamp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">datetime.fromtimestamp()</span></code></a> with <a class="reference internal" href="#datetime.UTC" title="datetime.UTC"><code class="xref py py-const docutils literal notranslate"><span class="pre">UTC</span></code></a> instead.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.fromordinal">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">fromordinal</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">ordinal</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.fromordinal" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return the <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">ValueError</span></code></a> is raised unless
|
||
<code class="docutils literal notranslate"><span class="pre">1</span> <span class="pre"><=</span> <span class="pre">ordinal</span> <span class="pre"><=</span> <span class="pre">datetime.max.toordinal()</span></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"><span class="pre">tzinfo</span></code></a> is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.combine">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">combine</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">date</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">time</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tzinfo</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">time.tzinfo</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.combine" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a new <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">date</span></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"><span class="pre">time</span></code></a> object’s. If the <em>tzinfo</em>
|
||
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"><span class="pre">tzinfo</span></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"><span class="pre">tzinfo</span></code></a> attribute of the <em>time</em> argument
|
||
is used. If the <em>date</em> argument is a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">tzinfo</span></code></a> attributes are ignored.</p>
|
||
<p>For any <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> object <code class="docutils literal notranslate"><span class="pre">d</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">d</span> <span class="pre">==</span> <span class="pre">datetime.combine(d.date(),</span> <span class="pre">d.time(),</span> <span class="pre">d.tzinfo)</span></code>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Added the <em>tzinfo</em> argument.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.fromisoformat">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">fromisoformat</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">date_string</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.fromisoformat" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> corresponding to a <em>date_string</em> in any valid
|
||
ISO 8601 format, with the following exceptions:</p>
|
||
<ol class="arabic simple">
|
||
<li><p>Time zone offsets may have fractional seconds.</p></li>
|
||
<li><p>The <code class="docutils literal notranslate"><span class="pre">T</span></code> separator may be replaced by any single unicode character.</p></li>
|
||
<li><p>Fractional hours and minutes are not supported.</p></li>
|
||
<li><p>Reduced precision dates are not currently supported (<code class="docutils literal notranslate"><span class="pre">YYYY-MM</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">YYYY</span></code>).</p></li>
|
||
<li><p>Extended date representations are not currently supported
|
||
(<code class="docutils literal notranslate"><span class="pre">±YYYYYY-MM-DD</span></code>).</p></li>
|
||
<li><p>Ordinal dates are not currently supported (<code class="docutils literal notranslate"><span class="pre">YYYY-OOO</span></code>).</p></li>
|
||
</ol>
|
||
<p>Examples:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'2011-11-04'</span><span class="p">)</span>
|
||
<span class="go">datetime.datetime(2011, 11, 4, 0, 0)</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'20111104'</span><span class="p">)</span>
|
||
<span class="go">datetime.datetime(2011, 11, 4, 0, 0)</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'2011-11-04T00:05:23'</span><span class="p">)</span>
|
||
<span class="go">datetime.datetime(2011, 11, 4, 0, 5, 23)</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'2011-11-04T00:05:23Z'</span><span class="p">)</span>
|
||
<span class="go">datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'20111104T000523'</span><span class="p">)</span>
|
||
<span class="go">datetime.datetime(2011, 11, 4, 0, 5, 23)</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'2011-W01-2T00:05:23.283'</span><span class="p">)</span>
|
||
<span class="go">datetime.datetime(2011, 1, 4, 0, 5, 23, 283000)</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'2011-11-04 00:05:23.283'</span><span class="p">)</span>
|
||
<span class="go">datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'2011-11-04 00:05:23.283+00:00'</span><span class="p">)</span>
|
||
<span class="go">datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc)</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'2011-11-04T00:05:23+04:00'</span><span class="p">)</span>
|
||
<span class="go">datetime.datetime(2011, 11, 4, 0, 5, 23,</span>
|
||
<span class="go"> tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.7.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span>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"><span class="pre">date.isoformat()</span></code></a> or <a class="reference internal" href="#datetime.datetime.isoformat" title="datetime.datetime.isoformat"><code class="xref py py-meth docutils literal notranslate"><span class="pre">datetime.isoformat()</span></code></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.fromisocalendar">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">fromisocalendar</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">year</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">week</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">day</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.fromisocalendar" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">datetime.isocalendar()</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.8.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.strptime">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">strptime</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">date_string</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">format</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.strptime" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> corresponding to <em>date_string</em>, parsed according to
|
||
<em>format</em>.</p>
|
||
<p>If <em>format</em> does not contain microseconds or time zone information, this is equivalent to:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">datetime</span><span class="p">(</span><span class="o">*</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">strptime</span><span class="p">(</span><span class="n">date_string</span><span class="p">,</span> <span class="nb">format</span><span class="p">)[</span><span class="mi">0</span><span class="p">:</span><span class="mi">6</span><span class="p">]))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></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"><span class="pre">time.strptime()</span></code></a> or if it returns a value which isn’t a
|
||
time tuple. See also <a class="reference internal" href="#strftime-strptime-behavior"><span class="std std-ref">strftime() and strptime() Behavior</span></a> and
|
||
<a class="reference internal" href="#datetime.datetime.fromisoformat" title="datetime.datetime.fromisoformat"><code class="xref py py-meth docutils literal notranslate"><span class="pre">datetime.fromisoformat()</span></code></a>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.13: </span>If <em>format</em> 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"><span class="pre">DeprecationWarning</span></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 <em>format</em> values may raise an error as of Python 3.15. The
|
||
workaround is to always include a year in your <em>format</em>. If parsing
|
||
<em>date_string</em> values that do not have a year, explicitly add a year that
|
||
is a leap year before parsing:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span>
|
||
<span class="gp">>>> </span><span class="n">date_string</span> <span class="o">=</span> <span class="s2">"02/29"</span>
|
||
<span class="gp">>>> </span><span class="n">when</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">strptime</span><span class="p">(</span><span class="sa">f</span><span class="s2">"</span><span class="si">{</span><span class="n">date_string</span><span class="si">}</span><span class="s2">;1984"</span><span class="p">,</span> <span class="s2">"%m/</span><span class="si">%d</span><span class="s2">;%Y"</span><span class="p">)</span> <span class="c1"># Avoids leap year bug.</span>
|
||
<span class="gp">>>> </span><span class="n">when</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s2">"%B </span><span class="si">%d</span><span class="s2">"</span><span class="p">)</span>
|
||
<span class="go">'February 29'</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>Class attributes:</p>
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.datetime.min">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">min</span></span><a class="headerlink" href="#datetime.datetime.min" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The earliest representable <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a>, <code class="docutils literal notranslate"><span class="pre">datetime(MINYEAR,</span> <span class="pre">1,</span> <span class="pre">1,</span>
|
||
<span class="pre">tzinfo=None)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.datetime.max">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">max</span></span><a class="headerlink" href="#datetime.datetime.max" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The latest representable <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a>, <code class="docutils literal notranslate"><span class="pre">datetime(MAXYEAR,</span> <span class="pre">12,</span> <span class="pre">31,</span> <span class="pre">23,</span> <span class="pre">59,</span>
|
||
<span class="pre">59,</span> <span class="pre">999999,</span> <span class="pre">tzinfo=None)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.datetime.resolution">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">resolution</span></span><a class="headerlink" href="#datetime.datetime.resolution" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">datetime</span></code></a> objects,
|
||
<code class="docutils literal notranslate"><span class="pre">timedelta(microseconds=1)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<p>Instance attributes (read-only):</p>
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.datetime.year">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">year</span></span><a class="headerlink" href="#datetime.datetime.year" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Between <a class="reference internal" href="#datetime.MINYEAR" title="datetime.MINYEAR"><code class="xref py py-const docutils literal notranslate"><span class="pre">MINYEAR</span></code></a> and <a class="reference internal" href="#datetime.MAXYEAR" title="datetime.MAXYEAR"><code class="xref py py-const docutils literal notranslate"><span class="pre">MAXYEAR</span></code></a> inclusive.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.datetime.month">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">month</span></span><a class="headerlink" href="#datetime.datetime.month" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Between 1 and 12 inclusive.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.datetime.day">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">day</span></span><a class="headerlink" href="#datetime.datetime.day" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Between 1 and the number of days in the given month of the given year.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.datetime.hour">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">hour</span></span><a class="headerlink" href="#datetime.datetime.hour" title="Link to this definition">¶</a></dt>
|
||
<dd><p>In <code class="docutils literal notranslate"><span class="pre">range(24)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.datetime.minute">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">minute</span></span><a class="headerlink" href="#datetime.datetime.minute" title="Link to this definition">¶</a></dt>
|
||
<dd><p>In <code class="docutils literal notranslate"><span class="pre">range(60)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.datetime.second">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">second</span></span><a class="headerlink" href="#datetime.datetime.second" title="Link to this definition">¶</a></dt>
|
||
<dd><p>In <code class="docutils literal notranslate"><span class="pre">range(60)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.datetime.microsecond">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">microsecond</span></span><a class="headerlink" href="#datetime.datetime.microsecond" title="Link to this definition">¶</a></dt>
|
||
<dd><p>In <code class="docutils literal notranslate"><span class="pre">range(1000000)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.datetime.tzinfo">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">tzinfo</span></span><a class="headerlink" href="#datetime.datetime.tzinfo" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The object passed as the <em>tzinfo</em> argument to the <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> constructor,
|
||
or <code class="docutils literal notranslate"><span class="pre">None</span></code> if none was passed.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.datetime.fold">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">fold</span></span><a class="headerlink" href="#datetime.datetime.fold" title="Link to this definition">¶</a></dt>
|
||
<dd><p>In <code class="docutils literal notranslate"><span class="pre">[0,</span> <span class="pre">1]</span></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.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.6.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>Supported operations:</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Operation</p></th>
|
||
<th class="head"><p>Result</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">datetime2</span> <span class="pre">=</span> <span class="pre">datetime1</span> <span class="pre">+</span> <span class="pre">timedelta</span></code></p></td>
|
||
<td><p>(1)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">datetime2</span> <span class="pre">=</span> <span class="pre">datetime1</span> <span class="pre">-</span> <span class="pre">timedelta</span></code></p></td>
|
||
<td><p>(2)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">timedelta</span> <span class="pre">=</span> <span class="pre">datetime1</span> <span class="pre">-</span> <span class="pre">datetime2</span></code></p></td>
|
||
<td><p>(3)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><div class="line-block">
|
||
<div class="line"><code class="docutils literal notranslate"><span class="pre">datetime1</span> <span class="pre">==</span> <span class="pre">datetime2</span></code></div>
|
||
<div class="line"><code class="docutils literal notranslate"><span class="pre">datetime1</span> <span class="pre">!=</span> <span class="pre">datetime2</span></code></div>
|
||
</div>
|
||
</td>
|
||
<td><p>Equality comparison. (4)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><div class="line-block">
|
||
<div class="line"><code class="docutils literal notranslate"><span class="pre">datetime1</span> <span class="pre"><</span> <span class="pre">datetime2</span></code></div>
|
||
<div class="line"><code class="docutils literal notranslate"><span class="pre">datetime1</span> <span class="pre">></span> <span class="pre">datetime2</span></code></div>
|
||
<div class="line"><code class="docutils literal notranslate"><span class="pre">datetime1</span> <span class="pre"><=</span> <span class="pre">datetime2</span></code></div>
|
||
<div class="line"><code class="docutils literal notranslate"><span class="pre">datetime1</span> <span class="pre">>=</span> <span class="pre">datetime2</span></code></div>
|
||
</div>
|
||
</td>
|
||
<td><p>Order comparison. (5)</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<ol class="arabic">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">datetime2</span></code> is a duration of <code class="docutils literal notranslate"><span class="pre">timedelta</span></code> removed from <code class="docutils literal notranslate"><span class="pre">datetime1</span></code>, moving forward in
|
||
time if <code class="docutils literal notranslate"><span class="pre">timedelta.days</span> <span class="pre">></span> <span class="pre">0</span></code>, or backward if <code class="docutils literal notranslate"><span class="pre">timedelta.days</span> <span class="pre"><</span> <span class="pre">0</span></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"><span class="pre">tzinfo</span></code></a> attribute as the input datetime, and
|
||
<code class="docutils literal notranslate"><span class="pre">datetime2</span> <span class="pre">-</span> <span class="pre">datetime1</span> <span class="pre">==</span> <span class="pre">timedelta</span></code> after. <a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> is raised if
|
||
<code class="docutils literal notranslate"><span class="pre">datetime2.year</span></code> would be smaller than <a class="reference internal" href="#datetime.MINYEAR" title="datetime.MINYEAR"><code class="xref py py-const docutils literal notranslate"><span class="pre">MINYEAR</span></code></a> or larger than
|
||
<a class="reference internal" href="#datetime.MAXYEAR" title="datetime.MAXYEAR"><code class="xref py py-const docutils literal notranslate"><span class="pre">MAXYEAR</span></code></a>. Note that no time zone adjustments are done even if the
|
||
input is an aware object.</p></li>
|
||
<li><p>Computes the <code class="docutils literal notranslate"><span class="pre">datetime2</span></code> such that <code class="docutils literal notranslate"><span class="pre">datetime2</span> <span class="pre">+</span> <span class="pre">timedelta</span> <span class="pre">==</span> <span class="pre">datetime1</span></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"><span class="pre">tzinfo</span></code></a> attribute as the input
|
||
datetime, and no time zone adjustments are done even if the input is aware.</p></li>
|
||
<li><p>Subtraction of a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> from a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">TypeError</span></code></a> is raised.</p>
|
||
<p>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"><span class="pre">tzinfo</span></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"><span class="pre">tzinfo</span></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"><span class="pre">timedelta</span></code></a>
|
||
object <code class="docutils literal notranslate"><span class="pre">t</span></code> such that <code class="docutils literal notranslate"><span class="pre">datetime2</span> <span class="pre">+</span> <span class="pre">t</span> <span class="pre">==</span> <span class="pre">datetime1</span></code>. No time zone adjustments
|
||
are done in this case.</p>
|
||
<p>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"><span class="pre">tzinfo</span></code></a> attributes, <code class="docutils literal notranslate"><span class="pre">a-b</span></code> acts
|
||
as if <code class="docutils literal notranslate"><span class="pre">a</span></code> and <code class="docutils literal notranslate"><span class="pre">b</span></code> were first converted to naive UTC datetimes. The
|
||
result is <code class="docutils literal notranslate"><span class="pre">(a.replace(tzinfo=None)</span> <span class="pre">-</span> <span class="pre">a.utcoffset())</span> <span class="pre">-</span> <span class="pre">(b.replace(tzinfo=None)</span>
|
||
<span class="pre">-</span> <span class="pre">b.utcoffset())</span></code> except that the implementation never overflows.</p>
|
||
</li>
|
||
<li><p><a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> objects are equal if they represent the same date
|
||
and time, taking into account the time zone.</p>
|
||
<p>Naive and aware <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code> objects are never equal.</p>
|
||
<p>If both comparands are aware, and have the same <code class="xref py py-attr docutils literal notranslate"><span class="pre">tzinfo</span></code> attribute,
|
||
the <code class="xref py py-attr docutils literal notranslate"><span class="pre">tzinfo</span></code> and <a class="reference internal" href="#datetime.datetime.fold" title="datetime.datetime.fold"><code class="xref py py-attr docutils literal notranslate"><span class="pre">fold</span></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"><span class="pre">tzinfo</span></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"><span class="pre">datetime</span></code> instances in a repeated interval are never equal to
|
||
<code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code> instances in other time zone.</p>
|
||
</li>
|
||
<li><p><em>datetime1</em> is considered less than <em>datetime2</em> when <em>datetime1</em> precedes
|
||
<em>datetime2</em> in time, taking into account the time zone.</p>
|
||
<p>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"><span class="pre">datetime</span></code></a> objects
|
||
raises <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>
|
||
<p>If both comparands are aware, and have the same <code class="xref py py-attr docutils literal notranslate"><span class="pre">tzinfo</span></code> attribute,
|
||
the <code class="xref py py-attr docutils literal notranslate"><span class="pre">tzinfo</span></code> and <a class="reference internal" href="#datetime.datetime.fold" title="datetime.datetime.fold"><code class="xref py py-attr docutils literal notranslate"><span class="pre">fold</span></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"><span class="pre">tzinfo</span></code></a>
|
||
attributes, the comparison acts as comparands were first converted to UTC
|
||
datetimes except that the implementation never overflows.</p>
|
||
</li>
|
||
</ol>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>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"><span class="pre">datetime</span></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"><span class="pre">TypeError</span></code></a>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.13: </span>Comparison between <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">date</span></code></a> subclass that is not a <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code> subclass
|
||
no longer converts the latter to <code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code>, ignoring the time part
|
||
and the time zone.
|
||
The default behavior can be changed by overriding the special comparison
|
||
methods in subclasses.</p>
|
||
</div>
|
||
<p>Instance methods:</p>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.date">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">date</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.date" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a> object with same year, month and day.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.time">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">time</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.time" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></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"><span class="pre">tzinfo</span></code></a> is <code class="docutils literal notranslate"><span class="pre">None</span></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"><span class="pre">timetz()</span></code></a>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>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"><span class="pre">time</span></code></a> object.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.timetz">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">timetz</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.timetz" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></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"><span class="pre">time()</span></code></a>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>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"><span class="pre">time</span></code></a> object.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.replace">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">replace</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">year</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.year</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">month</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.month</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">day</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.day</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">hour</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.hour</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">minute</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.minute</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">second</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.second</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">microsecond</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.microsecond</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tzinfo</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.tzinfo</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">fold</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.replace" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a new <a class="reference internal" href="#module-datetime" title="datetime: Basic date and time types."><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> object with the same attributes, but with
|
||
specified parameters updated. Note that <code class="docutils literal notranslate"><span class="pre">tzinfo=None</span></code> can be specified to
|
||
create a naive datetime from an aware datetime with no conversion of date
|
||
and time data.</p>
|
||
<p><a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">copy.replace()</span></code></a>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Added the <em>fold</em> parameter.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.astimezone">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">astimezone</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tz</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.astimezone" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">tzinfo</span></code></a> attribute <em>tz</em>,
|
||
adjusting the date and time data so the result is the same UTC time as
|
||
<em>self</em>, but in <em>tz</em>’s local time.</p>
|
||
<p>If provided, <em>tz</em> 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"><span class="pre">tzinfo</span></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"><span class="pre">utcoffset()</span></code></a> and <a class="reference internal" href="#datetime.datetime.dst" title="datetime.datetime.dst"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dst()</span></code></a> methods must not return <code class="docutils literal notranslate"><span class="pre">None</span></code>. If <em>self</em>
|
||
is naive, it is presumed to represent time in the system time zone.</p>
|
||
<p>If called without arguments (or with <code class="docutils literal notranslate"><span class="pre">tz=None</span></code>) the system local
|
||
time zone is assumed for the target time zone. The <code class="docutils literal notranslate"><span class="pre">.tzinfo</span></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"><span class="pre">timezone</span></code></a>
|
||
with the zone name and offset obtained from the OS.</p>
|
||
<p>If <code class="docutils literal notranslate"><span class="pre">self.tzinfo</span></code> is <em>tz</em>, <code class="docutils literal notranslate"><span class="pre">self.astimezone(tz)</span></code> is equal to <em>self</em>: no
|
||
adjustment of date or time data is performed. Else the result is local
|
||
time in the time zone <em>tz</em>, representing the same UTC time as <em>self</em>: after
|
||
<code class="docutils literal notranslate"><span class="pre">astz</span> <span class="pre">=</span> <span class="pre">dt.astimezone(tz)</span></code>, <code class="docutils literal notranslate"><span class="pre">astz</span> <span class="pre">-</span> <span class="pre">astz.utcoffset()</span></code> will have
|
||
the same date and time data as <code class="docutils literal notranslate"><span class="pre">dt</span> <span class="pre">-</span> <span class="pre">dt.utcoffset()</span></code>.</p>
|
||
<p>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"><span class="pre">timezone</span></code></a> object <em>tz</em> to a datetime <em>dt</em> without
|
||
adjustment of date and time data, use <code class="docutils literal notranslate"><span class="pre">dt.replace(tzinfo=tz)</span></code>. If you
|
||
merely want to remove the <code class="xref py py-class docutils literal notranslate"><span class="pre">timezone</span></code> object from an aware datetime <em>dt</em> without
|
||
conversion of date and time data, use <code class="docutils literal notranslate"><span class="pre">dt.replace(tzinfo=None)</span></code>.</p>
|
||
<p>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"><span class="pre">tzinfo.fromutc()</span></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"><span class="pre">tzinfo</span></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"><span class="pre">astimezone()</span></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"><span class="pre">astimezone()</span></code></a> acts like:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">astimezone</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tz</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">tzinfo</span> <span class="ow">is</span> <span class="n">tz</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="bp">self</span>
|
||
<span class="c1"># Convert self to UTC, and attach the new timezone object.</span>
|
||
<span class="n">utc</span> <span class="o">=</span> <span class="p">(</span><span class="bp">self</span> <span class="o">-</span> <span class="bp">self</span><span class="o">.</span><span class="n">utcoffset</span><span class="p">())</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">tzinfo</span><span class="o">=</span><span class="n">tz</span><span class="p">)</span>
|
||
<span class="c1"># Convert from UTC to tz's local time.</span>
|
||
<span class="k">return</span> <span class="n">tz</span><span class="o">.</span><span class="n">fromutc</span><span class="p">(</span><span class="n">utc</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span><em>tz</em> now can be omitted.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>The <a class="reference internal" href="#datetime.datetime.astimezone" title="datetime.datetime.astimezone"><code class="xref py py-meth docutils literal notranslate"><span class="pre">astimezone()</span></code></a> method can now be called on naive instances that
|
||
are presumed to represent system local time.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.utcoffset">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">utcoffset</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.utcoffset" title="Link to this definition">¶</a></dt>
|
||
<dd><p>If <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tzinfo</span></code></a> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, returns <code class="docutils literal notranslate"><span class="pre">None</span></code>, else returns
|
||
<code class="docutils literal notranslate"><span class="pre">self.tzinfo.utcoffset(self)</span></code>, and raises an exception if the latter doesn’t
|
||
return <code class="docutils literal notranslate"><span class="pre">None</span></code> or a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></code></a> object with magnitude less than one day.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The UTC offset is not restricted to a whole number of minutes.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.dst">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">dst</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.dst" title="Link to this definition">¶</a></dt>
|
||
<dd><p>If <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tzinfo</span></code></a> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, returns <code class="docutils literal notranslate"><span class="pre">None</span></code>, else returns
|
||
<code class="docutils literal notranslate"><span class="pre">self.tzinfo.dst(self)</span></code>, and raises an exception if the latter doesn’t return
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code> or a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></code></a> object with magnitude less than one day.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The DST offset is not restricted to a whole number of minutes.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.tzname">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">tzname</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.tzname" title="Link to this definition">¶</a></dt>
|
||
<dd><p>If <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tzinfo</span></code></a> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, returns <code class="docutils literal notranslate"><span class="pre">None</span></code>, else returns
|
||
<code class="docutils literal notranslate"><span class="pre">self.tzinfo.tzname(self)</span></code>, raises an exception if the latter doesn’t return
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code> or a string object,</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.timetuple">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">timetuple</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.timetuple" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">time.struct_time</span></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"><span class="pre">time.localtime()</span></code></a>.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">d.timetuple()</span></code> is equivalent to:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">time</span><span class="o">.</span><span class="n">struct_time</span><span class="p">((</span><span class="n">d</span><span class="o">.</span><span class="n">year</span><span class="p">,</span> <span class="n">d</span><span class="o">.</span><span class="n">month</span><span class="p">,</span> <span class="n">d</span><span class="o">.</span><span class="n">day</span><span class="p">,</span>
|
||
<span class="n">d</span><span class="o">.</span><span class="n">hour</span><span class="p">,</span> <span class="n">d</span><span class="o">.</span><span class="n">minute</span><span class="p">,</span> <span class="n">d</span><span class="o">.</span><span class="n">second</span><span class="p">,</span>
|
||
<span class="n">d</span><span class="o">.</span><span class="n">weekday</span><span class="p">(),</span> <span class="n">yday</span><span class="p">,</span> <span class="n">dst</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>where <code class="docutils literal notranslate"><span class="pre">yday</span> <span class="pre">=</span> <span class="pre">d.toordinal()</span> <span class="pre">-</span> <span class="pre">date(d.year,</span> <span class="pre">1,</span> <span class="pre">1).toordinal()</span> <span class="pre">+</span> <span class="pre">1</span></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"><span class="pre">tm_isdst</span></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"><span class="pre">dst()</span></code></a> method: <a class="reference internal" href="#datetime.datetime.tzinfo" title="datetime.datetime.tzinfo"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tzinfo</span></code></a> is <code class="docutils literal notranslate"><span class="pre">None</span></code> or <a class="reference internal" href="#datetime.datetime.dst" title="datetime.datetime.dst"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dst()</span></code></a> returns
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">tm_isdst</span></code> is set to <code class="docutils literal notranslate"><span class="pre">-1</span></code>; else if <a class="reference internal" href="#datetime.datetime.dst" title="datetime.datetime.dst"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dst()</span></code></a> returns a
|
||
non-zero value, <code class="xref py py-attr docutils literal notranslate"><span class="pre">tm_isdst</span></code> is set to 1; else <code class="xref py py-attr docutils literal notranslate"><span class="pre">tm_isdst</span></code> is
|
||
set to 0.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.utctimetuple">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">utctimetuple</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.utctimetuple" title="Link to this definition">¶</a></dt>
|
||
<dd><p>If <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> instance <code class="docutils literal notranslate"><span class="pre">d</span></code> is naive, this is the same as
|
||
<code class="docutils literal notranslate"><span class="pre">d.timetuple()</span></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"><span class="pre">tm_isdst</span></code></a> is forced to 0 regardless of what
|
||
<code class="docutils literal notranslate"><span class="pre">d.dst()</span></code> returns. DST is never in effect for a UTC time.</p>
|
||
<p>If <code class="docutils literal notranslate"><span class="pre">d</span></code> is aware, <code class="docutils literal notranslate"><span class="pre">d</span></code> is normalized to UTC time, by subtracting
|
||
<code class="docutils literal notranslate"><span class="pre">d.utcoffset()</span></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"><span class="pre">time.struct_time</span></code></a> for the
|
||
normalized time is returned. <code class="xref py py-attr docutils literal notranslate"><span class="pre">tm_isdst</span></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"><span class="pre">OverflowError</span></code></a> may be raised if <code class="docutils literal notranslate"><span class="pre">d.year</span></code> was
|
||
<code class="docutils literal notranslate"><span class="pre">MINYEAR</span></code> or <code class="docutils literal notranslate"><span class="pre">MAXYEAR</span></code> and UTC adjustment spills over a year
|
||
boundary.</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>Because naive <code class="docutils literal notranslate"><span class="pre">datetime</span></code> objects are treated by many <code class="docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">datetime.utctimetuple()</span></code></a> may give misleading
|
||
results. If you have a naive <code class="docutils literal notranslate"><span class="pre">datetime</span></code> representing UTC, use
|
||
<code class="docutils literal notranslate"><span class="pre">datetime.replace(tzinfo=timezone.utc)</span></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"><span class="pre">datetime.timetuple()</span></code></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.toordinal">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">toordinal</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.toordinal" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return the proleptic Gregorian ordinal of the date. The same as
|
||
<code class="docutils literal notranslate"><span class="pre">self.date().toordinal()</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.timestamp">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">timestamp</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.timestamp" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">datetime</span></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"><span class="pre">float</span></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"><span class="pre">time.time()</span></code></a>.</p>
|
||
<p>Naive <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">mktime()</span></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"><span class="pre">datetime</span></code></a>
|
||
supports wider range of values than <code class="xref c c-func docutils literal notranslate"><span class="pre">mktime()</span></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"><span class="pre">OverflowError</span></code></a> or <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>
|
||
for times far in the past or far in the future.</p>
|
||
<p>For aware <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> instances, the return value is computed
|
||
as:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">dt</span> <span class="o">-</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">1970</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">timezone</span><span class="o">.</span><span class="n">utc</span><span class="p">))</span><span class="o">.</span><span class="n">total_seconds</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.3.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>The <a class="reference internal" href="#datetime.datetime.timestamp" title="datetime.datetime.timestamp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">timestamp()</span></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"><span class="pre">fold</span></code></a> attribute to
|
||
disambiguate the times during a repeated interval.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>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"><span class="pre">datetime</span></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"><span class="pre">tzinfo=timezone.utc</span></code>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">timestamp</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">tzinfo</span><span class="o">=</span><span class="n">timezone</span><span class="o">.</span><span class="n">utc</span><span class="p">)</span><span class="o">.</span><span class="n">timestamp</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>or by calculating the timestamp directly:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">timestamp</span> <span class="o">=</span> <span class="p">(</span><span class="n">dt</span> <span class="o">-</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">1970</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">))</span> <span class="o">/</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">seconds</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.weekday">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">weekday</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.weekday" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">self.date().weekday()</span></code>. See also <a class="reference internal" href="#datetime.datetime.isoweekday" title="datetime.datetime.isoweekday"><code class="xref py py-meth docutils literal notranslate"><span class="pre">isoweekday()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.isoweekday">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">isoweekday</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.isoweekday" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">self.date().isoweekday()</span></code>. See also <a class="reference internal" href="#datetime.datetime.weekday" title="datetime.datetime.weekday"><code class="xref py py-meth docutils literal notranslate"><span class="pre">weekday()</span></code></a>,
|
||
<a class="reference internal" href="#datetime.datetime.isocalendar" title="datetime.datetime.isocalendar"><code class="xref py py-meth docutils literal notranslate"><span class="pre">isocalendar()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.isocalendar">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">isocalendar</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.isocalendar" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a> with three components: <code class="docutils literal notranslate"><span class="pre">year</span></code>, <code class="docutils literal notranslate"><span class="pre">week</span></code>
|
||
and <code class="docutils literal notranslate"><span class="pre">weekday</span></code>. The same as <code class="docutils literal notranslate"><span class="pre">self.date().isocalendar()</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.isoformat">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">isoformat</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sep</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'T'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timespec</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'auto'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.isoformat" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a string representing the date and time in ISO 8601 format:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">YYYY-MM-DDTHH:MM:SS.ffffff</span></code>, if <a class="reference internal" href="#datetime.datetime.microsecond" title="datetime.datetime.microsecond"><code class="xref py py-attr docutils literal notranslate"><span class="pre">microsecond</span></code></a> is not 0</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">YYYY-MM-DDTHH:MM:SS</span></code>, if <a class="reference internal" href="#datetime.datetime.microsecond" title="datetime.datetime.microsecond"><code class="xref py py-attr docutils literal notranslate"><span class="pre">microsecond</span></code></a> is 0</p></li>
|
||
</ul>
|
||
<p>If <a class="reference internal" href="#datetime.datetime.utcoffset" title="datetime.datetime.utcoffset"><code class="xref py py-meth docutils literal notranslate"><span class="pre">utcoffset()</span></code></a> does not return <code class="docutils literal notranslate"><span class="pre">None</span></code>, a string is
|
||
appended, giving the UTC offset:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]</span></code>, if <a class="reference internal" href="#datetime.datetime.microsecond" title="datetime.datetime.microsecond"><code class="xref py py-attr docutils literal notranslate"><span class="pre">microsecond</span></code></a>
|
||
is not 0</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]</span></code>, if <a class="reference internal" href="#datetime.datetime.microsecond" title="datetime.datetime.microsecond"><code class="xref py py-attr docutils literal notranslate"><span class="pre">microsecond</span></code></a> is 0</p></li>
|
||
</ul>
|
||
<p>Examples:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span><span class="p">,</span> <span class="n">timezone</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="p">(</span><span class="mi">2019</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">18</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">17</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">132263</span><span class="p">)</span><span class="o">.</span><span class="n">isoformat</span><span class="p">()</span>
|
||
<span class="go">'2019-05-18T15:17:08.132263'</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="p">(</span><span class="mi">2019</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">18</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">17</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">timezone</span><span class="o">.</span><span class="n">utc</span><span class="p">)</span><span class="o">.</span><span class="n">isoformat</span><span class="p">()</span>
|
||
<span class="go">'2019-05-18T15:17:00+00:00'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The optional argument <em>sep</em> (default <code class="docutils literal notranslate"><span class="pre">'T'</span></code>) is a one-character separator,
|
||
placed between the date and time portions of the result. For example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">tzinfo</span><span class="p">,</span> <span class="n">timedelta</span><span class="p">,</span> <span class="n">datetime</span>
|
||
<span class="gp">>>> </span><span class="k">class</span><span class="w"> </span><span class="nc">TZ</span><span class="p">(</span><span class="n">tzinfo</span><span class="p">):</span>
|
||
<span class="gp">... </span><span class="w"> </span><span class="sd">"""A time zone with an arbitrary, constant -06:39 offset."""</span>
|
||
<span class="gp">... </span> <span class="k">def</span><span class="w"> </span><span class="nf">utcoffset</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="k">return</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=-</span><span class="mi">6</span><span class="p">,</span> <span class="n">minutes</span><span class="o">=-</span><span class="mi">39</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="p">(</span><span class="mi">2002</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">25</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">TZ</span><span class="p">())</span><span class="o">.</span><span class="n">isoformat</span><span class="p">(</span><span class="s1">' '</span><span class="p">)</span>
|
||
<span class="go">'2002-12-25 00:00:00-06:39'</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="p">(</span><span class="mi">2009</span><span class="p">,</span> <span class="mi">11</span><span class="p">,</span> <span class="mi">27</span><span class="p">,</span> <span class="n">microsecond</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">TZ</span><span class="p">())</span><span class="o">.</span><span class="n">isoformat</span><span class="p">()</span>
|
||
<span class="go">'2009-11-27T00:00:00.000100-06:39'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The optional argument <em>timespec</em> specifies the number of additional
|
||
components of the time to include (the default is <code class="docutils literal notranslate"><span class="pre">'auto'</span></code>).
|
||
It can be one of the following:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'auto'</span></code>: Same as <code class="docutils literal notranslate"><span class="pre">'seconds'</span></code> if <a class="reference internal" href="#datetime.datetime.microsecond" title="datetime.datetime.microsecond"><code class="xref py py-attr docutils literal notranslate"><span class="pre">microsecond</span></code></a> is 0,
|
||
same as <code class="docutils literal notranslate"><span class="pre">'microseconds'</span></code> otherwise.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'hours'</span></code>: Include the <a class="reference internal" href="#datetime.datetime.hour" title="datetime.datetime.hour"><code class="xref py py-attr docutils literal notranslate"><span class="pre">hour</span></code></a> in the two-digit <code class="docutils literal notranslate"><span class="pre">HH</span></code> format.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'minutes'</span></code>: Include <a class="reference internal" href="#datetime.datetime.hour" title="datetime.datetime.hour"><code class="xref py py-attr docutils literal notranslate"><span class="pre">hour</span></code></a> and <a class="reference internal" href="#datetime.datetime.minute" title="datetime.datetime.minute"><code class="xref py py-attr docutils literal notranslate"><span class="pre">minute</span></code></a> in <code class="docutils literal notranslate"><span class="pre">HH:MM</span></code> format.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'seconds'</span></code>: Include <a class="reference internal" href="#datetime.datetime.hour" title="datetime.datetime.hour"><code class="xref py py-attr docutils literal notranslate"><span class="pre">hour</span></code></a>, <a class="reference internal" href="#datetime.datetime.minute" title="datetime.datetime.minute"><code class="xref py py-attr docutils literal notranslate"><span class="pre">minute</span></code></a>, and <a class="reference internal" href="#datetime.datetime.second" title="datetime.datetime.second"><code class="xref py py-attr docutils literal notranslate"><span class="pre">second</span></code></a>
|
||
in <code class="docutils literal notranslate"><span class="pre">HH:MM:SS</span></code> format.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'milliseconds'</span></code>: Include full time, but truncate fractional second
|
||
part to milliseconds. <code class="docutils literal notranslate"><span class="pre">HH:MM:SS.sss</span></code> format.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'microseconds'</span></code>: Include full time in <code class="docutils literal notranslate"><span class="pre">HH:MM:SS.ffffff</span></code> format.</p></li>
|
||
</ul>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Excluded time components are truncated, not rounded.</p>
|
||
</div>
|
||
<p><a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> will be raised on an invalid <em>timespec</em> argument:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span><span class="o">.</span><span class="n">isoformat</span><span class="p">(</span><span class="n">timespec</span><span class="o">=</span><span class="s1">'minutes'</span><span class="p">)</span>
|
||
<span class="go">'2002-12-25T00:00'</span>
|
||
<span class="gp">>>> </span><span class="n">dt</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">2015</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">30</span><span class="p">,</span> <span class="mi">59</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">dt</span><span class="o">.</span><span class="n">isoformat</span><span class="p">(</span><span class="n">timespec</span><span class="o">=</span><span class="s1">'microseconds'</span><span class="p">)</span>
|
||
<span class="go">'2015-01-01T12:30:59.000000'</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Added the <em>timespec</em> parameter.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.__str__">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">__str__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.__str__" title="Link to this definition">¶</a></dt>
|
||
<dd><p>For a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> instance <code class="docutils literal notranslate"><span class="pre">d</span></code>, <code class="docutils literal notranslate"><span class="pre">str(d)</span></code> is equivalent to
|
||
<code class="docutils literal notranslate"><span class="pre">d.isoformat('</span> <span class="pre">')</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.ctime">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">ctime</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.ctime" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a string representing the date and time:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="p">(</span><span class="mi">2002</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">20</span><span class="p">,</span> <span class="mi">30</span><span class="p">,</span> <span class="mi">40</span><span class="p">)</span><span class="o">.</span><span class="n">ctime</span><span class="p">()</span>
|
||
<span class="go">'Wed Dec 4 20:30:40 2002'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The output string will <em>not</em> include time zone information, regardless
|
||
of whether the input is aware or naive.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">d.ctime()</span></code> is equivalent to:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">time</span><span class="o">.</span><span class="n">ctime</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">mktime</span><span class="p">(</span><span class="n">d</span><span class="o">.</span><span class="n">timetuple</span><span class="p">()))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>on platforms where the native C <code class="xref c c-func docutils literal notranslate"><span class="pre">ctime()</span></code> function
|
||
(which <a class="reference internal" href="time.html#time.ctime" title="time.ctime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.ctime()</span></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"><span class="pre">datetime.ctime()</span></code></a> does not invoke) conforms to the C standard.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.strftime">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">strftime</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">format</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.strftime" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a string representing the date and time,
|
||
controlled by an explicit format string.
|
||
See also <a class="reference internal" href="#strftime-strptime-behavior"><span class="std std-ref">strftime() and strptime() Behavior</span></a> and <a class="reference internal" href="#datetime.datetime.isoformat" title="datetime.datetime.isoformat"><code class="xref py py-meth docutils literal notranslate"><span class="pre">datetime.isoformat()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.datetime.__format__">
|
||
<span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">__format__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">format</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.datetime.__format__" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Same as <a class="reference internal" href="#datetime.datetime.strftime" title="datetime.datetime.strftime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">datetime.strftime()</span></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"><span class="pre">datetime</span></code></a> object in <a class="reference internal" href="../reference/lexical_analysis.html#f-strings"><span class="std std-ref">formatted string
|
||
literals</span></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"><span class="pre">str.format()</span></code></a>.
|
||
See also <a class="reference internal" href="#strftime-strptime-behavior"><span class="std std-ref">strftime() and strptime() Behavior</span></a> and <a class="reference internal" href="#datetime.datetime.isoformat" title="datetime.datetime.isoformat"><code class="xref py py-meth docutils literal notranslate"><span class="pre">datetime.isoformat()</span></code></a>.</p>
|
||
</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"><span class="pre">datetime</span></code></a><a class="headerlink" href="#examples-of-usage-datetime" title="Link to this heading">¶</a></h3>
|
||
<p>Examples of working with <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> objects:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span><span class="p">,</span> <span class="n">date</span><span class="p">,</span> <span class="n">time</span><span class="p">,</span> <span class="n">timezone</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Using datetime.combine()</span>
|
||
<span class="gp">>>> </span><span class="n">d</span> <span class="o">=</span> <span class="n">date</span><span class="p">(</span><span class="mi">2005</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">14</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">t</span> <span class="o">=</span> <span class="n">time</span><span class="p">(</span><span class="mi">12</span><span class="p">,</span> <span class="mi">30</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">combine</span><span class="p">(</span><span class="n">d</span><span class="p">,</span> <span class="n">t</span><span class="p">)</span>
|
||
<span class="go">datetime.datetime(2005, 7, 14, 12, 30)</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Using datetime.now()</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span>
|
||
<span class="go">datetime.datetime(2007, 12, 6, 16, 29, 43, 79043) # GMT +1</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">(</span><span class="n">timezone</span><span class="o">.</span><span class="n">utc</span><span class="p">)</span>
|
||
<span class="go">datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Using datetime.strptime()</span>
|
||
<span class="gp">>>> </span><span class="n">dt</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">strptime</span><span class="p">(</span><span class="s2">"21/11/06 16:30"</span><span class="p">,</span> <span class="s2">"</span><span class="si">%d</span><span class="s2">/%m/%y %H:%M"</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">dt</span>
|
||
<span class="go">datetime.datetime(2006, 11, 21, 16, 30)</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Using datetime.timetuple() to get tuple of all attributes</span>
|
||
<span class="gp">>>> </span><span class="n">tt</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">timetuple</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="k">for</span> <span class="n">it</span> <span class="ow">in</span> <span class="n">tt</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">it</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="go">2006 # year</span>
|
||
<span class="go">11 # month</span>
|
||
<span class="go">21 # day</span>
|
||
<span class="go">16 # hour</span>
|
||
<span class="go">30 # minute</span>
|
||
<span class="go">0 # second</span>
|
||
<span class="go">1 # weekday (0 = Monday)</span>
|
||
<span class="go">325 # number of days since 1st January</span>
|
||
<span class="go">-1 # dst - method tzinfo.dst() returned None</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Date in ISO format</span>
|
||
<span class="gp">>>> </span><span class="n">ic</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">isocalendar</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="k">for</span> <span class="n">it</span> <span class="ow">in</span> <span class="n">ic</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">it</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="go">2006 # ISO year</span>
|
||
<span class="go">47 # ISO week</span>
|
||
<span class="go">2 # ISO weekday</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Formatting a datetime</span>
|
||
<span class="gp">>>> </span><span class="n">dt</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s2">"%A, </span><span class="si">%d</span><span class="s2">. %B %Y %I:%M%p"</span><span class="p">)</span>
|
||
<span class="go">'Tuesday, 21. November 2006 04:30PM'</span>
|
||
<span class="gp">>>> </span><span class="s1">'The </span><span class="si">{1}</span><span class="s1"> is {0:</span><span class="si">%d</span><span class="s1">}, the </span><span class="si">{2}</span><span class="s1"> is {0:%B}, the </span><span class="si">{3}</span><span class="s1"> is {0:%I:%M%p}.'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">dt</span><span class="p">,</span> <span class="s2">"day"</span><span class="p">,</span> <span class="s2">"month"</span><span class="p">,</span> <span class="s2">"time"</span><span class="p">)</span>
|
||
<span class="go">'The day is 21, the month is November, the time is 04:30PM.'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The example below defines a <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></code></a> subclass capturing time zone
|
||
information for Kabul, Afghanistan, which used +4 UTC until 1945
|
||
and then +4:30 UTC thereafter:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">timedelta</span><span class="p">,</span> <span class="n">datetime</span><span class="p">,</span> <span class="n">tzinfo</span><span class="p">,</span> <span class="n">timezone</span>
|
||
|
||
<span class="k">class</span><span class="w"> </span><span class="nc">KabulTz</span><span class="p">(</span><span class="n">tzinfo</span><span class="p">):</span>
|
||
<span class="c1"># Kabul used +4 until 1945, when they moved to +4:30</span>
|
||
<span class="n">UTC_MOVE_DATE</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">1944</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">31</span><span class="p">,</span> <span class="mi">20</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">timezone</span><span class="o">.</span><span class="n">utc</span><span class="p">)</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">utcoffset</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="n">dt</span><span class="o">.</span><span class="n">year</span> <span class="o"><</span> <span class="mi">1945</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span>
|
||
<span class="k">elif</span> <span class="p">(</span><span class="mi">1945</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o"><=</span> <span class="n">dt</span><span class="o">.</span><span class="n">timetuple</span><span class="p">()[:</span><span class="mi">5</span><span class="p">]</span> <span class="o"><</span> <span class="p">(</span><span class="mi">1945</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">30</span><span class="p">):</span>
|
||
<span class="c1"># An ambiguous ("imaginary") half-hour range representing</span>
|
||
<span class="c1"># a 'fold' in time due to the shift from +4 to +4:30.</span>
|
||
<span class="c1"># If dt falls in the imaginary range, use fold to decide how</span>
|
||
<span class="c1"># to resolve. See PEP495.</span>
|
||
<span class="k">return</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">4</span><span class="p">,</span> <span class="n">minutes</span><span class="o">=</span><span class="p">(</span><span class="mi">30</span> <span class="k">if</span> <span class="n">dt</span><span class="o">.</span><span class="n">fold</span> <span class="k">else</span> <span class="mi">0</span><span class="p">))</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">4</span><span class="p">,</span> <span class="n">minutes</span><span class="o">=</span><span class="mi">30</span><span class="p">)</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">fromutc</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="c1"># Follow same validations as in datetime.tzinfo</span>
|
||
<span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">dt</span><span class="p">,</span> <span class="n">datetime</span><span class="p">):</span>
|
||
<span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s2">"fromutc() requires a datetime argument"</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">dt</span><span class="o">.</span><span class="n">tzinfo</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">self</span><span class="p">:</span>
|
||
<span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">"dt.tzinfo is not self"</span><span class="p">)</span>
|
||
|
||
<span class="c1"># A custom implementation is required for fromutc as</span>
|
||
<span class="c1"># the input to this function is a datetime with utc values</span>
|
||
<span class="c1"># but with a tzinfo set to self.</span>
|
||
<span class="c1"># See datetime.astimezone or fromtimestamp.</span>
|
||
<span class="k">if</span> <span class="n">dt</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">tzinfo</span><span class="o">=</span><span class="n">timezone</span><span class="o">.</span><span class="n">utc</span><span class="p">)</span> <span class="o">>=</span> <span class="bp">self</span><span class="o">.</span><span class="n">UTC_MOVE_DATE</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="n">dt</span> <span class="o">+</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">4</span><span class="p">,</span> <span class="n">minutes</span><span class="o">=</span><span class="mi">30</span><span class="p">)</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="n">dt</span> <span class="o">+</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">dst</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="c1"># Kabul does not observe daylight saving time.</span>
|
||
<span class="k">return</span> <span class="n">timedelta</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">tzname</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="n">dt</span> <span class="o">>=</span> <span class="bp">self</span><span class="o">.</span><span class="n">UTC_MOVE_DATE</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="s2">"+04:30"</span>
|
||
<span class="k">return</span> <span class="s2">"+04"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Usage of <code class="docutils literal notranslate"><span class="pre">KabulTz</span></code> from above:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">tz1</span> <span class="o">=</span> <span class="n">KabulTz</span><span class="p">()</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Datetime before the change</span>
|
||
<span class="gp">>>> </span><span class="n">dt1</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">1900</span><span class="p">,</span> <span class="mi">11</span><span class="p">,</span> <span class="mi">21</span><span class="p">,</span> <span class="mi">16</span><span class="p">,</span> <span class="mi">30</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">tz1</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">dt1</span><span class="o">.</span><span class="n">utcoffset</span><span class="p">())</span>
|
||
<span class="go">4:00:00</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Datetime after the change</span>
|
||
<span class="gp">>>> </span><span class="n">dt2</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">2006</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">14</span><span class="p">,</span> <span class="mi">13</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">tz1</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">dt2</span><span class="o">.</span><span class="n">utcoffset</span><span class="p">())</span>
|
||
<span class="go">4:30:00</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Convert datetime to another time zone</span>
|
||
<span class="gp">>>> </span><span class="n">dt3</span> <span class="o">=</span> <span class="n">dt2</span><span class="o">.</span><span class="n">astimezone</span><span class="p">(</span><span class="n">timezone</span><span class="o">.</span><span class="n">utc</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">dt3</span>
|
||
<span class="go">datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)</span>
|
||
<span class="gp">>>> </span><span class="n">dt2</span>
|
||
<span class="go">datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())</span>
|
||
<span class="gp">>>> </span><span class="n">dt2</span> <span class="o">==</span> <span class="n">dt3</span>
|
||
<span class="go">True</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="time-objects">
|
||
<span id="datetime-time"></span><h2><a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a> Objects<a class="headerlink" href="#time-objects" title="Link to this heading">¶</a></h2>
|
||
<p>A <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></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"><span class="pre">tzinfo</span></code></a> object.</p>
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="datetime.time">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">time</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">hour</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">minute</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">second</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">microsecond</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tzinfo</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">fold</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.time" title="Link to this definition">¶</a></dt>
|
||
<dd><p>All arguments are optional. <em>tzinfo</em> may be <code class="docutils literal notranslate"><span class="pre">None</span></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"><span class="pre">tzinfo</span></code></a> subclass. The remaining arguments must be integers in the
|
||
following ranges:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre"><=</span> <span class="pre">hour</span> <span class="pre"><</span> <span class="pre">24</span></code>,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre"><=</span> <span class="pre">minute</span> <span class="pre"><</span> <span class="pre">60</span></code>,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre"><=</span> <span class="pre">second</span> <span class="pre"><</span> <span class="pre">60</span></code>,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre"><=</span> <span class="pre">microsecond</span> <span class="pre"><</span> <span class="pre">1000000</span></code>,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">fold</span> <span class="pre">in</span> <span class="pre">[0,</span> <span class="pre">1]</span></code>.</p></li>
|
||
</ul>
|
||
<p>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"><span class="pre">ValueError</span></code></a> is raised. All
|
||
default to 0 except <em>tzinfo</em>, which defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<p>Class attributes:</p>
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.time.min">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">min</span></span><a class="headerlink" href="#datetime.time.min" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The earliest representable <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a>, <code class="docutils literal notranslate"><span class="pre">time(0,</span> <span class="pre">0,</span> <span class="pre">0,</span> <span class="pre">0)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.time.max">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">max</span></span><a class="headerlink" href="#datetime.time.max" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The latest representable <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a>, <code class="docutils literal notranslate"><span class="pre">time(23,</span> <span class="pre">59,</span> <span class="pre">59,</span> <span class="pre">999999)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.time.resolution">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">resolution</span></span><a class="headerlink" href="#datetime.time.resolution" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">time</span></code></a> objects,
|
||
<code class="docutils literal notranslate"><span class="pre">timedelta(microseconds=1)</span></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"><span class="pre">time</span></code></a> objects is not supported.</p>
|
||
</dd></dl>
|
||
|
||
<p>Instance attributes (read-only):</p>
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.time.hour">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">hour</span></span><a class="headerlink" href="#datetime.time.hour" title="Link to this definition">¶</a></dt>
|
||
<dd><p>In <code class="docutils literal notranslate"><span class="pre">range(24)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.time.minute">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">minute</span></span><a class="headerlink" href="#datetime.time.minute" title="Link to this definition">¶</a></dt>
|
||
<dd><p>In <code class="docutils literal notranslate"><span class="pre">range(60)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.time.second">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">second</span></span><a class="headerlink" href="#datetime.time.second" title="Link to this definition">¶</a></dt>
|
||
<dd><p>In <code class="docutils literal notranslate"><span class="pre">range(60)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.time.microsecond">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">microsecond</span></span><a class="headerlink" href="#datetime.time.microsecond" title="Link to this definition">¶</a></dt>
|
||
<dd><p>In <code class="docutils literal notranslate"><span class="pre">range(1000000)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.time.tzinfo">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">tzinfo</span></span><a class="headerlink" href="#datetime.time.tzinfo" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">time</span></code></a> constructor, or
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code> if none was passed.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.time.fold">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">fold</span></span><a class="headerlink" href="#datetime.time.fold" title="Link to this definition">¶</a></dt>
|
||
<dd><p>In <code class="docutils literal notranslate"><span class="pre">[0,</span> <span class="pre">1]</span></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.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.6.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p><a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a> objects support equality and order comparisons,
|
||
where <code class="docutils literal notranslate"><span class="pre">a</span></code> is considered less than <code class="docutils literal notranslate"><span class="pre">b</span></code> when <code class="docutils literal notranslate"><span class="pre">a</span></code> precedes <code class="docutils literal notranslate"><span class="pre">b</span></code> in time.</p>
|
||
<p>Naive and aware <code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code> objects are never equal.
|
||
Order comparison between naive and aware <code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code> objects raises
|
||
<a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>
|
||
<p>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"><span class="pre">tzinfo</span></code></a>
|
||
attribute, the <code class="xref py py-attr docutils literal notranslate"><span class="pre">tzinfo</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">fold</span></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"><span class="pre">tzinfo</span></code> attributes, the comparands are first adjusted by
|
||
subtracting their UTC offsets (obtained from <code class="docutils literal notranslate"><span class="pre">self.utcoffset()</span></code>).</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>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"><span class="pre">time</span></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"><span class="pre">TypeError</span></code></a>.</p>
|
||
</div>
|
||
<p>In Boolean contexts, a <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a> object is always considered to be true.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>Before Python 3.5, a <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></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.</p>
|
||
</div>
|
||
<p>Other constructor:</p>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.time.fromisoformat">
|
||
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">fromisoformat</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">time_string</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.time.fromisoformat" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a> corresponding to a <em>time_string</em> in any valid
|
||
ISO 8601 format, with the following exceptions:</p>
|
||
<ol class="arabic simple">
|
||
<li><p>Time zone offsets may have fractional seconds.</p></li>
|
||
<li><p>The leading <code class="docutils literal notranslate"><span class="pre">T</span></code>, normally required in cases where there may be ambiguity between
|
||
a date and a time, is not required.</p></li>
|
||
<li><p>Fractional seconds may have any number of digits (anything beyond 6 will
|
||
be truncated).</p></li>
|
||
<li><p>Fractional hours and minutes are not supported.</p></li>
|
||
</ol>
|
||
<p>Examples:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">time</span>
|
||
<span class="gp">>>> </span><span class="n">time</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'04:23:01'</span><span class="p">)</span>
|
||
<span class="go">datetime.time(4, 23, 1)</span>
|
||
<span class="gp">>>> </span><span class="n">time</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'T04:23:01'</span><span class="p">)</span>
|
||
<span class="go">datetime.time(4, 23, 1)</span>
|
||
<span class="gp">>>> </span><span class="n">time</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'T042301'</span><span class="p">)</span>
|
||
<span class="go">datetime.time(4, 23, 1)</span>
|
||
<span class="gp">>>> </span><span class="n">time</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'04:23:01.000384'</span><span class="p">)</span>
|
||
<span class="go">datetime.time(4, 23, 1, 384)</span>
|
||
<span class="gp">>>> </span><span class="n">time</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'04:23:01,000384'</span><span class="p">)</span>
|
||
<span class="go">datetime.time(4, 23, 1, 384)</span>
|
||
<span class="gp">>>> </span><span class="n">time</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'04:23:01+04:00'</span><span class="p">)</span>
|
||
<span class="go">datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))</span>
|
||
<span class="gp">>>> </span><span class="n">time</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'04:23:01Z'</span><span class="p">)</span>
|
||
<span class="go">datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)</span>
|
||
<span class="gp">>>> </span><span class="n">time</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="s1">'04:23:01+00:00'</span><span class="p">)</span>
|
||
<span class="go">datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.7.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span>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"><span class="pre">time.isoformat()</span></code></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>Instance methods:</p>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.time.replace">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">replace</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">hour</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.hour</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">minute</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.minute</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">second</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.second</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">microsecond</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.microsecond</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tzinfo</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">self.tzinfo</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">fold</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.time.replace" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a new <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a> with the same values, but with specified
|
||
parameters updated. Note that <code class="docutils literal notranslate"><span class="pre">tzinfo=None</span></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"><span class="pre">time</span></code></a> from an aware <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a>, without conversion of the
|
||
time data.</p>
|
||
<p><a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></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"><span class="pre">copy.replace()</span></code></a>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Added the <em>fold</em> parameter.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.time.isoformat">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">isoformat</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">timespec</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'auto'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.time.isoformat" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a string representing the time in ISO 8601 format, one of:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">HH:MM:SS.ffffff</span></code>, if <a class="reference internal" href="#datetime.time.microsecond" title="datetime.time.microsecond"><code class="xref py py-attr docutils literal notranslate"><span class="pre">microsecond</span></code></a> is not 0</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">HH:MM:SS</span></code>, if <a class="reference internal" href="#datetime.time.microsecond" title="datetime.time.microsecond"><code class="xref py py-attr docutils literal notranslate"><span class="pre">microsecond</span></code></a> is 0</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]</span></code>, if <a class="reference internal" href="#datetime.time.utcoffset" title="datetime.time.utcoffset"><code class="xref py py-meth docutils literal notranslate"><span class="pre">utcoffset()</span></code></a> does not return <code class="docutils literal notranslate"><span class="pre">None</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">HH:MM:SS+HH:MM[:SS[.ffffff]]</span></code>, if <a class="reference internal" href="#datetime.time.microsecond" title="datetime.time.microsecond"><code class="xref py py-attr docutils literal notranslate"><span class="pre">microsecond</span></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"><span class="pre">utcoffset()</span></code></a> does not return <code class="docutils literal notranslate"><span class="pre">None</span></code></p></li>
|
||
</ul>
|
||
<p>The optional argument <em>timespec</em> specifies the number of additional
|
||
components of the time to include (the default is <code class="docutils literal notranslate"><span class="pre">'auto'</span></code>).
|
||
It can be one of the following:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'auto'</span></code>: Same as <code class="docutils literal notranslate"><span class="pre">'seconds'</span></code> if <a class="reference internal" href="#datetime.time.microsecond" title="datetime.time.microsecond"><code class="xref py py-attr docutils literal notranslate"><span class="pre">microsecond</span></code></a> is 0,
|
||
same as <code class="docutils literal notranslate"><span class="pre">'microseconds'</span></code> otherwise.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'hours'</span></code>: Include the <a class="reference internal" href="#datetime.time.hour" title="datetime.time.hour"><code class="xref py py-attr docutils literal notranslate"><span class="pre">hour</span></code></a> in the two-digit <code class="docutils literal notranslate"><span class="pre">HH</span></code> format.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'minutes'</span></code>: Include <a class="reference internal" href="#datetime.time.hour" title="datetime.time.hour"><code class="xref py py-attr docutils literal notranslate"><span class="pre">hour</span></code></a> and <a class="reference internal" href="#datetime.time.minute" title="datetime.time.minute"><code class="xref py py-attr docutils literal notranslate"><span class="pre">minute</span></code></a> in <code class="docutils literal notranslate"><span class="pre">HH:MM</span></code> format.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'seconds'</span></code>: Include <a class="reference internal" href="#datetime.time.hour" title="datetime.time.hour"><code class="xref py py-attr docutils literal notranslate"><span class="pre">hour</span></code></a>, <a class="reference internal" href="#datetime.time.minute" title="datetime.time.minute"><code class="xref py py-attr docutils literal notranslate"><span class="pre">minute</span></code></a>, and <a class="reference internal" href="#datetime.time.second" title="datetime.time.second"><code class="xref py py-attr docutils literal notranslate"><span class="pre">second</span></code></a>
|
||
in <code class="docutils literal notranslate"><span class="pre">HH:MM:SS</span></code> format.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'milliseconds'</span></code>: Include full time, but truncate fractional second
|
||
part to milliseconds. <code class="docutils literal notranslate"><span class="pre">HH:MM:SS.sss</span></code> format.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'microseconds'</span></code>: Include full time in <code class="docutils literal notranslate"><span class="pre">HH:MM:SS.ffffff</span></code> format.</p></li>
|
||
</ul>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Excluded time components are truncated, not rounded.</p>
|
||
</div>
|
||
<p><a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> will be raised on an invalid <em>timespec</em> argument.</p>
|
||
<p>Example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">time</span>
|
||
<span class="gp">>>> </span><span class="n">time</span><span class="p">(</span><span class="n">hour</span><span class="o">=</span><span class="mi">12</span><span class="p">,</span> <span class="n">minute</span><span class="o">=</span><span class="mi">34</span><span class="p">,</span> <span class="n">second</span><span class="o">=</span><span class="mi">56</span><span class="p">,</span> <span class="n">microsecond</span><span class="o">=</span><span class="mi">123456</span><span class="p">)</span><span class="o">.</span><span class="n">isoformat</span><span class="p">(</span><span class="n">timespec</span><span class="o">=</span><span class="s1">'minutes'</span><span class="p">)</span>
|
||
<span class="go">'12:34'</span>
|
||
<span class="gp">>>> </span><span class="n">dt</span> <span class="o">=</span> <span class="n">time</span><span class="p">(</span><span class="n">hour</span><span class="o">=</span><span class="mi">12</span><span class="p">,</span> <span class="n">minute</span><span class="o">=</span><span class="mi">34</span><span class="p">,</span> <span class="n">second</span><span class="o">=</span><span class="mi">56</span><span class="p">,</span> <span class="n">microsecond</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">dt</span><span class="o">.</span><span class="n">isoformat</span><span class="p">(</span><span class="n">timespec</span><span class="o">=</span><span class="s1">'microseconds'</span><span class="p">)</span>
|
||
<span class="go">'12:34:56.000000'</span>
|
||
<span class="gp">>>> </span><span class="n">dt</span><span class="o">.</span><span class="n">isoformat</span><span class="p">(</span><span class="n">timespec</span><span class="o">=</span><span class="s1">'auto'</span><span class="p">)</span>
|
||
<span class="go">'12:34:56'</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Added the <em>timespec</em> parameter.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.time.__str__">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">__str__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.time.__str__" title="Link to this definition">¶</a></dt>
|
||
<dd><p>For a time <code class="docutils literal notranslate"><span class="pre">t</span></code>, <code class="docutils literal notranslate"><span class="pre">str(t)</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">t.isoformat()</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.time.strftime">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">strftime</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">format</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.time.strftime" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a string representing the time, controlled by an explicit format
|
||
string. See also <a class="reference internal" href="#strftime-strptime-behavior"><span class="std std-ref">strftime() and strptime() Behavior</span></a> and <a class="reference internal" href="#datetime.time.isoformat" title="datetime.time.isoformat"><code class="xref py py-meth docutils literal notranslate"><span class="pre">time.isoformat()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.time.__format__">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">__format__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">format</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.time.__format__" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Same as <a class="reference internal" href="#datetime.time.strftime" title="datetime.time.strftime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">time.strftime()</span></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"><span class="pre">time</span></code></a> object in <a class="reference internal" href="../reference/lexical_analysis.html#f-strings"><span class="std std-ref">formatted string
|
||
literals</span></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"><span class="pre">str.format()</span></code></a>.
|
||
See also <a class="reference internal" href="#strftime-strptime-behavior"><span class="std std-ref">strftime() and strptime() Behavior</span></a> and <a class="reference internal" href="#datetime.time.isoformat" title="datetime.time.isoformat"><code class="xref py py-meth docutils literal notranslate"><span class="pre">time.isoformat()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.time.utcoffset">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">utcoffset</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.time.utcoffset" title="Link to this definition">¶</a></dt>
|
||
<dd><p>If <a class="reference internal" href="#datetime.time.tzinfo" title="datetime.time.tzinfo"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tzinfo</span></code></a> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, returns <code class="docutils literal notranslate"><span class="pre">None</span></code>, else returns
|
||
<code class="docutils literal notranslate"><span class="pre">self.tzinfo.utcoffset(None)</span></code>, and raises an exception if the latter doesn’t
|
||
return <code class="docutils literal notranslate"><span class="pre">None</span></code> or a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></code></a> object with magnitude less than one day.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The UTC offset is not restricted to a whole number of minutes.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.time.dst">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">dst</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.time.dst" title="Link to this definition">¶</a></dt>
|
||
<dd><p>If <a class="reference internal" href="#datetime.time.tzinfo" title="datetime.time.tzinfo"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tzinfo</span></code></a> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, returns <code class="docutils literal notranslate"><span class="pre">None</span></code>, else returns
|
||
<code class="docutils literal notranslate"><span class="pre">self.tzinfo.dst(None)</span></code>, and raises an exception if the latter doesn’t return
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code>, or a <a class="reference internal" href="#datetime.timedelta" title="datetime.timedelta"><code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></code></a> object with magnitude less than one day.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The DST offset is not restricted to a whole number of minutes.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.time.tzname">
|
||
<span class="sig-prename descclassname"><span class="pre">time.</span></span><span class="sig-name descname"><span class="pre">tzname</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#datetime.time.tzname" title="Link to this definition">¶</a></dt>
|
||
<dd><p>If <a class="reference internal" href="#datetime.time.tzinfo" title="datetime.time.tzinfo"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tzinfo</span></code></a> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, returns <code class="docutils literal notranslate"><span class="pre">None</span></code>, else returns
|
||
<code class="docutils literal notranslate"><span class="pre">self.tzinfo.tzname(None)</span></code>, or raises an exception if the latter doesn’t
|
||
return <code class="docutils literal notranslate"><span class="pre">None</span></code> or a string object.</p>
|
||
</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"><span class="pre">time</span></code></a><a class="headerlink" href="#examples-of-usage-time" title="Link to this heading">¶</a></h3>
|
||
<p>Examples of working with a <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a> object:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">time</span><span class="p">,</span> <span class="n">tzinfo</span><span class="p">,</span> <span class="n">timedelta</span>
|
||
<span class="gp">>>> </span><span class="k">class</span><span class="w"> </span><span class="nc">TZ1</span><span class="p">(</span><span class="n">tzinfo</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="k">def</span><span class="w"> </span><span class="nf">utcoffset</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="k">return</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="k">def</span><span class="w"> </span><span class="nf">dst</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="k">return</span> <span class="n">timedelta</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="k">def</span><span class="w"> </span><span class="nf">tzname</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span><span class="n">dt</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="k">return</span> <span class="s2">"+01:00"</span>
|
||
<span class="gp">... </span> <span class="k">def</span><span class="w"> </span><span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="k">return</span> <span class="sa">f</span><span class="s2">"</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="vm">__name__</span><span class="si">}</span><span class="s2">()"</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">>>> </span><span class="n">t</span> <span class="o">=</span> <span class="n">time</span><span class="p">(</span><span class="mi">12</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">30</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">TZ1</span><span class="p">())</span>
|
||
<span class="gp">>>> </span><span class="n">t</span>
|
||
<span class="go">datetime.time(12, 10, 30, tzinfo=TZ1())</span>
|
||
<span class="gp">>>> </span><span class="n">t</span><span class="o">.</span><span class="n">isoformat</span><span class="p">()</span>
|
||
<span class="go">'12:10:30+01:00'</span>
|
||
<span class="gp">>>> </span><span class="n">t</span><span class="o">.</span><span class="n">dst</span><span class="p">()</span>
|
||
<span class="go">datetime.timedelta(0)</span>
|
||
<span class="gp">>>> </span><span class="n">t</span><span class="o">.</span><span class="n">tzname</span><span class="p">()</span>
|
||
<span class="go">'+01:00'</span>
|
||
<span class="gp">>>> </span><span class="n">t</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s2">"%H:%M:%S %Z"</span><span class="p">)</span>
|
||
<span class="go">'12:10:30 +01:00'</span>
|
||
<span class="gp">>>> </span><span class="s1">'The </span><span class="si">{}</span><span class="s1"> is {:%H:%M}.'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="s2">"time"</span><span class="p">,</span> <span class="n">t</span><span class="p">)</span>
|
||
<span class="go">'The time is 12:10.'</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="tzinfo-objects">
|
||
<span id="datetime-tzinfo"></span><h2><a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></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">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">tzinfo</span></span><a class="headerlink" href="#datetime.tzinfo" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">tzinfo</span></code></a> to capture
|
||
information about a particular time zone.</p>
|
||
<p>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"><span class="pre">tzinfo</span></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"><span class="pre">datetime</span></code></a> and <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></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"><span class="pre">tzinfo</span></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.</p>
|
||
<p>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"><span class="pre">tzinfo</span></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"><span class="pre">datetime</span></code></a> methods you use. The <code class="xref py py-mod docutils literal notranslate"><span class="pre">datetime</span></code> module provides
|
||
<a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate"><span class="pre">timezone</span></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"><span class="pre">tzinfo</span></code></a> which can
|
||
represent time zones with fixed offset from UTC such as UTC itself or North
|
||
American EST and EDT.</p>
|
||
<p>Special requirement for pickling: A <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></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"><span class="pre">__init__()</span></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.</p>
|
||
<p>A concrete subclass of <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></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"><span class="pre">datetime</span></code> objects. If in doubt, simply implement all of them.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.tzinfo.utcoffset">
|
||
<span class="sig-prename descclassname"><span class="pre">tzinfo.</span></span><span class="sig-name descname"><span class="pre">utcoffset</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dt</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.tzinfo.utcoffset" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">timedelta</span></code></a> object that is
|
||
positive east of UTC. If local time is west of UTC, this should be negative.</p>
|
||
<p>This represents the <em>total</em> 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"><span class="pre">tzinfo</span></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"><span class="pre">utcoffset()</span></code></a> should return their sum. If the UTC offset isn’t known,
|
||
return <code class="docutils literal notranslate"><span class="pre">None</span></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"><span class="pre">timedelta</span></code></a> object
|
||
strictly between <code class="docutils literal notranslate"><span class="pre">-timedelta(hours=24)</span></code> and <code class="docutils literal notranslate"><span class="pre">timedelta(hours=24)</span></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"><span class="pre">utcoffset()</span></code></a> will probably look like one of these two:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">return</span> <span class="n">CONSTANT</span> <span class="c1"># fixed-offset class</span>
|
||
<span class="k">return</span> <span class="n">CONSTANT</span> <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">dst</span><span class="p">(</span><span class="n">dt</span><span class="p">)</span> <span class="c1"># daylight-aware class</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If <a class="reference internal" href="#datetime.tzinfo.utcoffset" title="datetime.tzinfo.utcoffset"><code class="xref py py-meth docutils literal notranslate"><span class="pre">utcoffset()</span></code></a> does not return <code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="#datetime.tzinfo.dst" title="datetime.tzinfo.dst"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dst()</span></code></a> should not return
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code> either.</p>
|
||
<p>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"><span class="pre">utcoffset()</span></code></a> raises
|
||
<a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The UTC offset is not restricted to a whole number of minutes.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.tzinfo.dst">
|
||
<span class="sig-prename descclassname"><span class="pre">tzinfo.</span></span><span class="sig-name descname"><span class="pre">dst</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dt</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.tzinfo.dst" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">timedelta</span></code></a>
|
||
object or
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code> if DST information isn’t known.</p>
|
||
<p>Return <code class="docutils literal notranslate"><span class="pre">timedelta(0)</span></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"><span class="pre">timedelta</span></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"><span class="pre">utcoffset()</span></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"><span class="pre">utcoffset()</span></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"><span class="pre">dst()</span></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"><span class="pre">datetime.timetuple()</span></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"><span class="pre">tzinfo</span></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"><span class="pre">dst()</span></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"><span class="pre">tm_isdst</span></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"><span class="pre">tzinfo.fromutc()</span></code></a> calls <a class="reference internal" href="#datetime.tzinfo.dst" title="datetime.tzinfo.dst"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dst()</span></code></a> to account for
|
||
DST changes when crossing time zones.</p>
|
||
<p>An instance <em>tz</em> of a <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></code></a> subclass that models both standard and
|
||
daylight times must be consistent in this sense:</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">tz.utcoffset(dt)</span> <span class="pre">-</span> <span class="pre">tz.dst(dt)</span></code></p>
|
||
<p>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"><span class="pre">datetime</span></code></a> <em>dt</em> with <code class="docutils literal notranslate"><span class="pre">dt.tzinfo</span> <span class="pre">==</span>
|
||
<span class="pre">tz</span></code>. For sane <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></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"><span class="pre">datetime.astimezone()</span></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"><span class="pre">tzinfo</span></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"><span class="pre">tzinfo.fromutc()</span></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"><span class="pre">astimezone()</span></code></a> regardless.</p>
|
||
<p>Most implementations of <a class="reference internal" href="#datetime.tzinfo.dst" title="datetime.tzinfo.dst"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dst()</span></code></a> will probably look like one of these two:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">dst</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="c1"># a fixed-offset class: doesn't account for DST</span>
|
||
<span class="k">return</span> <span class="n">timedelta</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>or:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">dst</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="c1"># Code to set dston and dstoff to the time zone's DST</span>
|
||
<span class="c1"># transition times based on the input dt.year, and expressed</span>
|
||
<span class="c1"># in standard local time.</span>
|
||
|
||
<span class="k">if</span> <span class="n">dston</span> <span class="o"><=</span> <span class="n">dt</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">tzinfo</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span> <span class="o"><</span> <span class="n">dstoff</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="n">timedelta</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>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"><span class="pre">dst()</span></code></a> raises <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The DST offset is not restricted to a whole number of minutes.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.tzinfo.tzname">
|
||
<span class="sig-prename descclassname"><span class="pre">tzinfo.</span></span><span class="sig-name descname"><span class="pre">tzname</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dt</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.tzinfo.tzname" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">datetime</span></code></a> object <em>dt</em>, as
|
||
a string. Nothing about string names is defined by the <code class="xref py py-mod docutils literal notranslate"><span class="pre">datetime</span></code> module,
|
||
and there’s no requirement that it mean anything in particular. For example,
|
||
<code class="docutils literal notranslate"><span class="pre">"GMT"</span></code>, <code class="docutils literal notranslate"><span class="pre">"UTC"</span></code>, <code class="docutils literal notranslate"><span class="pre">"-500"</span></code>, <code class="docutils literal notranslate"><span class="pre">"-5:00"</span></code>, <code class="docutils literal notranslate"><span class="pre">"EDT"</span></code>, <code class="docutils literal notranslate"><span class="pre">"US/Eastern"</span></code>, <code class="docutils literal notranslate"><span class="pre">"America/New</span> <span class="pre">York"</span></code> are all
|
||
valid replies. Return <code class="docutils literal notranslate"><span class="pre">None</span></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"><span class="pre">tzinfo</span></code></a>
|
||
subclasses will wish to return different names depending on the specific value
|
||
of <em>dt</em> passed, especially if the <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></code></a> class is accounting for
|
||
daylight time.</p>
|
||
<p>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"><span class="pre">tzname()</span></code></a> raises <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<p>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"><span class="pre">datetime</span></code></a> or <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></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"><span class="pre">datetime</span></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"><span class="pre">time</span></code></a> object passes <code class="docutils literal notranslate"><span class="pre">None</span></code> as the
|
||
argument. A <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></code></a> subclass’s methods should therefore be prepared to
|
||
accept a <em>dt</em> argument of <code class="docutils literal notranslate"><span class="pre">None</span></code>, or of class <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a>.</p>
|
||
<p>When <code class="docutils literal notranslate"><span class="pre">None</span></code> is passed, it’s up to the class designer to decide the best
|
||
response. For example, returning <code class="docutils literal notranslate"><span class="pre">None</span></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"><span class="pre">tzinfo</span></code></a> protocols. It
|
||
may be more useful for <code class="docutils literal notranslate"><span class="pre">utcoffset(None)</span></code> to return the standard UTC offset, as
|
||
there is no other convention for discovering the standard offset.</p>
|
||
<p>When a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">datetime</span></code></a>
|
||
method, <code class="docutils literal notranslate"><span class="pre">dt.tzinfo</span></code> is the same object as <em>self</em>. <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></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"><span class="pre">tzinfo</span></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"><span class="pre">tzinfo</span></code></a> methods interpret <em>dt</em> as being in local
|
||
time, and not need worry about objects in other time zones.</p>
|
||
<p>There is one more <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></code></a> method that a subclass may wish to override:</p>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.tzinfo.fromutc">
|
||
<span class="sig-prename descclassname"><span class="pre">tzinfo.</span></span><span class="sig-name descname"><span class="pre">fromutc</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dt</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.tzinfo.fromutc" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">datetime.astimezone()</span></code></a>
|
||
implementation. When called from that, <code class="docutils literal notranslate"><span class="pre">dt.tzinfo</span></code> is <em>self</em>, and <em>dt</em>’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"><span class="pre">fromutc()</span></code></a> is to adjust the date and time data, returning an
|
||
equivalent datetime in <em>self</em>’s local time.</p>
|
||
<p>Most <a class="reference internal" href="#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></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"><span class="pre">fromutc()</span></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"><span class="pre">fromutc()</span></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"><span class="pre">astimezone()</span></code></a> and
|
||
<a class="reference internal" href="#datetime.tzinfo.fromutc" title="datetime.tzinfo.fromutc"><code class="xref py py-meth docutils literal notranslate"><span class="pre">fromutc()</span></code></a> may not produce the result you want if the result is one of the
|
||
hours straddling the moment the standard offset changes.</p>
|
||
<p>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"><span class="pre">fromutc()</span></code></a> implementation acts
|
||
like:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">fromutc</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="c1"># raise ValueError error if dt.tzinfo is not self</span>
|
||
<span class="n">dtoff</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">utcoffset</span><span class="p">()</span>
|
||
<span class="n">dtdst</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">dst</span><span class="p">()</span>
|
||
<span class="c1"># raise ValueError if dtoff is None or dtdst is None</span>
|
||
<span class="n">delta</span> <span class="o">=</span> <span class="n">dtoff</span> <span class="o">-</span> <span class="n">dtdst</span> <span class="c1"># this is self's standard offset</span>
|
||
<span class="k">if</span> <span class="n">delta</span><span class="p">:</span>
|
||
<span class="n">dt</span> <span class="o">+=</span> <span class="n">delta</span> <span class="c1"># convert to standard local time</span>
|
||
<span class="n">dtdst</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">dst</span><span class="p">()</span>
|
||
<span class="c1"># raise ValueError if dtdst is None</span>
|
||
<span class="k">if</span> <span class="n">dtdst</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="n">dt</span> <span class="o">+</span> <span class="n">dtdst</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="n">dt</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>In the following <a class="reference download internal" download="" href="../_downloads/6dc1f3f4f0e6ca13cb42ddf4d6cbc8af/tzinfo_examples.py"><code class="xref download docutils literal notranslate"><span class="pre">tzinfo_examples.py</span></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"><span class="pre">tzinfo</span></code></a> classes:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">tzinfo</span><span class="p">,</span> <span class="n">timedelta</span><span class="p">,</span> <span class="n">datetime</span>
|
||
|
||
<span class="n">ZERO</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
|
||
<span class="n">HOUR</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
|
||
<span class="n">SECOND</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">seconds</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
|
||
|
||
<span class="c1"># A class capturing the platform's idea of local time.</span>
|
||
<span class="c1"># (May result in wrong values on historical times in</span>
|
||
<span class="c1"># timezones where UTC offset and/or the DST rules had</span>
|
||
<span class="c1"># changed in the past.)</span>
|
||
<span class="kn">import</span><span class="w"> </span><span class="nn">time</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">_time</span>
|
||
|
||
<span class="n">STDOFFSET</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">seconds</span> <span class="o">=</span> <span class="o">-</span><span class="n">_time</span><span class="o">.</span><span class="n">timezone</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">_time</span><span class="o">.</span><span class="n">daylight</span><span class="p">:</span>
|
||
<span class="n">DSTOFFSET</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">seconds</span> <span class="o">=</span> <span class="o">-</span><span class="n">_time</span><span class="o">.</span><span class="n">altzone</span><span class="p">)</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="n">DSTOFFSET</span> <span class="o">=</span> <span class="n">STDOFFSET</span>
|
||
|
||
<span class="n">DSTDIFF</span> <span class="o">=</span> <span class="n">DSTOFFSET</span> <span class="o">-</span> <span class="n">STDOFFSET</span>
|
||
|
||
<span class="k">class</span><span class="w"> </span><span class="nc">LocalTimezone</span><span class="p">(</span><span class="n">tzinfo</span><span class="p">):</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">fromutc</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="k">assert</span> <span class="n">dt</span><span class="o">.</span><span class="n">tzinfo</span> <span class="ow">is</span> <span class="bp">self</span>
|
||
<span class="n">stamp</span> <span class="o">=</span> <span class="p">(</span><span class="n">dt</span> <span class="o">-</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">1970</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="bp">self</span><span class="p">))</span> <span class="o">//</span> <span class="n">SECOND</span>
|
||
<span class="n">args</span> <span class="o">=</span> <span class="n">_time</span><span class="o">.</span><span class="n">localtime</span><span class="p">(</span><span class="n">stamp</span><span class="p">)[:</span><span class="mi">6</span><span class="p">]</span>
|
||
<span class="n">dst_diff</span> <span class="o">=</span> <span class="n">DSTDIFF</span> <span class="o">//</span> <span class="n">SECOND</span>
|
||
<span class="c1"># Detect fold</span>
|
||
<span class="n">fold</span> <span class="o">=</span> <span class="p">(</span><span class="n">args</span> <span class="o">==</span> <span class="n">_time</span><span class="o">.</span><span class="n">localtime</span><span class="p">(</span><span class="n">stamp</span> <span class="o">-</span> <span class="n">dst_diff</span><span class="p">))</span>
|
||
<span class="k">return</span> <span class="n">datetime</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="n">microsecond</span><span class="o">=</span><span class="n">dt</span><span class="o">.</span><span class="n">microsecond</span><span class="p">,</span>
|
||
<span class="n">tzinfo</span><span class="o">=</span><span class="bp">self</span><span class="p">,</span> <span class="n">fold</span><span class="o">=</span><span class="n">fold</span><span class="p">)</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">utcoffset</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_isdst</span><span class="p">(</span><span class="n">dt</span><span class="p">):</span>
|
||
<span class="k">return</span> <span class="n">DSTOFFSET</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="n">STDOFFSET</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">dst</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_isdst</span><span class="p">(</span><span class="n">dt</span><span class="p">):</span>
|
||
<span class="k">return</span> <span class="n">DSTDIFF</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="n">ZERO</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">tzname</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="k">return</span> <span class="n">_time</span><span class="o">.</span><span class="n">tzname</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">_isdst</span><span class="p">(</span><span class="n">dt</span><span class="p">)]</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">_isdst</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="n">tt</span> <span class="o">=</span> <span class="p">(</span><span class="n">dt</span><span class="o">.</span><span class="n">year</span><span class="p">,</span> <span class="n">dt</span><span class="o">.</span><span class="n">month</span><span class="p">,</span> <span class="n">dt</span><span class="o">.</span><span class="n">day</span><span class="p">,</span>
|
||
<span class="n">dt</span><span class="o">.</span><span class="n">hour</span><span class="p">,</span> <span class="n">dt</span><span class="o">.</span><span class="n">minute</span><span class="p">,</span> <span class="n">dt</span><span class="o">.</span><span class="n">second</span><span class="p">,</span>
|
||
<span class="n">dt</span><span class="o">.</span><span class="n">weekday</span><span class="p">(),</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
|
||
<span class="n">stamp</span> <span class="o">=</span> <span class="n">_time</span><span class="o">.</span><span class="n">mktime</span><span class="p">(</span><span class="n">tt</span><span class="p">)</span>
|
||
<span class="n">tt</span> <span class="o">=</span> <span class="n">_time</span><span class="o">.</span><span class="n">localtime</span><span class="p">(</span><span class="n">stamp</span><span class="p">)</span>
|
||
<span class="k">return</span> <span class="n">tt</span><span class="o">.</span><span class="n">tm_isdst</span> <span class="o">></span> <span class="mi">0</span>
|
||
|
||
<span class="n">Local</span> <span class="o">=</span> <span class="n">LocalTimezone</span><span class="p">()</span>
|
||
|
||
|
||
<span class="c1"># A complete implementation of current DST rules for major US time zones.</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">first_sunday_on_or_after</span><span class="p">(</span><span class="n">dt</span><span class="p">):</span>
|
||
<span class="n">days_to_go</span> <span class="o">=</span> <span class="mi">6</span> <span class="o">-</span> <span class="n">dt</span><span class="o">.</span><span class="n">weekday</span><span class="p">()</span>
|
||
<span class="k">if</span> <span class="n">days_to_go</span><span class="p">:</span>
|
||
<span class="n">dt</span> <span class="o">+=</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">days_to_go</span><span class="p">)</span>
|
||
<span class="k">return</span> <span class="n">dt</span>
|
||
|
||
|
||
<span class="c1"># US DST Rules</span>
|
||
<span class="c1">#</span>
|
||
<span class="c1"># This is a simplified (i.e., wrong for a few cases) set of rules for US</span>
|
||
<span class="c1"># DST start and end times. For a complete and up-to-date set of DST rules</span>
|
||
<span class="c1"># and timezone definitions, visit the Olson Database (or try pytz):</span>
|
||
<span class="c1"># http://www.twinsun.com/tz/tz-link.htm</span>
|
||
<span class="c1"># https://sourceforge.net/projects/pytz/ (might not be up-to-date)</span>
|
||
<span class="c1">#</span>
|
||
<span class="c1"># In the US, since 2007, DST starts at 2am (standard time) on the second</span>
|
||
<span class="c1"># Sunday in March, which is the first Sunday on or after Mar 8.</span>
|
||
<span class="n">DSTSTART_2007</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
|
||
<span class="c1"># and ends at 2am (DST time) on the first Sunday of Nov.</span>
|
||
<span class="n">DSTEND_2007</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">11</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
|
||
<span class="c1"># From 1987 to 2006, DST used to start at 2am (standard time) on the first</span>
|
||
<span class="c1"># Sunday in April and to end at 2am (DST time) on the last</span>
|
||
<span class="c1"># Sunday of October, which is the first Sunday on or after Oct 25.</span>
|
||
<span class="n">DSTSTART_1987_2006</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
|
||
<span class="n">DSTEND_1987_2006</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">25</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
|
||
<span class="c1"># From 1967 to 1986, DST used to start at 2am (standard time) on the last</span>
|
||
<span class="c1"># Sunday in April (the one on or after April 24) and to end at 2am (DST time)</span>
|
||
<span class="c1"># on the last Sunday of October, which is the first Sunday</span>
|
||
<span class="c1"># on or after Oct 25.</span>
|
||
<span class="n">DSTSTART_1967_1986</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">24</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
|
||
<span class="n">DSTEND_1967_1986</span> <span class="o">=</span> <span class="n">DSTEND_1987_2006</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">us_dst_range</span><span class="p">(</span><span class="n">year</span><span class="p">):</span>
|
||
<span class="c1"># Find start and end times for US DST. For years before 1967, return</span>
|
||
<span class="c1"># start = end for no DST.</span>
|
||
<span class="k">if</span> <span class="mi">2006</span> <span class="o"><</span> <span class="n">year</span><span class="p">:</span>
|
||
<span class="n">dststart</span><span class="p">,</span> <span class="n">dstend</span> <span class="o">=</span> <span class="n">DSTSTART_2007</span><span class="p">,</span> <span class="n">DSTEND_2007</span>
|
||
<span class="k">elif</span> <span class="mi">1986</span> <span class="o"><</span> <span class="n">year</span> <span class="o"><</span> <span class="mi">2007</span><span class="p">:</span>
|
||
<span class="n">dststart</span><span class="p">,</span> <span class="n">dstend</span> <span class="o">=</span> <span class="n">DSTSTART_1987_2006</span><span class="p">,</span> <span class="n">DSTEND_1987_2006</span>
|
||
<span class="k">elif</span> <span class="mi">1966</span> <span class="o"><</span> <span class="n">year</span> <span class="o"><</span> <span class="mi">1987</span><span class="p">:</span>
|
||
<span class="n">dststart</span><span class="p">,</span> <span class="n">dstend</span> <span class="o">=</span> <span class="n">DSTSTART_1967_1986</span><span class="p">,</span> <span class="n">DSTEND_1967_1986</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="p">(</span><span class="n">datetime</span><span class="p">(</span><span class="n">year</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">)</span> <span class="o">*</span> <span class="mi">2</span>
|
||
|
||
<span class="n">start</span> <span class="o">=</span> <span class="n">first_sunday_on_or_after</span><span class="p">(</span><span class="n">dststart</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">year</span><span class="o">=</span><span class="n">year</span><span class="p">))</span>
|
||
<span class="n">end</span> <span class="o">=</span> <span class="n">first_sunday_on_or_after</span><span class="p">(</span><span class="n">dstend</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">year</span><span class="o">=</span><span class="n">year</span><span class="p">))</span>
|
||
<span class="k">return</span> <span class="n">start</span><span class="p">,</span> <span class="n">end</span>
|
||
|
||
|
||
<span class="k">class</span><span class="w"> </span><span class="nc">USTimeZone</span><span class="p">(</span><span class="n">tzinfo</span><span class="p">):</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">hours</span><span class="p">,</span> <span class="n">reprname</span><span class="p">,</span> <span class="n">stdname</span><span class="p">,</span> <span class="n">dstname</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">stdoffset</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="n">hours</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">reprname</span> <span class="o">=</span> <span class="n">reprname</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">stdname</span> <span class="o">=</span> <span class="n">stdname</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">dstname</span> <span class="o">=</span> <span class="n">dstname</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">reprname</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">tzname</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">dst</span><span class="p">(</span><span class="n">dt</span><span class="p">):</span>
|
||
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">dstname</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">stdname</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">utcoffset</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">stdoffset</span> <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">dst</span><span class="p">(</span><span class="n">dt</span><span class="p">)</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">dst</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="n">dt</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">or</span> <span class="n">dt</span><span class="o">.</span><span class="n">tzinfo</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
|
||
<span class="c1"># An exception may be sensible here, in one or both cases.</span>
|
||
<span class="c1"># It depends on how you want to treat them. The default</span>
|
||
<span class="c1"># fromutc() implementation (called by the default astimezone()</span>
|
||
<span class="c1"># implementation) passes a datetime with dt.tzinfo is self.</span>
|
||
<span class="k">return</span> <span class="n">ZERO</span>
|
||
<span class="k">assert</span> <span class="n">dt</span><span class="o">.</span><span class="n">tzinfo</span> <span class="ow">is</span> <span class="bp">self</span>
|
||
<span class="n">start</span><span class="p">,</span> <span class="n">end</span> <span class="o">=</span> <span class="n">us_dst_range</span><span class="p">(</span><span class="n">dt</span><span class="o">.</span><span class="n">year</span><span class="p">)</span>
|
||
<span class="c1"># Can't compare naive to aware objects, so strip the timezone from</span>
|
||
<span class="c1"># dt first.</span>
|
||
<span class="n">dt</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">tzinfo</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">start</span> <span class="o">+</span> <span class="n">HOUR</span> <span class="o"><=</span> <span class="n">dt</span> <span class="o"><</span> <span class="n">end</span> <span class="o">-</span> <span class="n">HOUR</span><span class="p">:</span>
|
||
<span class="c1"># DST is in effect.</span>
|
||
<span class="k">return</span> <span class="n">HOUR</span>
|
||
<span class="k">if</span> <span class="n">end</span> <span class="o">-</span> <span class="n">HOUR</span> <span class="o"><=</span> <span class="n">dt</span> <span class="o"><</span> <span class="n">end</span><span class="p">:</span>
|
||
<span class="c1"># Fold (an ambiguous hour): use dt.fold to disambiguate.</span>
|
||
<span class="k">return</span> <span class="n">ZERO</span> <span class="k">if</span> <span class="n">dt</span><span class="o">.</span><span class="n">fold</span> <span class="k">else</span> <span class="n">HOUR</span>
|
||
<span class="k">if</span> <span class="n">start</span> <span class="o"><=</span> <span class="n">dt</span> <span class="o"><</span> <span class="n">start</span> <span class="o">+</span> <span class="n">HOUR</span><span class="p">:</span>
|
||
<span class="c1"># Gap (a non-existent hour): reverse the fold rule.</span>
|
||
<span class="k">return</span> <span class="n">HOUR</span> <span class="k">if</span> <span class="n">dt</span><span class="o">.</span><span class="n">fold</span> <span class="k">else</span> <span class="n">ZERO</span>
|
||
<span class="c1"># DST is off.</span>
|
||
<span class="k">return</span> <span class="n">ZERO</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">fromutc</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dt</span><span class="p">):</span>
|
||
<span class="k">assert</span> <span class="n">dt</span><span class="o">.</span><span class="n">tzinfo</span> <span class="ow">is</span> <span class="bp">self</span>
|
||
<span class="n">start</span><span class="p">,</span> <span class="n">end</span> <span class="o">=</span> <span class="n">us_dst_range</span><span class="p">(</span><span class="n">dt</span><span class="o">.</span><span class="n">year</span><span class="p">)</span>
|
||
<span class="n">start</span> <span class="o">=</span> <span class="n">start</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">tzinfo</span><span class="o">=</span><span class="bp">self</span><span class="p">)</span>
|
||
<span class="n">end</span> <span class="o">=</span> <span class="n">end</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">tzinfo</span><span class="o">=</span><span class="bp">self</span><span class="p">)</span>
|
||
<span class="n">std_time</span> <span class="o">=</span> <span class="n">dt</span> <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">stdoffset</span>
|
||
<span class="n">dst_time</span> <span class="o">=</span> <span class="n">std_time</span> <span class="o">+</span> <span class="n">HOUR</span>
|
||
<span class="k">if</span> <span class="n">end</span> <span class="o"><=</span> <span class="n">dst_time</span> <span class="o"><</span> <span class="n">end</span> <span class="o">+</span> <span class="n">HOUR</span><span class="p">:</span>
|
||
<span class="c1"># Repeated hour</span>
|
||
<span class="k">return</span> <span class="n">std_time</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">fold</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">std_time</span> <span class="o"><</span> <span class="n">start</span> <span class="ow">or</span> <span class="n">dst_time</span> <span class="o">>=</span> <span class="n">end</span><span class="p">:</span>
|
||
<span class="c1"># Standard time</span>
|
||
<span class="k">return</span> <span class="n">std_time</span>
|
||
<span class="k">if</span> <span class="n">start</span> <span class="o"><=</span> <span class="n">std_time</span> <span class="o"><</span> <span class="n">end</span> <span class="o">-</span> <span class="n">HOUR</span><span class="p">:</span>
|
||
<span class="c1"># Daylight saving time</span>
|
||
<span class="k">return</span> <span class="n">dst_time</span>
|
||
|
||
|
||
<span class="n">Eastern</span> <span class="o">=</span> <span class="n">USTimeZone</span><span class="p">(</span><span class="o">-</span><span class="mi">5</span><span class="p">,</span> <span class="s2">"Eastern"</span><span class="p">,</span> <span class="s2">"EST"</span><span class="p">,</span> <span class="s2">"EDT"</span><span class="p">)</span>
|
||
<span class="n">Central</span> <span class="o">=</span> <span class="n">USTimeZone</span><span class="p">(</span><span class="o">-</span><span class="mi">6</span><span class="p">,</span> <span class="s2">"Central"</span><span class="p">,</span> <span class="s2">"CST"</span><span class="p">,</span> <span class="s2">"CDT"</span><span class="p">)</span>
|
||
<span class="n">Mountain</span> <span class="o">=</span> <span class="n">USTimeZone</span><span class="p">(</span><span class="o">-</span><span class="mi">7</span><span class="p">,</span> <span class="s2">"Mountain"</span><span class="p">,</span> <span class="s2">"MST"</span><span class="p">,</span> <span class="s2">"MDT"</span><span class="p">)</span>
|
||
<span class="n">Pacific</span> <span class="o">=</span> <span class="n">USTimeZone</span><span class="p">(</span><span class="o">-</span><span class="mi">8</span><span class="p">,</span> <span class="s2">"Pacific"</span><span class="p">,</span> <span class="s2">"PST"</span><span class="p">,</span> <span class="s2">"PDT"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>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"><span class="pre">tzinfo</span></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:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span> <span class="n">UTC</span> <span class="mi">3</span><span class="p">:</span><span class="n">MM</span> <span class="mi">4</span><span class="p">:</span><span class="n">MM</span> <span class="mi">5</span><span class="p">:</span><span class="n">MM</span> <span class="mi">6</span><span class="p">:</span><span class="n">MM</span> <span class="mi">7</span><span class="p">:</span><span class="n">MM</span> <span class="mi">8</span><span class="p">:</span><span class="n">MM</span>
|
||
<span class="n">EST</span> <span class="mi">22</span><span class="p">:</span><span class="n">MM</span> <span class="mi">23</span><span class="p">:</span><span class="n">MM</span> <span class="mi">0</span><span class="p">:</span><span class="n">MM</span> <span class="mi">1</span><span class="p">:</span><span class="n">MM</span> <span class="mi">2</span><span class="p">:</span><span class="n">MM</span> <span class="mi">3</span><span class="p">:</span><span class="n">MM</span>
|
||
<span class="n">EDT</span> <span class="mi">23</span><span class="p">:</span><span class="n">MM</span> <span class="mi">0</span><span class="p">:</span><span class="n">MM</span> <span class="mi">1</span><span class="p">:</span><span class="n">MM</span> <span class="mi">2</span><span class="p">:</span><span class="n">MM</span> <span class="mi">3</span><span class="p">:</span><span class="n">MM</span> <span class="mi">4</span><span class="p">:</span><span class="n">MM</span>
|
||
|
||
<span class="n">start</span> <span class="mi">22</span><span class="p">:</span><span class="n">MM</span> <span class="mi">23</span><span class="p">:</span><span class="n">MM</span> <span class="mi">0</span><span class="p">:</span><span class="n">MM</span> <span class="mi">1</span><span class="p">:</span><span class="n">MM</span> <span class="mi">3</span><span class="p">:</span><span class="n">MM</span> <span class="mi">4</span><span class="p">:</span><span class="n">MM</span>
|
||
|
||
<span class="n">end</span> <span class="mi">23</span><span class="p">:</span><span class="n">MM</span> <span class="mi">0</span><span class="p">:</span><span class="n">MM</span> <span class="mi">1</span><span class="p">:</span><span class="n">MM</span> <span class="mi">1</span><span class="p">:</span><span class="n">MM</span> <span class="mi">2</span><span class="p">:</span><span class="n">MM</span> <span class="mi">3</span><span class="p">:</span><span class="n">MM</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>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"><span class="pre">astimezone(Eastern)</span></code> won’t deliver a result with <code class="docutils literal notranslate"><span class="pre">hour</span> <span class="pre">==</span> <span class="pre">2</span></code> on the day DST
|
||
begins. For example, at the Spring forward transition of 2016, we get:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span><span class="p">,</span> <span class="n">timezone</span>
|
||
<span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">tzinfo_examples</span><span class="w"> </span><span class="kn">import</span> <span class="n">HOUR</span><span class="p">,</span> <span class="n">Eastern</span>
|
||
<span class="gp">>>> </span><span class="n">u0</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">2016</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">13</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">timezone</span><span class="o">.</span><span class="n">utc</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">4</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="n">u</span> <span class="o">=</span> <span class="n">u0</span> <span class="o">+</span> <span class="n">i</span><span class="o">*</span><span class="n">HOUR</span>
|
||
<span class="gp">... </span> <span class="n">t</span> <span class="o">=</span> <span class="n">u</span><span class="o">.</span><span class="n">astimezone</span><span class="p">(</span><span class="n">Eastern</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">u</span><span class="o">.</span><span class="n">time</span><span class="p">(),</span> <span class="s1">'UTC ='</span><span class="p">,</span> <span class="n">t</span><span class="o">.</span><span class="n">time</span><span class="p">(),</span> <span class="n">t</span><span class="o">.</span><span class="n">tzname</span><span class="p">())</span>
|
||
<span class="gp">...</span>
|
||
<span class="go">05:00:00 UTC = 00:00:00 EST</span>
|
||
<span class="go">06:00:00 UTC = 01:00:00 EST</span>
|
||
<span class="go">07:00:00 UTC = 03:00:00 EDT</span>
|
||
<span class="go">08:00:00 UTC = 04:00:00 EDT</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>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"><span class="pre">astimezone()</span></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"><span class="pre">fold</span></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:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">u0</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">2016</span><span class="p">,</span> <span class="mi">11</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">timezone</span><span class="o">.</span><span class="n">utc</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">4</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="n">u</span> <span class="o">=</span> <span class="n">u0</span> <span class="o">+</span> <span class="n">i</span><span class="o">*</span><span class="n">HOUR</span>
|
||
<span class="gp">... </span> <span class="n">t</span> <span class="o">=</span> <span class="n">u</span><span class="o">.</span><span class="n">astimezone</span><span class="p">(</span><span class="n">Eastern</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">u</span><span class="o">.</span><span class="n">time</span><span class="p">(),</span> <span class="s1">'UTC ='</span><span class="p">,</span> <span class="n">t</span><span class="o">.</span><span class="n">time</span><span class="p">(),</span> <span class="n">t</span><span class="o">.</span><span class="n">tzname</span><span class="p">(),</span> <span class="n">t</span><span class="o">.</span><span class="n">fold</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="go">04:00:00 UTC = 00:00:00 EDT 0</span>
|
||
<span class="go">05:00:00 UTC = 01:00:00 EDT 0</span>
|
||
<span class="go">06:00:00 UTC = 01:00:00 EST 1</span>
|
||
<span class="go">07:00:00 UTC = 02:00:00 EST 0</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that the <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></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"><span class="pre">fold</span></code></a> attribute are considered equal in comparisons.</p>
|
||
<p>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"><span class="pre">fold</span></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"><span class="pre">tzinfo</span></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"><span class="pre">timezone</span></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"><span class="pre">tzinfo</span></code></a> subclass (such as a class representing
|
||
only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<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"><span class="pre">zoneinfo</span></code></a></dt><dd><p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">datetime</span></code> module has a basic <a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate"><span class="pre">timezone</span></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"><span class="pre">timezone.utc</span></code></a>
|
||
attribute (a UTC <code class="xref py py-class docutils literal notranslate"><span class="pre">timezone</span></code> instance).</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">zoneinfo</span></code> brings the <em>IANA time zone database</em> (also known as the Olson
|
||
database) to Python, and its usage is recommended.</p>
|
||
</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><p>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.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</section>
|
||
<section id="timezone-objects">
|
||
<span id="datetime-timezone"></span><h2><a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate"><span class="pre">timezone</span></code></a> Objects<a class="headerlink" href="#timezone-objects" title="Link to this heading">¶</a></h2>
|
||
<p>The <a class="reference internal" href="#datetime.timezone" title="datetime.timezone"><code class="xref py py-class docutils literal notranslate"><span class="pre">timezone</span></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"><span class="pre">tzinfo</span></code></a>, each
|
||
instance of which represents a time zone defined by a fixed offset from
|
||
UTC.</p>
|
||
<p>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.</p>
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="datetime.timezone">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">datetime.</span></span><span class="sig-name descname"><span class="pre">timezone</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">offset</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.timezone" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The <em>offset</em> 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"><span class="pre">timedelta</span></code></a>
|
||
object representing the difference between the local time and UTC. It must
|
||
be strictly between <code class="docutils literal notranslate"><span class="pre">-timedelta(hours=24)</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">timedelta(hours=24)</span></code>, otherwise <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised.</p>
|
||
<p>The <em>name</em> 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"><span class="pre">datetime.tzname()</span></code></a> method.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.2.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The UTC offset is not restricted to a whole number of minutes.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.timezone.utcoffset">
|
||
<span class="sig-prename descclassname"><span class="pre">timezone.</span></span><span class="sig-name descname"><span class="pre">utcoffset</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dt</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.timezone.utcoffset" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">timezone</span></code></a> instance is
|
||
constructed.</p>
|
||
<p>The <em>dt</em> 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"><span class="pre">timedelta</span></code></a>
|
||
instance equal to the difference between the local time and UTC.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The UTC offset is not restricted to a whole number of minutes.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.timezone.tzname">
|
||
<span class="sig-prename descclassname"><span class="pre">timezone.</span></span><span class="sig-name descname"><span class="pre">tzname</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dt</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.timezone.tzname" title="Link to this definition">¶</a></dt>
|
||
<dd><p>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"><span class="pre">timezone</span></code></a> instance
|
||
is constructed.</p>
|
||
<p>If <em>name</em> is not provided in the constructor, the name returned by
|
||
<code class="docutils literal notranslate"><span class="pre">tzname(dt)</span></code> is generated from the value of the <code class="docutils literal notranslate"><span class="pre">offset</span></code> as follows. If
|
||
<em>offset</em> is <code class="docutils literal notranslate"><span class="pre">timedelta(0)</span></code>, the name is “UTC”, otherwise it is a string in
|
||
the format <code class="docutils literal notranslate"><span class="pre">UTC±HH:MM</span></code>, where ± is the sign of <code class="docutils literal notranslate"><span class="pre">offset</span></code>, HH and MM are
|
||
two digits of <code class="docutils literal notranslate"><span class="pre">offset.hours</span></code> and <code class="docutils literal notranslate"><span class="pre">offset.minutes</span></code> respectively.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Name generated from <code class="docutils literal notranslate"><span class="pre">offset=timedelta(0)</span></code> is now plain <code class="docutils literal notranslate"><span class="pre">'UTC'</span></code>, not
|
||
<code class="docutils literal notranslate"><span class="pre">'UTC+00:00'</span></code>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.timezone.dst">
|
||
<span class="sig-prename descclassname"><span class="pre">timezone.</span></span><span class="sig-name descname"><span class="pre">dst</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dt</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.timezone.dst" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Always returns <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="datetime.timezone.fromutc">
|
||
<span class="sig-prename descclassname"><span class="pre">timezone.</span></span><span class="sig-name descname"><span class="pre">fromutc</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dt</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#datetime.timezone.fromutc" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">dt</span> <span class="pre">+</span> <span class="pre">offset</span></code>. The <em>dt</em> argument must be an aware
|
||
<a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> instance, with <code class="docutils literal notranslate"><span class="pre">tzinfo</span></code> set to <code class="docutils literal notranslate"><span class="pre">self</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<p>Class attributes:</p>
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="datetime.timezone.utc">
|
||
<span class="sig-prename descclassname"><span class="pre">timezone.</span></span><span class="sig-name descname"><span class="pre">utc</span></span><a class="headerlink" href="#datetime.timezone.utc" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The UTC time zone, <code class="docutils literal notranslate"><span class="pre">timezone(timedelta(0))</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="strftime-and-strptime-behavior">
|
||
<span id="strftime-strptime-behavior"></span><span id="index-0"></span><h2><a class="reference internal" href="#datetime.datetime.strftime" title="datetime.datetime.strftime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strftime()</span></code></a> and <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strptime()</span></code></a> Behavior<a class="headerlink" href="#strftime-and-strptime-behavior" title="Link to this heading">¶</a></h2>
|
||
<p><a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a>, <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a>, and <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a> objects all support a
|
||
<code class="docutils literal notranslate"><span class="pre">strftime(format)</span></code> method, to create a string representing the time under the
|
||
control of an explicit format string.</p>
|
||
<p>Conversely, the <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">datetime.strptime()</span></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"><span class="pre">datetime</span></code></a> object from a string representing a date and time and a
|
||
corresponding format string.</p>
|
||
<p>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"><span class="pre">strftime()</span></code></a>
|
||
versus <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strptime()</span></code></a>:</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"></th>
|
||
<th class="head"><p><code class="docutils literal notranslate"><span class="pre">strftime</span></code></p></th>
|
||
<th class="head"><p><code class="docutils literal notranslate"><span class="pre">strptime</span></code></p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p>Usage</p></td>
|
||
<td><p>Convert object to a string according to a given format</p></td>
|
||
<td><p>Parse a string into a <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> object given a corresponding format</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>Type of method</p></td>
|
||
<td><p>Instance method</p></td>
|
||
<td><p>Class method</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>Method of</p></td>
|
||
<td><p><a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a>; <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a>; <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a></p></td>
|
||
<td><p><a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>Signature</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">strftime(format)</span></code></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">strptime(date_string,</span> <span class="pre">format)</span></code></p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<blockquote>
|
||
<div></div></blockquote>
|
||
<section id="strftime-and-strptime-format-codes">
|
||
<span id="format-codes"></span><h3><a class="reference internal" href="#datetime.datetime.strftime" title="datetime.datetime.strftime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strftime()</span></code></a> and <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strptime()</span></code></a> Format Codes<a class="headerlink" href="#strftime-and-strptime-format-codes" title="Link to this heading">¶</a></h3>
|
||
<p>These methods accept format codes that can be used to parse and format dates:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">strptime</span><span class="p">(</span><span class="s1">'31/01/22 23:59:59.999999'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'</span><span class="si">%d</span><span class="s1">/%m/%y %H:%M:%S.</span><span class="si">%f</span><span class="s1">'</span><span class="p">)</span>
|
||
<span class="go">datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)</span>
|
||
<span class="gp">>>> </span><span class="n">_</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s1">'</span><span class="si">%a</span><span class="s1"> </span><span class="si">%d</span><span class="s1"> %b %Y, %I:%M%p'</span><span class="p">)</span>
|
||
<span class="go">'Mon 31 Jan 2022, 11:59PM'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>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.</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Directive</p></th>
|
||
<th class="head"><p>Meaning</p></th>
|
||
<th class="head"><p>Example</p></th>
|
||
<th class="head"><p>Notes</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">%a</span></code></p></td>
|
||
<td><p>Weekday as locale’s
|
||
abbreviated name.</p></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><p>(1)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">%A</span></code></p></td>
|
||
<td><p>Weekday as locale’s full name.</p></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><p>(1)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">%w</span></code></p></td>
|
||
<td><p>Weekday as a decimal number,
|
||
where 0 is Sunday and 6 is
|
||
Saturday.</p></td>
|
||
<td><p>0, 1, …, 6</p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">%d</span></code></p></td>
|
||
<td><p>Day of the month as a
|
||
zero-padded decimal number.</p></td>
|
||
<td><p>01, 02, …, 31</p></td>
|
||
<td><p>(9)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">%b</span></code></p></td>
|
||
<td><p>Month as locale’s abbreviated
|
||
name.</p></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><p>(1)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">%B</span></code></p></td>
|
||
<td><p>Month as locale’s full name.</p></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><p>(1)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">%m</span></code></p></td>
|
||
<td><p>Month as a zero-padded
|
||
decimal number.</p></td>
|
||
<td><p>01, 02, …, 12</p></td>
|
||
<td><p>(9)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">%y</span></code></p></td>
|
||
<td><p>Year without century as a
|
||
zero-padded decimal number.</p></td>
|
||
<td><p>00, 01, …, 99</p></td>
|
||
<td><p>(9)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">%Y</span></code></p></td>
|
||
<td><p>Year with century as a decimal
|
||
number.</p></td>
|
||
<td><p>0001, 0002, …, 2013,
|
||
2014, …, 9998, 9999</p></td>
|
||
<td><p>(2)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">%H</span></code></p></td>
|
||
<td><p>Hour (24-hour clock) as a
|
||
zero-padded decimal number.</p></td>
|
||
<td><p>00, 01, …, 23</p></td>
|
||
<td><p>(9)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">%I</span></code></p></td>
|
||
<td><p>Hour (12-hour clock) as a
|
||
zero-padded decimal number.</p></td>
|
||
<td><p>01, 02, …, 12</p></td>
|
||
<td><p>(9)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">%p</span></code></p></td>
|
||
<td><p>Locale’s equivalent of either
|
||
AM or PM.</p></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><p>(1),
|
||
(3)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">%M</span></code></p></td>
|
||
<td><p>Minute as a zero-padded
|
||
decimal number.</p></td>
|
||
<td><p>00, 01, …, 59</p></td>
|
||
<td><p>(9)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">%S</span></code></p></td>
|
||
<td><p>Second as a zero-padded
|
||
decimal number.</p></td>
|
||
<td><p>00, 01, …, 59</p></td>
|
||
<td><p>(4),
|
||
(9)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">%f</span></code></p></td>
|
||
<td><p>Microsecond as a decimal
|
||
number, zero-padded to 6
|
||
digits.</p></td>
|
||
<td><p>000000, 000001, …,
|
||
999999</p></td>
|
||
<td><p>(5)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">%z</span></code></p></td>
|
||
<td><p>UTC offset in the form
|
||
<code class="docutils literal notranslate"><span class="pre">±HHMM[SS[.ffffff]]</span></code> (empty
|
||
string if the object is
|
||
naive).</p></td>
|
||
<td><p>(empty), +0000,
|
||
-0400, +1030,
|
||
+063415,
|
||
-030712.345216</p></td>
|
||
<td><p>(6)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">%Z</span></code></p></td>
|
||
<td><p>Time zone name (empty string
|
||
if the object is naive).</p></td>
|
||
<td><p>(empty), UTC, GMT</p></td>
|
||
<td><p>(6)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">%j</span></code></p></td>
|
||
<td><p>Day of the year as a
|
||
zero-padded decimal number.</p></td>
|
||
<td><p>001, 002, …, 366</p></td>
|
||
<td><p>(9)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">%U</span></code></p></td>
|
||
<td><p>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.</p></td>
|
||
<td><p>00, 01, …, 53</p></td>
|
||
<td><p>(7),
|
||
(9)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">%W</span></code></p></td>
|
||
<td><p>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.</p></td>
|
||
<td><p>00, 01, …, 53</p></td>
|
||
<td><p>(7),
|
||
(9)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">%c</span></code></p></td>
|
||
<td><p>Locale’s appropriate date and
|
||
time representation.</p></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><p>(1)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">%x</span></code></p></td>
|
||
<td><p>Locale’s appropriate date
|
||
representation.</p></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><p>(1)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">%X</span></code></p></td>
|
||
<td><p>Locale’s appropriate time
|
||
representation.</p></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><p>(1)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">%%</span></code></p></td>
|
||
<td><p>A literal <code class="docutils literal notranslate"><span class="pre">'%'</span></code> character.</p></td>
|
||
<td><p>%</p></td>
|
||
<td></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Several additional directives not required by the C89 standard are included for
|
||
convenience. These parameters all correspond to ISO 8601 date values.</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Directive</p></th>
|
||
<th class="head"><p>Meaning</p></th>
|
||
<th class="head"><p>Example</p></th>
|
||
<th class="head"><p>Notes</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">%G</span></code></p></td>
|
||
<td><p>ISO 8601 year with century
|
||
representing the year that
|
||
contains the greater part of
|
||
the ISO week (<code class="docutils literal notranslate"><span class="pre">%V</span></code>).</p></td>
|
||
<td><p>0001, 0002, …, 2013,
|
||
2014, …, 9998, 9999</p></td>
|
||
<td><p>(8)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">%u</span></code></p></td>
|
||
<td><p>ISO 8601 weekday as a decimal
|
||
number where 1 is Monday.</p></td>
|
||
<td><p>1, 2, …, 7</p></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">%V</span></code></p></td>
|
||
<td><p>ISO 8601 week as a decimal
|
||
number with Monday as
|
||
the first day of the week.
|
||
Week 01 is the week containing
|
||
Jan 4.</p></td>
|
||
<td><p>01, 02, …, 53</p></td>
|
||
<td><p>(8),
|
||
(9)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">%:z</span></code></p></td>
|
||
<td><p>UTC offset in the form
|
||
<code class="docutils literal notranslate"><span class="pre">±HH:MM[:SS[.ffffff]]</span></code>
|
||
(empty string if the object is
|
||
naive).</p></td>
|
||
<td><p>(empty), +00:00,
|
||
-04:00, +10:30,
|
||
+06:34:15,
|
||
-03:07:12.345216</p></td>
|
||
<td><p>(6)</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>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"><span class="pre">strftime()</span></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"><span class="pre">strptime()</span></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"><span class="pre">ValueError</span></code></a>.</p>
|
||
<p>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"><span class="pre">strftime()</span></code> function, and platform
|
||
variations are common. To see the full set of format codes supported on your
|
||
platform, consult the <em class="manpage"><a class="manpage reference external" href="https://manpages.debian.org/strftime(3)">strftime(3)</a></em> documentation. There are also
|
||
differences between platforms in handling of unsupported format specifiers.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.6: </span><code class="docutils literal notranslate"><span class="pre">%G</span></code>, <code class="docutils literal notranslate"><span class="pre">%u</span></code> and <code class="docutils literal notranslate"><span class="pre">%V</span></code> were added.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.12: </span><code class="docutils literal notranslate"><span class="pre">%:z</span></code> was added.</p>
|
||
</div>
|
||
</section>
|
||
<section id="technical-detail">
|
||
<h3>Technical Detail<a class="headerlink" href="#technical-detail" title="Link to this heading">¶</a></h3>
|
||
<p>Broadly speaking, <code class="docutils literal notranslate"><span class="pre">d.strftime(fmt)</span></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"><span class="pre">time</span></code></a> module’s
|
||
<code class="docutils literal notranslate"><span class="pre">time.strftime(fmt,</span> <span class="pre">d.timetuple())</span></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"><span class="pre">timetuple()</span></code></a> method.</p>
|
||
<p>For the <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">datetime.strptime()</span></code></a> class method, the default value is
|
||
<code class="docutils literal notranslate"><span class="pre">1900-01-01T00:00:00.000</span></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"><span class="fn-bracket">[</span>4<span class="fn-bracket">]</span></a></p>
|
||
<p>Using <code class="docutils literal notranslate"><span class="pre">datetime.strptime(date_string,</span> <span class="pre">format)</span></code> is equivalent to:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">datetime</span><span class="p">(</span><span class="o">*</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">strptime</span><span class="p">(</span><span class="n">date_string</span><span class="p">,</span> <span class="nb">format</span><span class="p">)[</span><span class="mi">0</span><span class="p">:</span><span class="mi">6</span><span class="p">]))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>except when the format includes sub-second components or time zone offset
|
||
information, which are supported in <code class="docutils literal notranslate"><span class="pre">datetime.strptime</span></code> but are discarded by
|
||
<code class="docutils literal notranslate"><span class="pre">time.strptime</span></code>.</p>
|
||
<p>For <a class="reference internal" href="#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></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"><span class="pre">time</span></code> objects have no such values. If they’re used anyway,
|
||
1900 is substituted for the year, and 1 for the month and day.</p>
|
||
<p>For <a class="reference internal" href="#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></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"><span class="pre">date</span></code></a> objects have no such
|
||
values. If they’re used anyway, 0 is substituted for them.</p>
|
||
<p>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"><span class="pre">strftime</span></code> may raise <a class="reference internal" href="exceptions.html#UnicodeError" title="UnicodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeError</span></code></a> or return
|
||
an empty string instead.</p>
|
||
<p>Notes:</p>
|
||
<ol class="arabic">
|
||
<li><p>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.</p></li>
|
||
<li><p>The <a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strptime()</span></code></a> method can parse years in the full [1, 9999] range, but
|
||
years < 1000 must be zero-filled to 4-digit width.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>In previous versions, <a class="reference internal" href="#datetime.datetime.strftime" title="datetime.datetime.strftime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strftime()</span></code></a> method was restricted to
|
||
years >= 1900.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>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"><span class="pre">strftime()</span></code></a> method was restricted to
|
||
years >= 1000.</p>
|
||
</div>
|
||
</li>
|
||
<li><p>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"><span class="pre">strptime()</span></code></a> method, the <code class="docutils literal notranslate"><span class="pre">%p</span></code> directive only affects
|
||
the output hour field if the <code class="docutils literal notranslate"><span class="pre">%I</span></code> directive is used to parse the hour.</p></li>
|
||
<li><p>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"><span class="pre">time</span></code></a> module, the <code class="xref py py-mod docutils literal notranslate"><span class="pre">datetime</span></code> module does not support
|
||
leap seconds.</p></li>
|
||
<li><p>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"><span class="pre">strptime()</span></code></a> method, the <code class="docutils literal notranslate"><span class="pre">%f</span></code> directive
|
||
accepts from one to six digits and zero pads on the right. <code class="docutils literal notranslate"><span class="pre">%f</span></code> is
|
||
an extension to the set of format characters in the C standard (but
|
||
implemented separately in datetime objects, and therefore always
|
||
available).</p></li>
|
||
<li><p>For a naive object, the <code class="docutils literal notranslate"><span class="pre">%z</span></code>, <code class="docutils literal notranslate"><span class="pre">%:z</span></code> and <code class="docutils literal notranslate"><span class="pre">%Z</span></code> format codes are replaced
|
||
by empty strings.</p>
|
||
<p>For an aware object:</p>
|
||
<dl class="simple">
|
||
<dt><code class="docutils literal notranslate"><span class="pre">%z</span></code></dt><dd><p><a class="reference internal" href="#datetime.datetime.utcoffset" title="datetime.datetime.utcoffset"><code class="xref py py-meth docutils literal notranslate"><span class="pre">utcoffset()</span></code></a> is transformed into a string of the form
|
||
<code class="docutils literal notranslate"><span class="pre">±HHMM[SS[.ffffff]]</span></code>, where <code class="docutils literal notranslate"><span class="pre">HH</span></code> is a 2-digit string giving the number
|
||
of UTC offset hours, <code class="docutils literal notranslate"><span class="pre">MM</span></code> is a 2-digit string giving the number of UTC
|
||
offset minutes, <code class="docutils literal notranslate"><span class="pre">SS</span></code> is a 2-digit string giving the number of UTC offset
|
||
seconds and <code class="docutils literal notranslate"><span class="pre">ffffff</span></code> is a 6-digit string giving the number of UTC
|
||
offset microseconds. The <code class="docutils literal notranslate"><span class="pre">ffffff</span></code> part is omitted when the offset is a
|
||
whole number of seconds and both the <code class="docutils literal notranslate"><span class="pre">ffffff</span></code> and the <code class="docutils literal notranslate"><span class="pre">SS</span></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"><span class="pre">utcoffset()</span></code></a> returns <code class="docutils literal notranslate"><span class="pre">timedelta(hours=-3,</span> <span class="pre">minutes=-30)</span></code>, <code class="docutils literal notranslate"><span class="pre">%z</span></code> is
|
||
replaced with the string <code class="docutils literal notranslate"><span class="pre">'-0330'</span></code>.</p>
|
||
</dd>
|
||
</dl>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The UTC offset is not restricted to a whole number of minutes.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>When the <code class="docutils literal notranslate"><span class="pre">%z</span></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"><span class="pre">strptime()</span></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"><span class="pre">'+01:00:00'</span></code> will be parsed as an offset of one hour.
|
||
In addition, providing <code class="docutils literal notranslate"><span class="pre">'Z'</span></code> is identical to <code class="docutils literal notranslate"><span class="pre">'+00:00'</span></code>.</p>
|
||
</div>
|
||
<dl>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">%:z</span></code></dt><dd><p>Behaves exactly as <code class="docutils literal notranslate"><span class="pre">%z</span></code>, but has a colon separator added between
|
||
hours, minutes and seconds.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">%Z</span></code></dt><dd><p>In <a class="reference internal" href="#datetime.datetime.strftime" title="datetime.datetime.strftime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strftime()</span></code></a>, <code class="docutils literal notranslate"><span class="pre">%Z</span></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"><span class="pre">tzname()</span></code></a> returns <code class="docutils literal notranslate"><span class="pre">None</span></code>; otherwise <code class="docutils literal notranslate"><span class="pre">%Z</span></code> is replaced by the
|
||
returned value, which must be a string.</p>
|
||
<p><a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strptime()</span></code></a> only accepts certain values for <code class="docutils literal notranslate"><span class="pre">%Z</span></code>:</p>
|
||
<ol class="arabic simple">
|
||
<li><p>any value in <code class="docutils literal notranslate"><span class="pre">time.tzname</span></code> for your machine’s locale</p></li>
|
||
<li><p>the hard-coded values <code class="docutils literal notranslate"><span class="pre">UTC</span></code> and <code class="docutils literal notranslate"><span class="pre">GMT</span></code></p></li>
|
||
</ol>
|
||
<p>So someone living in Japan may have <code class="docutils literal notranslate"><span class="pre">JST</span></code>, <code class="docutils literal notranslate"><span class="pre">UTC</span></code>, and <code class="docutils literal notranslate"><span class="pre">GMT</span></code> as
|
||
valid values, but probably not <code class="docutils literal notranslate"><span class="pre">EST</span></code>. It will raise <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> for
|
||
invalid values.</p>
|
||
</dd>
|
||
</dl>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>When the <code class="docutils literal notranslate"><span class="pre">%z</span></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"><span class="pre">strptime()</span></code></a> method, an
|
||
aware <a class="reference internal" href="#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a> object will be produced. The <code class="docutils literal notranslate"><span class="pre">tzinfo</span></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"><span class="pre">timezone</span></code></a> instance.</p>
|
||
</div>
|
||
</li>
|
||
<li><p>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"><span class="pre">strptime()</span></code></a> method, <code class="docutils literal notranslate"><span class="pre">%U</span></code> and <code class="docutils literal notranslate"><span class="pre">%W</span></code> are only used
|
||
in calculations when the day of the week and the calendar year (<code class="docutils literal notranslate"><span class="pre">%Y</span></code>)
|
||
are specified.</p></li>
|
||
<li><p>Similar to <code class="docutils literal notranslate"><span class="pre">%U</span></code> and <code class="docutils literal notranslate"><span class="pre">%W</span></code>, <code class="docutils literal notranslate"><span class="pre">%V</span></code> is only used in calculations when the
|
||
day of the week and the ISO year (<code class="docutils literal notranslate"><span class="pre">%G</span></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"><span class="pre">strptime()</span></code></a> format string. Also note that <code class="docutils literal notranslate"><span class="pre">%G</span></code> and <code class="docutils literal notranslate"><span class="pre">%Y</span></code> are not
|
||
interchangeable.</p></li>
|
||
<li><p>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"><span class="pre">strptime()</span></code></a> method, the leading zero is optional
|
||
for formats <code class="docutils literal notranslate"><span class="pre">%d</span></code>, <code class="docutils literal notranslate"><span class="pre">%m</span></code>, <code class="docutils literal notranslate"><span class="pre">%H</span></code>, <code class="docutils literal notranslate"><span class="pre">%I</span></code>, <code class="docutils literal notranslate"><span class="pre">%M</span></code>, <code class="docutils literal notranslate"><span class="pre">%S</span></code>, <code class="docutils literal notranslate"><span class="pre">%j</span></code>, <code class="docutils literal notranslate"><span class="pre">%U</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">%W</span></code>, and <code class="docutils literal notranslate"><span class="pre">%V</span></code>. Format <code class="docutils literal notranslate"><span class="pre">%y</span></code> does require a leading zero.</p></li>
|
||
<li><p>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"><span class="pre">strptime()</span></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…</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">month_day</span> <span class="o">=</span> <span class="s2">"02/29"</span>
|
||
<span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">strptime</span><span class="p">(</span><span class="sa">f</span><span class="s2">"</span><span class="si">{</span><span class="n">month_day</span><span class="si">}</span><span class="s2">;1984"</span><span class="p">,</span> <span class="s2">"%m/</span><span class="si">%d</span><span class="s2">;%Y"</span><span class="p">)</span> <span class="c1"># No leap year bug.</span>
|
||
<span class="go">datetime.datetime(1984, 2, 29, 0, 0)</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="deprecated-removed">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.13, will be removed in version 3.15: </span><a class="reference internal" href="#datetime.datetime.strptime" title="datetime.datetime.strptime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strptime()</span></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"><span class="pre">DeprecationWarning</span></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>.</p>
|
||
</div>
|
||
</li>
|
||
</ol>
|
||
<p class="rubric">Footnotes</p>
|
||
<aside class="footnote-list brackets">
|
||
<aside class="footnote brackets" id="id5" role="doc-footnote">
|
||
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">1</a><span class="fn-bracket">]</span></span>
|
||
<p>If, that is, we ignore the effects of Relativity</p>
|
||
</aside>
|
||
<aside class="footnote brackets" id="id6" role="doc-footnote">
|
||
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id2">2</a><span class="fn-bracket">]</span></span>
|
||
<p>This matches the definition of the “proleptic Gregorian” calendar in
|
||
Dershowitz and Reingold’s book <em>Calendrical Calculations</em>,
|
||
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.</p>
|
||
</aside>
|
||
<aside class="footnote brackets" id="id7" role="doc-footnote">
|
||
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id3">3</a><span class="fn-bracket">]</span></span>
|
||
<p>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.</p>
|
||
</aside>
|
||
<aside class="footnote brackets" id="id8" role="doc-footnote">
|
||
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id4">4</a><span class="fn-bracket">]</span></span>
|
||
<p>Passing <code class="docutils literal notranslate"><span class="pre">datetime.strptime('Feb</span> <span class="pre">29',</span> <span class="pre">'%b</span> <span class="pre">%d')</span></code> will fail since 1900 is not a leap year.</p>
|
||
</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"><span class="pre">datetime</span></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></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"><span class="pre">timedelta</span></code> Objects</a><ul>
|
||
<li><a class="reference internal" href="#examples-of-usage-timedelta">Examples of usage: <code class="xref py py-class docutils literal notranslate"><span class="pre">timedelta</span></code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#date-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code> Objects</a><ul>
|
||
<li><a class="reference internal" href="#examples-of-usage-date">Examples of Usage: <code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#datetime-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code> Objects</a><ul>
|
||
<li><a class="reference internal" href="#examples-of-usage-datetime">Examples of Usage: <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#time-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code> Objects</a><ul>
|
||
<li><a class="reference internal" href="#examples-of-usage-time">Examples of Usage: <code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#tzinfo-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">tzinfo</span></code> Objects</a></li>
|
||
<li><a class="reference internal" href="#timezone-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">timezone</span></code> Objects</a></li>
|
||
<li><a class="reference internal" href="#strftime-and-strptime-behavior"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strftime()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">strptime()</span></code> Behavior</a><ul>
|
||
<li><a class="reference internal" href="#strftime-and-strptime-format-codes"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strftime()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">strptime()</span></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>
|
||
<p class="topless"><a href="datatypes.html"
|
||
title="previous chapter">Data Types</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="zoneinfo.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">zoneinfo</span></code> — IANA time zone support</a></p>
|
||
</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">
|
||
<span>«</span>
|
||
</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.3 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"><span class="pre">datetime</span></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-2025, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
See <a href="/license.html">History and License</a> for more information.<br />
|
||
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
Last updated on Apr 08, 2025 (14:33 UTC).
|
||
|
||
<a href="/bugs.html">Found a bug</a>?
|
||
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |