DEPR: Deprecate pandas.core.datetools (#14105)

* MAINT: Replace datetools import in tests

* MAINT: Replace datetools import internally

* DOC: Replace datetools import in docs

* MAINT: Remove datetool imports from scripts

* DEPR: Deprecate pandas.core.datetools

Closes gh-14094.

Author: gfyoung

doc/source/timeseries.rst

@@ -7,7 +7,7 @@
    from datetime import datetime, timedelta, time
    import numpy as np
    import pandas as pd
-   from pandas import datetools
+   from pandas import offsets
    np.random.seed(123456)
    randn = np.random.randn
    randint = np.random.randint
@@ -1223,7 +1223,7 @@ The shift method accepts an ``freq`` argument which can accept a
 
 .. ipython:: python
 
-   ts.shift(5, freq=datetools.bday)
+   ts.shift(5, freq=offsets.BDay())
    ts.shift(5, freq='BM')
 
 Rather than changing the alignment of the data and the index, ``DataFrame`` and
@@ -1246,7 +1246,7 @@ around ``reindex`` which generates a ``date_range`` and calls ``reindex``.
 
 .. ipython:: python
 
-   dr = pd.date_range('1/1/2010', periods=3, freq=3 * datetools.bday)
+   dr = pd.date_range('1/1/2010', periods=3, freq=3 * offsets.BDay())
    ts = pd.Series(randn(3), index=dr)
    ts
    ts.asfreq(BDay())

doc/source/whatsnew/v0.19.0.txt

@@ -1295,6 +1295,7 @@ Deprecations
 
 - ``PeriodIndex.to_datetime`` has been deprecated in favour of ``PeriodIndex.to_timestamp`` (:issue:`8254`)
 - ``Timestamp.to_datetime`` has been deprecated in favour of ``Timestamp.to_pydatetime`` (:issue:`8254`)
+- ``pandas.core.datetools`` module has been deprecated and will be removed in a subsequent release (:issue:`14094`)
 - ``Index.to_datetime`` and ``DatetimeIndex.to_datetime`` have been deprecated in favour of ``pd.to_datetime`` (:issue:`8254`)
 - ``SparseList`` has been deprecated and will be removed in a future version (:issue:`13784`)
 - ``DataFrame.to_html()`` and ``DataFrame.to_latex()`` have dropped the ``colSpace`` parameter in favor of ``col_space`` (:issue:`13857`)

pandas/api/tests/test_api.py

@@ -42,7 +42,7 @@ class TestPDApi(Base, tm.TestCase):
                      'json', 'lib', 'index', 'parser']
 
     # these are already deprecated; awaiting removal
-    deprecated_modules = ['ols', 'stats']
+    deprecated_modules = ['ols', 'stats', 'datetools']
 
     # misc
     misc = ['IndexSlice', 'NaT']
@@ -61,14 +61,14 @@ class TestPDApi(Base, tm.TestCase):
                           'SparseTimeSeries', 'Panel4D',
                           'SparseList']
 
-    # these should be deperecated in the future
+    # these should be deprecated in the future
     deprecated_classes_in_future = ['Term', 'Panel']
 
     # these should be removed from top-level namespace
     remove_classes_from_top_level_namespace = ['Expr']
 
     # external modules exposed in pandas namespace
-    modules = ['np', 'datetime', 'datetools']
+    modules = ['np', 'datetime']
 
     # top-level functions
     funcs = ['bdate_range', 'concat', 'crosstab', 'cut',
@@ -99,7 +99,7 @@ class TestPDApi(Base, tm.TestCase):
     funcs_to = ['to_datetime', 'to_msgpack',
                 'to_numeric', 'to_pickle', 'to_timedelta']
 
-    # these should be deperecated in the future
+    # these should be deprecated in the future
     deprecated_funcs_in_future = ['pnow', 'groupby', 'info']
 
     # these are already deprecated; awaiting removal
@@ -208,6 +208,19 @@ def test_removed_from_core_common(self):
                   'ensure_float']:
             self.assertRaises(AttributeError, lambda: getattr(com, t))
 
+
+class TestDatetools(tm.TestCase):
+
+    def test_deprecation_access_func(self):
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            pd.datetools.to_datetime('2016-01-01')
+
+    def test_deprecation_access_obj(self):
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            pd.datetools.monthEnd
+
 if __name__ == '__main__':
     import nose
     nose.runmodule(argv=[__file__, '-vvs', '-x', '--pdb', '--pdb-failure'],

pandas/core/api.py

@@ -28,8 +28,18 @@
 from pandas.tseries.tdi import TimedeltaIndex, Timedelta
 from pandas.tseries.period import Period, PeriodIndex
 
-# legacy
-import pandas.core.datetools as datetools
+# see gh-14094.
+from pandas.util.depr_module import _DeprecatedModule
+
+_alts = ['pandas.tseries.tools', 'pandas.tseries.offsets',
+         'pandas.tseries.frequencies']
+_removals = ['day', 'bday', 'businessDay', 'cday', 'customBusinessDay',
+             'customBusinessMonthEnd', 'customBusinessMonthBegin',
+             'monthEnd', 'yearEnd', 'yearBegin', 'bmonthEnd', 'bmonthBegin',
+             'cbmonthEnd', 'cbmonthBegin', 'bquarterEnd', 'quarterEnd',
+             'byearEnd', 'week']
+datetools = _DeprecatedModule(deprmod='pandas.core.datetools', alts=_alts,
+                              removals=_removals)
 
 from pandas.core.config import (get_option, set_option, reset_option,
                                 describe_option, option_context, options)

pandas/core/datetools.py

@@ -2,10 +2,16 @@
 
 # flake8: noqa
 
+import warnings
+
 from pandas.tseries.tools import *
 from pandas.tseries.offsets import *
 from pandas.tseries.frequencies import *
 
+warnings.warn("The pandas.core.datetools module is deprecated and will be "
+              "removed in a future version. Please use the pandas.tseries "
+              "module instead.", FutureWarning, stacklevel=2)
+
 day = DateOffset()
 bday = BDay()
 businessDay = bday

pandas/core/generic.py

@@ -42,9 +42,9 @@
 import pandas.core.algorithms as algos
 import pandas.core.common as com
 import pandas.core.missing as missing
-import pandas.core.datetools as datetools
 from pandas.formats.printing import pprint_thing
 from pandas.formats.format import format_percentiles
+from pandas.tseries.frequencies import to_offset
 from pandas import compat
 from pandas.compat.numpy import function as nv
 from pandas.compat import (map, zip, lrange, string_types,
@@ -4792,7 +4792,7 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None,
         periods : int
             Number of periods to move, can be positive or negative
         freq : DateOffset, timedelta, or time rule string, optional
-            Increment to use from datetools module or time rule (e.g. 'EOM').
+            Increment to use from the tseries module or time rule (e.g. 'EOM').
             See Notes.
         axis : %(axes_single_arg)s
 
@@ -4865,7 +4865,7 @@ def tshift(self, periods=1, freq=None, axis=0):
         periods : int
             Number of periods to move, can be positive or negative
         freq : DateOffset, timedelta, or time rule string, default None
-            Increment to use from datetools module or time rule (e.g. 'EOM')
+            Increment to use from the tseries module or time rule (e.g. 'EOM')
         axis : int or basestring
             Corresponds to the axis that contains the Index
 
@@ -4895,11 +4895,11 @@ def tshift(self, periods=1, freq=None, axis=0):
             return self
 
         if isinstance(freq, string_types):
-            freq = datetools.to_offset(freq)
+            freq = to_offset(freq)
 
         block_axis = self._get_block_manager_axis(axis)
         if isinstance(index, PeriodIndex):
-            orig_freq = datetools.to_offset(index.freq)
+            orig_freq = to_offset(index.freq)
             if freq == orig_freq:
                 new_data = self._data.copy()
                 new_data.axes[block_axis] = index.shift(periods)

pandas/io/tests/test_sql.py

@@ -37,7 +37,7 @@
 from pandas import date_range, to_datetime, to_timedelta, Timestamp
 import pandas.compat as compat
 from pandas.compat import StringIO, range, lrange, string_types
-from pandas.core.datetools import format as date_format
+from pandas.tseries.tools import format as date_format
 
 import pandas.io.sql as sql
 from pandas.io.sql import read_sql_table, read_sql_query

pandas/sparse/tests/test_frame.py

@@ -8,7 +8,7 @@
 
 from pandas import Series, DataFrame, bdate_range, Panel
 from pandas.tseries.index import DatetimeIndex
-import pandas.core.datetools as datetools
+from pandas.tseries.offsets import BDay
 import pandas.util.testing as tm
 from pandas.compat import lrange
 from pandas import compat
@@ -850,8 +850,8 @@ def _check(frame, orig):
             exp = exp.to_sparse(frame.default_fill_value)
             tm.assert_frame_equal(shifted, exp)
 
-            shifted = frame.shift(2, freq=datetools.bday)
-            exp = orig.shift(2, freq=datetools.bday)
+            shifted = frame.shift(2, freq=BDay())
+            exp = orig.shift(2, freq=BDay())
             exp = exp.to_sparse(frame.default_fill_value)
             tm.assert_frame_equal(shifted, exp)
 

pandas/sparse/tests/test_series.py

@@ -7,9 +7,8 @@
 import pandas as pd
 
 from pandas import Series, DataFrame, bdate_range
-from pandas.core.datetools import BDay
-import pandas.core.datetools as datetools
 from pandas.core.common import isnull
+from pandas.tseries.offsets import BDay
 import pandas.util.testing as tm
 from pandas.compat import range
 from pandas import compat
@@ -843,7 +842,7 @@ def test_shift(self):
         f = lambda s: s.shift(2, freq='B')
         _dense_series_compare(series, f)
 
-        f = lambda s: s.shift(2, freq=datetools.bday)
+        f = lambda s: s.shift(2, freq=BDay())
         _dense_series_compare(series, f)
 
     def test_shift_nan(self):

pandas/stats/tests/test_ols.py

@@ -16,15 +16,15 @@
 
 from pandas import date_range, bdate_range
 from pandas.core.panel import Panel
-from pandas import DataFrame, Index, Series, notnull, datetools
+from pandas import DataFrame, Index, Series, notnull, offsets
 from pandas.stats.api import ols
 from pandas.stats.ols import _filter_data
 from pandas.stats.plm import NonPooledPanelOLS, PanelOLS
 from pandas.util.testing import (assert_almost_equal, assert_series_equal,
                                  assert_frame_equal, assertRaisesRegexp, slow)
 import pandas.util.testing as tm
 import pandas.compat as compat
-from .common import BaseTest
+from pandas.stats.tests.common import BaseTest
 
 _have_statsmodels = True
 try:
@@ -898,22 +898,22 @@ class TestOLSFilter(tm.TestCase):
 
     def setUp(self):
         date_index = date_range(datetime(2009, 12, 11), periods=3,
-                                freq=datetools.bday)
+                                freq=offsets.BDay())
         ts = Series([3, 1, 4], index=date_index)
         self.TS1 = ts
 
         date_index = date_range(datetime(2009, 12, 11), periods=5,
-                                freq=datetools.bday)
+                                freq=offsets.BDay())
         ts = Series([1, 5, 9, 2, 6], index=date_index)
         self.TS2 = ts
 
         date_index = date_range(datetime(2009, 12, 11), periods=3,
-                                freq=datetools.bday)
+                                freq=offsets.BDay())
         ts = Series([5, np.nan, 3], index=date_index)
         self.TS3 = ts
 
         date_index = date_range(datetime(2009, 12, 11), periods=5,
-                                freq=datetools.bday)
+                                freq=offsets.BDay())
         ts = Series([np.nan, 5, 8, 9, 7], index=date_index)
         self.TS4 = ts