Permalink
Browse files

Add FAQ entry for datetime.datetime OverflowError.

  • Loading branch information...
1 parent 0b1a58d commit 6242782e60a37f93339ad21293b7ce1c6e67bdbd @behackett behackett committed Dec 14, 2012
Showing with 37 additions and 11 deletions.
  1. +37 −11 doc/faq.rst
View
@@ -275,18 +275,44 @@ with :mod:`json` and :mod:`simplejson` in the
Why do I get an error for dates on or after 2038?
-------------------------------------------------
-On Unix systems, dates are represented as seconds from 1 January 1970 and usually stored in the C
-:mod:`time_t` type. On most 32-bit operating systems :mod:`time_t` is a signed 4 byte integer
-which means it can't handle dates after 19 January 2038; this is known as the
-`year 2038 problem <http://en.wikipedia.org/wiki/Year_2038_problem>`_. Neither MongoDB nor
-Python uses :mod:`time_t` to represent dates internally so do not suffer from this problem, but
-Python's :mod:`datetime.datetime.fromtimestamp()` used by PyMongo's Python implementation of
-:mod:`bson` does, which means it is susceptible. Therefore, on 32-bit systems you may get an
-error retrieving dates after 2038 from MongoDB using PyMongo with the Python version of
-:mod:`bson`.
+On Unix systems, dates are represented as seconds from 1 January 1970 and
+usually stored in the C :mod:`time_t` type. On most 32-bit operating systems
+:mod:`time_t` is a signed 4 byte integer which means it can't handle dates
+after 19 January 2038; this is known as the `year 2038 problem
+<http://en.wikipedia.org/wiki/Year_2038_problem>`_. Neither MongoDB nor Python
+uses :mod:`time_t` to represent dates internally so do not suffer from this
+problem, but Python's :mod:`datetime.datetime.fromtimestamp()` does, which
+means it is susceptible.
+
+Previous to version 2.0, PyMongo used :mod:`datetime.datetime.fromtimestamp()`
+in its pure Python :mod:`bson` module. Therefore, on 32-bit systems you may
+get an error retrieving dates after 2038 from MongoDB using older versions
+of PyMongo with the pure Python version of :mod:`bson`.
+
+This problem was fixed in the pure Python implementation of :mod:`bson` by
+commit ``b19ab334af2a29353529`` (8 June 2011 - PyMongo 2.0).
+
+The C implementation of :mod:`bson` also used to suffer from this problem but
+it was fixed in commit ``566bc9fb7be6f9ab2604`` (10 May 2010 - PyMongo 1.7).
+
+Why do I get OverflowError decoding dates stored by another language's driver?
+------------------------------------------------------------------------------
+PyMongo decodes BSON datetime values to instances of Python's
+:class:`datetime.datetime`. Instances of :class:`datetime.datetime` are
+limited to years between :data:`datetime.MINYEAR` (usually 1) and
+:data:`datetime.MAXYEAR` (usually 9999). Some MongoDB drivers (e.g. the PHP
+driver) can store BSON datetimes with year values far outside those supported
+by :class:`datetime.datetime`.
-The C implementation of :mod:`bson` also used to suffer from this problem but it was fixed in
-commit ``566bc9fb7be6f9ab2604`` (10 May 2010).
+There are a few ways to work around this issue. One option is to filter
+out documents with values outside of the range supported by
+:class:`datetime.datetime`::
+ >>> from datetime import datetime
+ >>> coll = client.test.dates
+ >>> cur = coll.find({'dt': {'$gte': datetime.min, '$lte': datetime.max}})
+Another option, assuming you don't need the datetime field, is to filter out
+just that field::
+ >>> cur = coll.find({}, fields={'dt': False})

0 comments on commit 6242782

Please sign in to comment.