<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>datetime – Date/time value manipulation — Python Module of the Week</title>
<link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.132',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="top" title="Python Module of the Week" href="../index.html" />
<link rel="up" title="Data Types" href="../data_types.html" />
<link rel="next" title="calendar – Work with dates" href="../calendar/index.html" />
<link rel="prev" title="array – Sequence of fixed-type data" href="../array/index.html" />
</head>
<body>
<div class="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="../calendar/index.html" title="calendar – Work with dates"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../array/index.html" title="array – Sequence of fixed-type data"
accesskey="P">previous</a> |</li>
<li><a href="../contents.html">PyMOTW</a> »</li>
<li><a href="../data_types.html" accesskey="U">Data Types</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">datetime – Date/time value manipulation</a><ul>
<li><a class="reference internal" href="#times">Times</a></li>
<li><a class="reference internal" href="#dates">Dates</a></li>
<li><a class="reference internal" href="#timedeltas">timedeltas</a></li>
<li><a class="reference internal" href="#date-arithmetic">Date Arithmetic</a></li>
<li><a class="reference internal" href="#comparing-values">Comparing Values</a></li>
<li><a class="reference internal" href="#combining-dates-and-times">Combining Dates and Times</a></li>
<li><a class="reference internal" href="#formatting-and-parsing">Formatting and Parsing</a></li>
<li><a class="reference internal" href="#time-zones">Time Zones</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="../array/index.html"
title="previous chapter">array – Sequence of fixed-type data</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../calendar/index.html"
title="next chapter">calendar – Work with dates</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/datetime/index.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-datetime">
<span id="datetime-date-time-value-manipulation"></span><h1>datetime – Date/time value manipulation<a class="headerlink" href="#module-datetime" title="Permalink to this headline">¶</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Purpose:</th><td class="field-body">The datetime module includes functions and classes for doing date and time parsing, formatting, and arithmetic.</td>
</tr>
<tr class="field"><th class="field-name">Python Version:</th><td class="field-body">2.3 and later</td>
</tr>
</tbody>
</table>
<p><a class="reference internal" href="#module-datetime" title="datetime: Date/time value manipulation."><tt class="xref py py-mod docutils literal"><span class="pre">datetime</span></tt></a> contains functions and classes for working with dates
and times, separatley and together.</p>
<div class="section" id="times">
<h2>Times<a class="headerlink" href="#times" title="Permalink to this headline">¶</a></h2>
<p>Time values are represented with the <a class="reference internal" href="../time/index.html#module-time" title="time: Functions for manipulating clock time"><tt class="xref py py-class docutils literal"><span class="pre">time</span></tt></a> class. Times have
attributes for hour, minute, second, and microsecond. They can also
include time zone information. The arguments to initialize a
<a class="reference internal" href="../time/index.html#module-time" title="time: Functions for manipulating clock time"><tt class="xref py py-class docutils literal"><span class="pre">time</span></tt></a> instance are optional, but the default of <tt class="docutils literal"><span class="pre">0</span></tt> is
unlikely to be what you want.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">datetime</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">time</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="mi">3</span><span class="p">)</span>
<span class="k">print</span> <span class="n">t</span>
<span class="k">print</span> <span class="s">'hour :'</span><span class="p">,</span> <span class="n">t</span><span class="o">.</span><span class="n">hour</span>
<span class="k">print</span> <span class="s">'minute:'</span><span class="p">,</span> <span class="n">t</span><span class="o">.</span><span class="n">minute</span>
<span class="k">print</span> <span class="s">'second:'</span><span class="p">,</span> <span class="n">t</span><span class="o">.</span><span class="n">second</span>
<span class="k">print</span> <span class="s">'microsecond:'</span><span class="p">,</span> <span class="n">t</span><span class="o">.</span><span class="n">microsecond</span>
<span class="k">print</span> <span class="s">'tzinfo:'</span><span class="p">,</span> <span class="n">t</span><span class="o">.</span><span class="n">tzinfo</span>
</pre></div>
</div>
<div class="highlight-python"><pre>$ python datetime_time.py
01:02:03
hour : 1
minute: 2
second: 3
microsecond: 0
tzinfo: None</pre>
</div>
<p>A time instance only holds values of time, and not a date associated
with the time.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">datetime</span>
<span class="k">print</span> <span class="s">'Earliest :'</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">time</span><span class="o">.</span><span class="n">min</span>
<span class="k">print</span> <span class="s">'Latest :'</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">time</span><span class="o">.</span><span class="n">max</span>
<span class="k">print</span> <span class="s">'Resolution:'</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">time</span><span class="o">.</span><span class="n">resolution</span>
</pre></div>
</div>
<p>The <em>min</em> and <em>max</em> class attributes reflect the valid range of
times in a single day.</p>
<div class="highlight-python"><pre>$ python datetime_time_minmax.py
Earliest : 00:00:00
Latest : 23:59:59.999999
Resolution: 0:00:00.000001</pre>
</div>
<p>The resolution for time is limited to whole microseconds.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">datetime</span>
<span class="k">for</span> <span class="n">m</span> <span class="ow">in</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="mf">0.1</span><span class="p">,</span> <span class="mf">0.6</span> <span class="p">]:</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">print</span> <span class="s">'</span><span class="si">%02.1f</span><span class="s"> :'</span> <span class="o">%</span> <span class="n">m</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">time</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">microsecond</span><span class="o">=</span><span class="n">m</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">TypeError</span><span class="p">,</span> <span class="n">err</span><span class="p">:</span>
<span class="k">print</span> <span class="s">'ERROR:'</span><span class="p">,</span> <span class="n">err</span>
</pre></div>
</div>
<p>In fact, using floating point numbers for the microsecond argument
generates a <a class="reference internal" href="../exceptions/index.html#exceptions-typeerror"><em>TypeError</em></a>.</p>
<div class="highlight-python"><pre>$ python datetime_time_resolution.py
1.0 : 00:00:00.000001
0.0 : 00:00:00
0.1 : ERROR: integer argument expected, got float
0.6 : ERROR: integer argument expected, got float</pre>
</div>
</div>
<div class="section" id="dates">
<h2>Dates<a class="headerlink" href="#dates" title="Permalink to this headline">¶</a></h2>
<p>Calendar date values are represented with the <tt class="xref py py-class docutils literal"><span class="pre">date</span></tt>
class. Instances have attributes for year, month, and day. It is easy
to create a date representing today’s date using the <tt class="xref py py-func docutils literal"><span class="pre">today()</span></tt>
class method.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">datetime</span>
<span class="n">today</span> <span class="o">=</span> <span class="n">datetime</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="k">print</span> <span class="n">today</span>
<span class="k">print</span> <span class="s">'ctime:'</span><span class="p">,</span> <span class="n">today</span><span class="o">.</span><span class="n">ctime</span><span class="p">()</span>
<span class="k">print</span> <span class="s">'tuple:'</span><span class="p">,</span> <span class="n">today</span><span class="o">.</span><span class="n">timetuple</span><span class="p">()</span>
<span class="k">print</span> <span class="s">'ordinal:'</span><span class="p">,</span> <span class="n">today</span><span class="o">.</span><span class="n">toordinal</span><span class="p">()</span>
<span class="k">print</span> <span class="s">'Year:'</span><span class="p">,</span> <span class="n">today</span><span class="o">.</span><span class="n">year</span>
<span class="k">print</span> <span class="s">'Mon :'</span><span class="p">,</span> <span class="n">today</span><span class="o">.</span><span class="n">month</span>
<span class="k">print</span> <span class="s">'Day :'</span><span class="p">,</span> <span class="n">today</span><span class="o">.</span><span class="n">day</span>
</pre></div>
</div>
<p>This example prints the current date in several formats:</p>
<div class="highlight-python"><pre>$ python datetime_date.py
2010-10-24
ctime: Sun Oct 24 00:00:00 2010
tuple: time.struct_time(tm_year=2010, tm_mon=10, tm_mday=24, tm_hour=0, tm_min=0, tm_sec=0, tm_wday=6, tm_yday=297, tm_isdst=-1)
ordinal: 734069
Year: 2010
Mon : 10
Day : 24</pre>
</div>
<p>There are also class methods for creating instances from integers
(using proleptic Gregorian ordinal values, which starts counting from
Jan. 1 of the year 1) or POSIX timestamp values.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">datetime</span>
<span class="kn">import</span> <span class="nn">time</span>
<span class="n">o</span> <span class="o">=</span> <span class="mi">733114</span>
<span class="k">print</span> <span class="s">'o:'</span><span class="p">,</span> <span class="n">o</span>
<span class="k">print</span> <span class="s">'fromordinal(o):'</span><span class="p">,</span> <span class="n">datetime</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="n">o</span><span class="p">)</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span>
<span class="k">print</span> <span class="s">'t:'</span><span class="p">,</span> <span class="n">t</span>
<span class="k">print</span> <span class="s">'fromtimestamp(t):'</span><span class="p">,</span> <span class="n">datetime</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">t</span><span class="p">)</span>
</pre></div>
</div>
<p>This example illustrates the different value types used by
<tt class="xref py py-func docutils literal"><span class="pre">fromordinal()</span></tt> and <tt class="xref py py-func docutils literal"><span class="pre">fromtimestamp()</span></tt>.</p>
<div class="highlight-python"><pre>$ python datetime_date_fromordinal.py
o: 733114
fromordinal(o): 2008-03-13
t: 1287924807.32
fromtimestamp(t): 2010-10-24</pre>
</div>
<p>As with <a class="reference internal" href="../time/index.html#module-time" title="time: Functions for manipulating clock time"><tt class="xref py py-class docutils literal"><span class="pre">time</span></tt></a>, the range of date values supported can be
determined using the <em>min</em> and <em>max</em> attributes.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">datetime</span>
<span class="k">print</span> <span class="s">'Earliest :'</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">date</span><span class="o">.</span><span class="n">min</span>
<span class="k">print</span> <span class="s">'Latest :'</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">date</span><span class="o">.</span><span class="n">max</span>
<span class="k">print</span> <span class="s">'Resolution:'</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">date</span><span class="o">.</span><span class="n">resolution</span>
</pre></div>
</div>
<p>The resolution for dates is whole days.</p>
<div class="highlight-python"><pre>$ python datetime_date_minmax.py
Earliest : 0001-01-01
Latest : 9999-12-31
Resolution: 1 day, 0:00:00</pre>
</div>
<p>Another way to create new date instances uses the <tt class="xref py py-func docutils literal"><span class="pre">replace()</span></tt>
method of an existing date. For example, you can change the year,
leaving the day and month alone.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">datetime</span>
<span class="n">d1</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">date</span><span class="p">(</span><span class="mi">2008</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">12</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'d1:'</span><span class="p">,</span> <span class="n">d1</span>
<span class="n">d2</span> <span class="o">=</span> <span class="n">d1</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">2009</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'d2:'</span><span class="p">,</span> <span class="n">d2</span>
</pre></div>
</div>
<div class="highlight-python"><pre>$ python datetime_date_replace.py
d1: 2008-03-12
d2: 2009-03-12</pre>
</div>
</div>
<div class="section" id="timedeltas">
<h2>timedeltas<a class="headerlink" href="#timedeltas" title="Permalink to this headline">¶</a></h2>
<p>Using <tt class="xref py py-func docutils literal"><span class="pre">replace()</span></tt> is not the only way to calculate future/past
dates. You can use <a class="reference internal" href="#module-datetime" title="datetime: Date/time value manipulation."><tt class="xref py py-mod docutils literal"><span class="pre">datetime</span></tt></a> to perform basic arithmetic on date
values via the <tt class="xref py py-class docutils literal"><span class="pre">timedelta</span></tt> class. Subtracting dates produces a
<tt class="xref py py-class docutils literal"><span class="pre">timedelta</span></tt>, and a <tt class="xref py py-class docutils literal"><span class="pre">timedelta</span></tt> can be added or
subtracted from a date to produce another date. The internal values
for a <tt class="xref py py-class docutils literal"><span class="pre">timedelta</span></tt> are stored in days, seconds, and
microseconds.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">datetime</span>
<span class="k">print</span> <span class="s">"microseconds:"</span><span class="p">,</span> <span class="n">datetime</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="k">print</span> <span class="s">"milliseconds:"</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">timedelta</span><span class="p">(</span><span class="n">milliseconds</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="k">print</span> <span class="s">"seconds :"</span><span class="p">,</span> <span class="n">datetime</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="k">print</span> <span class="s">"minutes :"</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">timedelta</span><span class="p">(</span><span class="n">minutes</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="k">print</span> <span class="s">"hours :"</span><span class="p">,</span> <span class="n">datetime</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="k">print</span> <span class="s">"days :"</span><span class="p">,</span> <span class="n">datetime</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">1</span><span class="p">)</span>
<span class="k">print</span> <span class="s">"weeks :"</span><span class="p">,</span> <span class="n">datetime</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">1</span><span class="p">)</span>
</pre></div>
</div>
<p>Intermediate level values passed to the constructor are converted into
days, seconds, and microseconds.</p>
<div class="highlight-python"><pre>$ python datetime_timedelta.py
microseconds: 0:00:00.000001
milliseconds: 0:00:00.001000
seconds : 0:00:01
minutes : 0:01:00
hours : 1:00:00
days : 1 day, 0:00:00
weeks : 7 days, 0:00:00</pre>
</div>
</div>
<div class="section" id="date-arithmetic">
<h2>Date Arithmetic<a class="headerlink" href="#date-arithmetic" title="Permalink to this headline">¶</a></h2>
<p>Date math uses the standard arithmetic operators. This example with
date objects illustrates using <tt class="xref py py-class docutils literal"><span class="pre">timedelta</span></tt> objects to compute
new dates, and subtracting date instances to produce timedeltas
(including a negative delta value).</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">datetime</span>
<span class="n">today</span> <span class="o">=</span> <span class="n">datetime</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="k">print</span> <span class="s">'Today :'</span><span class="p">,</span> <span class="n">today</span>
<span class="n">one_day</span> <span class="o">=</span> <span class="n">datetime</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">1</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'One day :'</span><span class="p">,</span> <span class="n">one_day</span>
<span class="n">yesterday</span> <span class="o">=</span> <span class="n">today</span> <span class="o">-</span> <span class="n">one_day</span>
<span class="k">print</span> <span class="s">'Yesterday:'</span><span class="p">,</span> <span class="n">yesterday</span>
<span class="n">tomorrow</span> <span class="o">=</span> <span class="n">today</span> <span class="o">+</span> <span class="n">one_day</span>
<span class="k">print</span> <span class="s">'Tomorrow :'</span><span class="p">,</span> <span class="n">tomorrow</span>
<span class="k">print</span> <span class="s">'tomorrow - yesterday:'</span><span class="p">,</span> <span class="n">tomorrow</span> <span class="o">-</span> <span class="n">yesterday</span>
<span class="k">print</span> <span class="s">'yesterday - tomorrow:'</span><span class="p">,</span> <span class="n">yesterday</span> <span class="o">-</span> <span class="n">tomorrow</span>
</pre></div>
</div>
<div class="highlight-python"><pre>$ python datetime_date_math.py
Today : 2010-10-24
One day : 1 day, 0:00:00
Yesterday: 2010-10-23
Tomorrow : 2010-10-25
tomorrow - yesterday: 2 days, 0:00:00
yesterday - tomorrow: -2 days, 0:00:00</pre>
</div>
</div>
<div class="section" id="comparing-values">
<h2>Comparing Values<a class="headerlink" href="#comparing-values" title="Permalink to this headline">¶</a></h2>
<p>Both date and time values can be compared using the standard operators
to determine which is earlier or later.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">datetime</span>
<span class="kn">import</span> <span class="nn">time</span>
<span class="k">print</span> <span class="s">'Times:'</span>
<span class="n">t1</span> <span class="o">=</span> <span class="n">datetime</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">55</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">t1:'</span><span class="p">,</span> <span class="n">t1</span>
<span class="n">t2</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">time</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="mi">0</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">t2:'</span><span class="p">,</span> <span class="n">t2</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">t1 < t2:'</span><span class="p">,</span> <span class="n">t1</span> <span class="o"><</span> <span class="n">t2</span>
<span class="k">print</span> <span class="s">'Dates:'</span>
<span class="n">d1</span> <span class="o">=</span> <span class="n">datetime</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="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">d1:'</span><span class="p">,</span> <span class="n">d1</span>
<span class="n">d2</span> <span class="o">=</span> <span class="n">datetime</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="o">+</span> <span class="n">datetime</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">1</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">d2:'</span><span class="p">,</span> <span class="n">d2</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\t</span><span class="s">d1 > d2:'</span><span class="p">,</span> <span class="n">d1</span> <span class="o">></span> <span class="n">d2</span>
</pre></div>
</div>
<div class="highlight-python"><pre>$ python datetime_comparing.py
Times:
t1: 12:55:00
t2: 13:05:00
t1 < t2: True
Dates:
d1: 2010-10-24
d2: 2010-10-25
d1 > d2: False</pre>
</div>
</div>
<div class="section" id="combining-dates-and-times">
<h2>Combining Dates and Times<a class="headerlink" href="#combining-dates-and-times" title="Permalink to this headline">¶</a></h2>
<p>Use the <a class="reference internal" href="#module-datetime" title="datetime: Date/time value manipulation."><tt class="xref py py-class docutils literal"><span class="pre">datetime</span></tt></a> class to hold values consisting of both date
and time components. As with <tt class="xref py py-class docutils literal"><span class="pre">date</span></tt>, there are several
convenient class methods to make creating <a class="reference internal" href="#module-datetime" title="datetime: Date/time value manipulation."><tt class="xref py py-class docutils literal"><span class="pre">datetime</span></tt></a> instances
from other common values.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">datetime</span>
<span class="k">print</span> <span class="s">'Now :'</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span>
<span class="k">print</span> <span class="s">'Today :'</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">today</span><span class="p">()</span>
<span class="k">print</span> <span class="s">'UTC Now:'</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">()</span>
<span class="n">d</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span>
<span class="k">for</span> <span class="n">attr</span> <span class="ow">in</span> <span class="p">[</span> <span class="s">'year'</span><span class="p">,</span> <span class="s">'month'</span><span class="p">,</span> <span class="s">'day'</span><span class="p">,</span> <span class="s">'hour'</span><span class="p">,</span> <span class="s">'minute'</span><span class="p">,</span> <span class="s">'second'</span><span class="p">,</span> <span class="s">'microsecond'</span><span class="p">]:</span>
<span class="k">print</span> <span class="n">attr</span><span class="p">,</span> <span class="s">':'</span><span class="p">,</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">d</span><span class="p">,</span> <span class="n">attr</span><span class="p">)</span>
</pre></div>
</div>
<p>As you might expect, the <a class="reference internal" href="#module-datetime" title="datetime: Date/time value manipulation."><tt class="xref py py-class docutils literal"><span class="pre">datetime</span></tt></a> instance has all of the
attributes of both a date and a time object.</p>
<div class="highlight-python"><pre>$ python datetime_datetime.py
Now : 2010-10-24 08:53:27.554957
Today : 2010-10-24 08:53:27.556047
UTC Now: 2010-10-24 12:53:27.556065
year : 2010
month : 10
day : 24
hour : 8
minute : 53
second : 27
microsecond : 556303</pre>
</div>
<p>Just as with date, datetime provides convenient class methods for
creating new instances. It also includes <tt class="xref py py-func docutils literal"><span class="pre">fromordinal()</span></tt> and
<tt class="xref py py-func docutils literal"><span class="pre">fromtimestamp()</span></tt>. In addition, <tt class="xref py py-func docutils literal"><span class="pre">combine()</span></tt> can be useful
if you already have a date instance and time instance and want to
create a datetime.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">datetime</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">time</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="mi">3</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'t :'</span><span class="p">,</span> <span class="n">t</span>
<span class="n">d</span> <span class="o">=</span> <span class="n">datetime</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="k">print</span> <span class="s">'d :'</span><span class="p">,</span> <span class="n">d</span>
<span class="n">dt</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</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="k">print</span> <span class="s">'dt:'</span><span class="p">,</span> <span class="n">dt</span>
</pre></div>
</div>
<div class="highlight-python"><pre>$ python datetime_datetime_combine.py
t : 01:02:03
d : 2010-10-24
dt: 2010-10-24 01:02:03</pre>
</div>
</div>
<div class="section" id="formatting-and-parsing">
<h2>Formatting and Parsing<a class="headerlink" href="#formatting-and-parsing" title="Permalink to this headline">¶</a></h2>
<p>The default string representation of a datetime object uses the <a class="reference external" href="http://www.iso.org/iso/support/faqs/faqs_widely_used_standards/widely_used_standards_other/date_and_time_format.htm">ISO
8601</a> format (<tt class="docutils literal"><span class="pre">YYYY-MM-DDTHH:MM:SS.mmmmmm</span></tt>). Alternate formats can
be generated using <tt class="xref py py-func docutils literal"><span class="pre">strftime()</span></tt>. Similarly, if your input data
includes timestamp values parsable with <tt class="xref py py-func docutils literal"><span class="pre">time.strptime()</span></tt>, then
<tt class="xref py py-func docutils literal"><span class="pre">datetime.strptime()</span></tt> is a convenient way to convert them to
datetime instances.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">datetime</span>
<span class="n">format</span> <span class="o">=</span> <span class="s">"%a %b </span><span class="si">%d</span><span class="s"> %H:%M:%S %Y"</span>
<span class="n">today</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">today</span><span class="p">()</span>
<span class="k">print</span> <span class="s">'ISO :'</span><span class="p">,</span> <span class="n">today</span>
<span class="n">s</span> <span class="o">=</span> <span class="n">today</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="n">format</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'strftime:'</span><span class="p">,</span> <span class="n">s</span>
<span class="n">d</span> <span class="o">=</span> <span class="n">datetime</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="n">s</span><span class="p">,</span> <span class="n">format</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'strptime:'</span><span class="p">,</span> <span class="n">d</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="n">format</span><span class="p">)</span>
</pre></div>
</div>
<div class="highlight-python"><pre>$ python datetime_datetime_strptime.py
ISO : 2010-10-24 08:53:27.683734
strftime: Sun Oct 24 08:53:27 2010
strptime: Sun Oct 24 08:53:27 2010</pre>
</div>
</div>
<div class="section" id="time-zones">
<h2>Time Zones<a class="headerlink" href="#time-zones" title="Permalink to this headline">¶</a></h2>
<p>Within <a class="reference internal" href="#module-datetime" title="datetime: Date/time value manipulation."><tt class="xref py py-mod docutils literal"><span class="pre">datetime</span></tt></a>, time zones are represented by subclasses of
<tt class="xref py py-class docutils literal"><span class="pre">tzinfo</span></tt>. Since <tt class="xref py py-class docutils literal"><span class="pre">tzinfo</span></tt> is an abstract base class, you
need to define a subclass and provide appropriate implementations for
a few methods to make it useful. Unfortunately, <a class="reference internal" href="#module-datetime" title="datetime: Date/time value manipulation."><tt class="xref py py-mod docutils literal"><span class="pre">datetime</span></tt></a> does
not include any actual implementations ready to be used, although the
documentation does provide a few sample implementations. Refer to the
standard library documentation page for examples using fixed offsets
as well as a DST-aware class and more details about creating your own
class. <a class="reference external" href="http://pytz.sourceforge.net/">pytz</a> is also a good source for time zone implementation
details.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference external" href="http://docs.python.org/lib/module-datetime.html">datetime</a></dt>
<dd>The standard library documentation for this module.</dd>
<dt><a class="reference internal" href="../calendar/index.html#module-calendar" title="calendar: The calendar module implements classes for working with dates to manage year/month/week oriented values."><tt class="xref py py-mod docutils literal"><span class="pre">calendar</span></tt></a></dt>
<dd>The <a class="reference internal" href="../calendar/index.html#module-calendar" title="calendar: The calendar module implements classes for working with dates to manage year/month/week oriented values."><tt class="xref py py-mod docutils literal"><span class="pre">calendar</span></tt></a> module.</dd>
<dt><a class="reference internal" href="../time/index.html#module-time" title="time: Functions for manipulating clock time"><tt class="xref py py-mod docutils literal"><span class="pre">time</span></tt></a></dt>
<dd>The <a class="reference internal" href="../time/index.html#module-time" title="time: Functions for manipulating clock time"><tt class="xref py py-mod docutils literal"><span class="pre">time</span></tt></a> module.</dd>
<dt><a class="reference external" href="http://labix.org/python-dateutil">dateutil</a></dt>
<dd>dateutil from Labix extends the datetime module with additional features.</dd>
<dt><a class="reference external" href="http://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">WikiPedia: Proleptic Gregorian calendar</a></dt>
<dd>A description of the Gregorian calendar system.</dd>
<dt><a class="reference external" href="http://pytz.sourceforge.net/">pytz</a></dt>
<dd>World Time Zone database</dd>
<dt><a class="reference external" href="http://www.iso.org/iso/support/faqs/faqs_widely_used_standards/widely_used_standards_other/date_and_time_format.htm">ISO 8601</a></dt>
<dd>The standard for numeric representation of Dates and Time</dd>
</dl>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="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="../calendar/index.html" title="calendar – Work with dates"
>next</a> |</li>
<li class="right" >
<a href="../array/index.html" title="array – Sequence of fixed-type data"
>previous</a> |</li>
<li><a href="../contents.html">PyMOTW</a> »</li>
<li><a href="../data_types.html" >Data Types</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright Doug Hellmann.
Last updated on Oct 24, 2010.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
<br/><a href="http://creativecommons.org/licenses/by-nc-sa/3.0/us/" rel="license"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-nc-sa/3.0/us/88x31.png"/></a>
</div>
</body>
</html>