diff --git a/doc/source/whatsnew/v0.21.0.txt b/doc/source/whatsnew/v0.21.0.txt index 273cbd8357f85..96e21852e9189 100644 --- a/doc/source/whatsnew/v0.21.0.txt +++ b/doc/source/whatsnew/v0.21.0.txt @@ -132,7 +132,6 @@ Other Enhancements - :func:`DataFrame.items` and :func:`Series.items` is now present in both Python 2 and 3 and is lazy in all cases (:issue:`13918`, :issue:`17213`) - .. _whatsnew_0210.api_breaking: Backwards incompatible API changes @@ -328,6 +327,10 @@ Deprecations - ``pd.options.html.border`` has been deprecated in favor of ``pd.options.display.html.border`` (:issue:`15793`). + +- :func: `to_datetime` now takes ``tz`` keyword argument, ``utc`` argument is deprecated (:issue:`13712`) + + .. _whatsnew_0210.prior_deprecations: Removal of prior version deprecations/changes diff --git a/pandas/core/tools/datetimes.py b/pandas/core/tools/datetimes.py index c0f234a36803d..dc388fe4e1a55 100644 --- a/pandas/core/tools/datetimes.py +++ b/pandas/core/tools/datetimes.py @@ -20,6 +20,7 @@ ABCDataFrame, ABCDateOffset) from pandas.core.dtypes.missing import notna from pandas.core import algorithms +from pandas.util._decorators import deprecate_kwarg import pandas.compat as compat @@ -182,9 +183,12 @@ def _guess_datetime_format_for_array(arr, **kwargs): return _guess_datetime_format(arr[non_nan_elements[0]], **kwargs) +@deprecate_kwarg(old_arg_name='utc', new_arg_name='tz', + mapping={True: 'UTC'}) def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False, - utc=None, box=True, format=None, exact=True, - unit=None, infer_datetime_format=False, origin='unix'): + box=True, format=None, exact=True, + unit=None, infer_datetime_format=False, origin='unix', + tz=None): """ Convert argument to datetime. @@ -223,6 +227,14 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False, utc : boolean, default None Return UTC DatetimeIndex if True (converting any tz-aware datetime.datetime objects as well). + + .. deprecated: 0.21.0 + + tz : pytz.timezone or dateutil.tz.tzfile, default None + Define the timezone. + + .. versionadded: 0.21.0 + box : boolean, default True - If True returns a DatetimeIndex @@ -343,8 +355,6 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False, """ from pandas.core.indexes.datetimes import DatetimeIndex - tz = 'utc' if utc else None - def _convert_listlike(arg, box, format, name=None, tz=tz): if isinstance(arg, (list, tuple)): @@ -354,8 +364,8 @@ def _convert_listlike(arg, box, format, name=None, tz=tz): if is_datetime64tz_dtype(arg): if not isinstance(arg, DatetimeIndex): return DatetimeIndex(arg, tz=tz, name=name) - if utc: - arg = arg.tz_convert(None).tz_localize('UTC') + if tz: + arg = arg.tz_convert(None).tz_localize(tz) return arg elif is_datetime64_ns_dtype(arg): @@ -431,6 +441,10 @@ def _convert_listlike(arg, box, format, name=None, tz=tz): result = arg if result is None and (format is None or infer_datetime_format): + if tz == 'utc' or tz == 'UTC': + utc = True + else: + utc = False result = tslib.array_to_datetime( arg, errors=errors, diff --git a/pandas/tests/indexes/datetimes/test_tools.py b/pandas/tests/indexes/datetimes/test_tools.py index 50669ee357bbd..98ce7e32cc4b9 100644 --- a/pandas/tests/indexes/datetimes/test_tools.py +++ b/pandas/tests/indexes/datetimes/test_tools.py @@ -270,6 +270,23 @@ def test_to_datetime_utc_is_true(self): expected = pd.DatetimeIndex(data=date_range) tm.assert_index_equal(result, expected) + def test_to_datetime_tz_kw(self): + # See gh-13712 + for tz in [None, 'US/Eastern', 'Asia/Tokyo', 'UTC']: + data = ['20140101 000000', '20140102 000000', '20140103 000000'] + start = pd.Timestamp(data[0], tz=tz) + end = pd.Timestamp(data[-1], tz=tz) + date_range = pd.bdate_range(start, end) + + result = pd.to_datetime(data, format='%Y%m%d %H%M%S', tz=tz) + expected = pd.DatetimeIndex(data=date_range) + tm.assert_numpy_array_equal(result.values, expected.values) + + if result.tz is None: + assert expected.tz is None + else: + assert result.tz.zone == expected.tz.zone + def test_to_datetime_tz_psycopg2(self): # xref 8260