diff options
author | Charles Harris <charlesr.harris@gmail.com> | 2016-01-16 21:02:14 -0700 |
---|---|---|
committer | Charles Harris <charlesr.harris@gmail.com> | 2016-01-16 21:02:14 -0700 |
commit | 865c3e375a598e5a0f7d9e690eda4702de8658af (patch) | |
tree | 316822fc5b4c8f8a6be584709225f522708a9130 /doc | |
parent | 2f7827702ef6b6ac4b318103d5c0dfe2ff6e7eb3 (diff) | |
parent | da98bbc030c272edb1a8548a458b3957e29ce346 (diff) | |
download | numpy-865c3e375a598e5a0f7d9e690eda4702de8658af.tar.gz |
Merge pull request #6453 from shoyer/naive-datetime64
API: Make datetime64 timezone naive
Diffstat (limited to 'doc')
-rw-r--r-- | doc/release/1.11.0-notes.rst | 41 | ||||
-rw-r--r-- | doc/source/reference/arrays.datetime.rst | 62 |
2 files changed, 78 insertions, 25 deletions
diff --git a/doc/release/1.11.0-notes.rst b/doc/release/1.11.0-notes.rst index 0305688d8..770938b60 100644 --- a/doc/release/1.11.0-notes.rst +++ b/doc/release/1.11.0-notes.rst @@ -7,6 +7,8 @@ This release supports Python 2.6 - 2.7 and 3.2 - 3.5. Highlights ========== +* The datetime64 type is now timezone naive. See "datetime64 changes" below + for more details. Build System Changes ==================== @@ -31,6 +33,41 @@ Future Changes Compatibility notes =================== +datetime64 changes +~~~~~~~~~~~~~~~~~~ + +In prior versions of NumPy the experimental datetime64 type always stored +times in UTC. By default, creating a datetime64 object from a string or +printing it would convert from or to local time:: + + # old behavior + >>>> np.datetime64('2000-01-01T00:00:00') + numpy.datetime64('2000-01-01T00:00:00-0800') # note the timezone offset -08:00 + +A concensus of datetime64 users agreed that this behavior is undesirable +and at odds with how datetime64 is usually used (e.g., by pandas_). For +most use cases, a timezone naive datetime type is preferred, similar to the +``datetime.datetime`` type in the Python standard library. Accordingly, +datetime64 no longer assumes that input is in local time, nor does it print +local times:: + + >>>> np.datetime64('2000-01-01T00:00:00') + numpy.datetime64('2000-01-01T00:00:00') + +For backwards compatibility, datetime64 still parses timezone offsets, which +it handles by converting to UTC. However, the resulting datetime is timezone +naive:: + + >>> np.datetime64('2000-01-01T00:00:00-08') + DeprecationWarning: parsing timezone aware datetimes is deprecated; this will raise an error in the future + numpy.datetime64('2000-01-01T08:00:00') + +As a corollary to this change, we no longer prohibit casting between datetimes +with date units and datetimes with timeunits. With timezone naive datetimes, +the rule for casting from dates to times is no longer ambiguous. + +pandas_: http://pandas.pydata.org + DeprecationWarning to error ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -163,6 +200,10 @@ extended to ``@``, ``numpy.dot``, ``numpy.inner``, and ``numpy.matmul``. **Note:** Requires the transposed and non-transposed matrices to share data. +*np.testing.assert_warns* can now be used as a context manager +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This matches the behavior of ``assert_raises``. + Changes ======= Pyrex support was removed from ``numpy.distutils``. The method diff --git a/doc/source/reference/arrays.datetime.rst b/doc/source/reference/arrays.datetime.rst index 0e8050b01..f5b454875 100644 --- a/doc/source/reference/arrays.datetime.rst +++ b/doc/source/reference/arrays.datetime.rst @@ -45,16 +45,10 @@ some additional SI-prefix seconds-based units. >>> np.datetime64('2005-02', 'D') numpy.datetime64('2005-02-01') - Using UTC "Zulu" time: - - >>> np.datetime64('2005-02-25T03:30Z') - numpy.datetime64('2005-02-24T21:30-0600') - - ISO 8601 specifies to use the local time zone - if none is explicitly given: + From a date and time: >>> np.datetime64('2005-02-25T03:30') - numpy.datetime64('2005-02-25T03:30-0600') + numpy.datetime64('2005-02-25T03:30') When creating an array of datetimes from a string, it is still possible to automatically select the unit from the inputs, by using the @@ -100,23 +94,6 @@ because the moment of time is still being represented exactly. >>> np.datetime64('2010-03-14T15Z') == np.datetime64('2010-03-14T15:00:00.00Z') True -An important exception to this rule is between datetimes with -:ref:`date units <arrays.dtypes.dateunits>` and datetimes with -:ref:`time units <arrays.dtypes.timeunits>`. This is because this kind -of conversion generally requires a choice of timezone and -particular time of day on the given date. - -.. admonition:: Example - - >>> np.datetime64('2003-12-25', 's') - Traceback (most recent call last): - File "<stdin>", line 1, in <module> - TypeError: Cannot parse "2003-12-25" as unit 's' using casting rule 'same_kind' - - >>> np.datetime64('2003-12-25') == np.datetime64('2003-12-25T00Z') - False - - Datetime and Timedelta Arithmetic ================================= @@ -353,6 +330,41 @@ Some examples:: # any amount of whitespace is allowed; abbreviations are case-sensitive. weekmask = "MonTue Wed Thu\tFri" +Changes with NumPy 1.11 +======================= + +In prior versions of NumPy, the datetime64 type always stored +times in UTC. By default, creating a datetime64 object from a string or +printing it would convert from or to local time:: + + # old behavior + >>>> np.datetime64('2000-01-01T00:00:00') + numpy.datetime64('2000-01-01T00:00:00-0800') # note the timezone offset -08:00 + +A concensus of datetime64 users agreed that this behavior is undesirable +and at odds with how datetime64 is usually used (e.g., by pandas_). For +most use cases, a timezone naive datetime type is preferred, similar to the +``datetime.datetime`` type in the Python standard library. Accordingly, +datetime64 no longer assumes that input is in local time, nor does it print +local times:: + + >>>> np.datetime64('2000-01-01T00:00:00') + numpy.datetime64('2000-01-01T00:00:00') + +For backwards compatibility, datetime64 still parses timezone offsets, which +it handles by converting to UTC. However, the resulting datetime is timezone +naive:: + + >>> np.datetime64('2000-01-01T00:00:00-08') + DeprecationWarning: parsing timezone aware datetimes is deprecated; this will raise an error in the future + numpy.datetime64('2000-01-01T08:00:00') + +As a corollary to this change, we no longer prohibit casting between datetimes +with date units and datetimes with timeunits. With timezone naive datetimes, +the rule for casting from dates to times is no longer ambiguous. + +pandas_: http://pandas.pydata.org + Differences Between 1.6 and 1.7 Datetimes ========================================= |