<!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="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Datetimes and Timezones — PyMongo 3.7.2 documentation</title>
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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>
<script type="text/javascript" src="../_static/language_data.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Geospatial Indexing Example" href="geo.html" />
<link rel="prev" title="Bulk Write Operations" href="bulk.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<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="geo.html" title="Geospatial Indexing Example"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="bulk.html" title="Bulk Write Operations"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">PyMongo 3.7.2 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Examples</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="datetimes-and-timezones">
<h1>Datetimes and Timezones<a class="headerlink" href="#datetimes-and-timezones" title="Permalink to this headline">¶</a></h1>
<p>These examples show how to handle Python <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.datetime</span></code> objects
correctly in PyMongo.</p>
<div class="section" id="basic-usage">
<h2>Basic Usage<a class="headerlink" href="#basic-usage" title="Permalink to this headline">¶</a></h2>
<p>PyMongo uses <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.datetime</span></code> objects for representing dates and times
in MongoDB documents. Because MongoDB assumes that dates and times are in UTC,
care should be taken to ensure that dates and times written to the database
reflect UTC. For example, the following code stores the current UTC date and
time into MongoDB:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">result</span> <span class="o">=</span> <span class="n">db</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">insert_one</span><span class="p">(</span>
<span class="gp">... </span> <span class="p">{</span><span class="s2">"last_modified"</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>
</pre></div>
</div>
<p>Always use <code class="xref py py-meth docutils literal notranslate"><span class="pre">datetime.datetime.utcnow()</span></code>, which returns the current time in
UTC, instead of <code class="xref py py-meth docutils literal notranslate"><span class="pre">datetime.datetime.now()</span></code>, which returns the current local
time. Avoid doing this:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">result</span> <span class="o">=</span> <span class="n">db</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">insert_one</span><span class="p">(</span>
<span class="gp">... </span> <span class="p">{</span><span class="s2">"last_modified"</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>
</pre></div>
</div>
<p>The value for <cite>last_modified</cite> is very different between these two examples, even
though both documents were stored at around the same local time. This will be
confusing to the application that reads them:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="p">[</span><span class="n">doc</span><span class="p">[</span><span class="s1">'last_modified'</span><span class="p">]</span> <span class="k">for</span> <span class="n">doc</span> <span class="ow">in</span> <span class="n">db</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">find</span><span class="p">()]</span>
<span class="go">[datetime.datetime(2015, 7, 8, 18, 17, 28, 324000),</span>
<span class="go"> datetime.datetime(2015, 7, 8, 11, 17, 42, 911000)]</span>
</pre></div>
</div>
<p><a class="reference internal" href="../api/bson/codec_options.html#bson.codec_options.CodecOptions" title="bson.codec_options.CodecOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">bson.codec_options.CodecOptions</span></code></a> has a <cite>tz_aware</cite> option that enables
“aware” <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.datetime</span></code> objects, i.e., datetimes that know what
timezone they’re in. By default, PyMongo retrieves naive datetimes:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">result</span> <span class="o">=</span> <span class="n">db</span><span class="o">.</span><span class="n">tzdemo</span><span class="o">.</span><span class="n">insert_one</span><span class="p">(</span>
<span class="gp">... </span> <span class="p">{</span><span class="s1">'date'</span><span class="p">:</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2002</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">27</span><span class="p">,</span> <span class="mi">6</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="gp">>>> </span><span class="n">db</span><span class="o">.</span><span class="n">tzdemo</span><span class="o">.</span><span class="n">find_one</span><span class="p">()[</span><span class="s1">'date'</span><span class="p">]</span>
<span class="go">datetime.datetime(2002, 10, 27, 6, 0)</span>
<span class="gp">>>> </span><span class="n">options</span> <span class="o">=</span> <span class="n">CodecOptions</span><span class="p">(</span><span class="n">tz_aware</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">db</span><span class="o">.</span><span class="n">get_collection</span><span class="p">(</span><span class="s1">'tzdemo'</span><span class="p">,</span> <span class="n">codec_options</span><span class="o">=</span><span class="n">options</span><span class="p">)</span><span class="o">.</span><span class="n">find_one</span><span class="p">()[</span><span class="s1">'date'</span><span class="p">]</span>
<span class="go">datetime.datetime(2002, 10, 27, 6, 0,</span>
<span class="go"> tzinfo=<bson.tz_util.FixedOffset object at 0x10583a050>)</span>
</pre></div>
</div>
</div>
<div class="section" id="saving-datetimes-with-timezones">
<h2>Saving Datetimes with Timezones<a class="headerlink" href="#saving-datetimes-with-timezones" title="Permalink to this headline">¶</a></h2>
<p>When storing <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.datetime</span></code> objects that specify a timezone
(i.e. they have a <cite>tzinfo</cite> property that isn’t <code class="docutils literal notranslate"><span class="pre">None</span></code>), PyMongo will convert
those datetimes to UTC automatically:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">pytz</span>
<span class="gp">>>> </span><span class="n">pacific</span> <span class="o">=</span> <span class="n">pytz</span><span class="o">.</span><span class="n">timezone</span><span class="p">(</span><span class="s1">'US/Pacific'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">aware_datetime</span> <span class="o">=</span> <span class="n">pacific</span><span class="o">.</span><span class="n">localize</span><span class="p">(</span>
<span class="gp">... </span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2002</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">27</span><span class="p">,</span> <span class="mi">6</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="gp">>>> </span><span class="n">result</span> <span class="o">=</span> <span class="n">db</span><span class="o">.</span><span class="n">times</span><span class="o">.</span><span class="n">insert_one</span><span class="p">({</span><span class="s2">"date"</span><span class="p">:</span> <span class="n">aware_datetime</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">db</span><span class="o">.</span><span class="n">times</span><span class="o">.</span><span class="n">find_one</span><span class="p">()[</span><span class="s1">'date'</span><span class="p">]</span>
<span class="go">datetime.datetime(2002, 10, 27, 14, 0)</span>
</pre></div>
</div>
</div>
<div class="section" id="reading-time">
<h2>Reading Time<a class="headerlink" href="#reading-time" title="Permalink to this headline">¶</a></h2>
<p>As previously mentioned, by default all <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.datetime</span></code> objects
returned by PyMongo will be naive but reflect UTC (i.e. the time as stored in
MongoDB). By setting the <cite>tz_aware</cite> option on
<a class="reference internal" href="../api/bson/codec_options.html#bson.codec_options.CodecOptions" title="bson.codec_options.CodecOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">CodecOptions</span></code></a>, <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.datetime</span></code> objects
will be timezone-aware and have a <cite>tzinfo</cite> property that reflects the UTC
timezone.</p>
<p>PyMongo 3.1 introduced a <cite>tzinfo</cite> property that can be set on
<a class="reference internal" href="../api/bson/codec_options.html#bson.codec_options.CodecOptions" title="bson.codec_options.CodecOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">CodecOptions</span></code></a> to convert <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.datetime</span></code>
objects to local time automatically. For example, if we wanted to read all times
out of MongoDB in US/Pacific time:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">bson.codec_options</span> <span class="k">import</span> <span class="n">CodecOptions</span>
<span class="gp">>>> </span><span class="n">db</span><span class="o">.</span><span class="n">times</span><span class="o">.</span><span class="n">find_one</span><span class="p">()[</span><span class="s1">'date'</span><span class="p">]</span>
<span class="go">datetime.datetime(2002, 10, 27, 14, 0)</span>
<span class="gp">>>> </span><span class="n">aware_times</span> <span class="o">=</span> <span class="n">db</span><span class="o">.</span><span class="n">times</span><span class="o">.</span><span class="n">with_options</span><span class="p">(</span><span class="n">codec_options</span><span class="o">=</span><span class="n">CodecOptions</span><span class="p">(</span>
<span class="gp">... </span> <span class="n">tz_aware</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">pytz</span><span class="o">.</span><span class="n">timezone</span><span class="p">(</span><span class="s1">'US/Pacific'</span><span class="p">)))</span>
<span class="gp">>>> </span><span class="n">result</span> <span class="o">=</span> <span class="n">aware_times</span><span class="o">.</span><span class="n">find_one</span><span class="p">()</span>
<span class="go">datetime.datetime(2002, 10, 27, 6, 0, # doctest: +NORMALIZE_WHITESPACE</span>
<span class="go"> tzinfo=<DstTzInfo 'US/Pacific' PST-1 day, 16:00:00 STD>)</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Datetimes and Timezones</a><ul>
<li><a class="reference internal" href="#basic-usage">Basic Usage</a></li>
<li><a class="reference internal" href="#saving-datetimes-with-timezones">Saving Datetimes with Timezones</a></li>
<li><a class="reference internal" href="#reading-time">Reading Time</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="bulk.html"
title="previous chapter">Bulk Write Operations</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="geo.html"
title="next chapter">Geospatial Indexing Example</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/examples/datetimes.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<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="geo.html" title="Geospatial Indexing Example"
>next</a> |</li>
<li class="right" >
<a href="bulk.html" title="Bulk Write Operations"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">PyMongo 3.7.2 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >Examples</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright MongoDB, Inc. 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-release
>
by-pkgid
>
bc55833f04f370ac3ed453ef5b0ad686
>
files
>
280
