summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorCharles Harris <charlesr.harris@gmail.com>2016-01-16 21:02:14 -0700
committerCharles Harris <charlesr.harris@gmail.com>2016-01-16 21:02:14 -0700
commit865c3e375a598e5a0f7d9e690eda4702de8658af (patch)
tree316822fc5b4c8f8a6be584709225f522708a9130 /doc
parent2f7827702ef6b6ac4b318103d5c0dfe2ff6e7eb3 (diff)
parentda98bbc030c272edb1a8548a458b3957e29ce346 (diff)
downloadnumpy-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.rst41
-rw-r--r--doc/source/reference/arrays.datetime.rst62
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
=========================================