DEPR: deprecate some top-level non-used functions

closes pandas-dev#13790

pd.pnow
pd.groupby
pd.match
pd.Term
pd.Expr

remove info.py

doc/source/whatsnew/v0.20.0.txt

@@ -534,6 +534,12 @@ Deprecations
 - ``Series.sortlevel`` and ``DataFrame.sortlevel`` have been deprecated in favor of ``Series.sort_index`` and ``DataFrame.sort_index`` (:issue:`15099`)
 - importing ``concat`` from ``pandas.tools.merge`` has been deprecated in favor of imports from the ``pandas`` namespace. This should only affect explict imports (:issue:`15358`)
 - ``Series/DataFrame/Panel.consolidate()`` been deprecated as a public method. (:issue:`15483`)
+- The following top-level pandas functions have been deprecated and will be removed in a future version (:issue:`13790`)
+  * ``pd.now()``, replaced by a direct import from ``pandas.tseries.period``
+  * ``pd.Term``, replaced by a direct import from ``pandas.io.pytables``
+  * ``pd.Expr``, replaced by a direct import from ``pandas.computation.expr``
+  * ``pd.match()``, replaced by a direct import from ``pandas.core.algorithms``
+  * ``pd.groupby()``, replaced by using the ``.groupby()`` method directly on a ``Series/DataFrame``
 
 .. _whatsnew_0200.prior_deprecations:
 

pandas/__init__.py

@@ -33,7 +33,6 @@
                       "the C extensions first.".format(module))
 
 from datetime import datetime
-from pandas.info import __doc__
 
 # let init-time option registration happen
 import pandas.core.config_init

pandas/computation/api.py

@@ -1,4 +1,13 @@
 # flake8: noqa
 
 from pandas.computation.eval import eval
-from pandas.computation.expr import Expr
+
+
+# deprecation, xref #13790
+def Expr(*args, **kwargs):
+    import warnings
+
+    warnings.warn("pd.Expr is deprecated. Please import from pandas.computation.expr",
+                  FutureWarning, stacklevel=2)
+    from pandas.computation.expr import Expr
+    return Expr(*args, **kwargs)

pandas/core/api.py

@@ -4,7 +4,7 @@
 
 import numpy as np
 
-from pandas.core.algorithms import factorize, match, unique, value_counts
+from pandas.core.algorithms import factorize, unique, value_counts
 from pandas.types.missing import isnull, notnull
 from pandas.core.categorical import Categorical
 from pandas.core.groupby import Grouper
@@ -17,7 +17,6 @@
 from pandas.core.frame import DataFrame
 from pandas.core.panel import Panel, WidePanel
 from pandas.core.panel4d import Panel4D
-from pandas.core.groupby import groupby
 from pandas.core.reshape import (pivot_simple as pivot, get_dummies,
                                  lreshape, wide_to_long)
 
@@ -42,3 +41,21 @@
 
 from pandas.core.config import (get_option, set_option, reset_option,
                                 describe_option, option_context, options)
+
+
+# deprecation, xref #13790
+def match(*args, **kwargs):
+    import warnings
+
+    warnings.warn("pd.match() is deprecated. Please use pandas.core.algorithms.match()",
+                  FutureWarning, stacklevel=2)
+    from pandas.core.algorithms import match
+    return match(*args, **kwargs)
+
+
+def groupby(*args, **kwargs):
+    import warnings
+
+    warnings.warn("pd.groupby() is deprecated. Please use the .groupby() method",
+                  FutureWarning, stacklevel=2)
+    return args[0].groupby(*args[1:], **kwargs)

pandas/io/api.py

@@ -7,7 +7,7 @@
 from pandas.io.parsers import read_csv, read_table, read_fwf
 from pandas.io.clipboard import read_clipboard
 from pandas.io.excel import ExcelFile, ExcelWriter, read_excel
-from pandas.io.pytables import HDFStore, Term, get_store, read_hdf
+from pandas.io.pytables import HDFStore, get_store, read_hdf
 from pandas.io.json import read_json
 from pandas.io.html import read_html
 from pandas.io.sql import read_sql, read_sql_table, read_sql_query
@@ -17,3 +17,12 @@
 from pandas.io.pickle import read_pickle, to_pickle
 from pandas.io.packers import read_msgpack, to_msgpack
 from pandas.io.gbq import read_gbq
+
+# deprecation, xref #13790
+def Term(*args, **kwargs):
+    import warnings
+
+    warnings.warn("pd.Term is deprecated. Please import from pandas.io.pytables",
+                  FutureWarning, stacklevel=2)
+    from pandas.io.pytables import Term
+    return Term(*args, **kwargs)

pandas/tests/api/test_api.py

@@ -59,13 +59,10 @@ class TestPDApi(Base, tm.TestCase):
     # these are already deprecated; awaiting removal
     deprecated_classes = ['WidePanel',
                           'SparseTimeSeries', 'Panel4D',
-                          'SparseList']
+                          'SparseList', 'Expr', 'Term']
 
     # 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']
+    deprecated_classes_in_future = ['Panel']
 
     # external modules exposed in pandas namespace
     modules = ['np', 'datetime']
@@ -75,7 +72,7 @@ class TestPDApi(Base, tm.TestCase):
              'date_range', 'eval',
              'factorize', 'get_dummies', 'get_store',
              'infer_freq', 'isnull', 'lreshape',
-             'match', 'melt', 'notnull', 'offsets',
+             'melt', 'notnull', 'offsets',
              'merge', 'merge_ordered', 'merge_asof',
              'period_range',
              'pivot', 'pivot_table', 'plot_params', 'qcut',
@@ -99,9 +96,6 @@ class TestPDApi(Base, tm.TestCase):
     funcs_to = ['to_datetime', 'to_msgpack',
                 'to_numeric', 'to_pickle', 'to_timedelta']
 
-    # these should be deprecated in the future
-    deprecated_funcs_in_future = ['pnow', 'groupby', 'info']
-
     # these are already deprecated; awaiting removal
     deprecated_funcs = ['ewma', 'ewmcorr', 'ewmcov', 'ewmstd', 'ewmvar',
                         'ewmvol', 'expanding_apply', 'expanding_corr',
@@ -114,7 +108,8 @@ class TestPDApi(Base, tm.TestCase):
                         'rolling_kurt', 'rolling_max', 'rolling_mean',
                         'rolling_median', 'rolling_min', 'rolling_quantile',
                         'rolling_skew', 'rolling_std', 'rolling_sum',
-                        'rolling_var', 'rolling_window', 'ordered_merge']
+                        'rolling_var', 'rolling_window', 'ordered_merge',
+                        'pnow', 'match', 'groupby']
 
     def test_api(self):
 
@@ -123,11 +118,9 @@ def test_api(self):
                    self.modules + self.deprecated_modules +
                    self.classes + self.deprecated_classes +
                    self.deprecated_classes_in_future +
-                   self.remove_classes_from_top_level_namespace +
                    self.funcs + self.funcs_option +
                    self.funcs_read + self.funcs_to +
-                   self.deprecated_funcs +
-                   self.deprecated_funcs_in_future,
+                   self.deprecated_funcs,
                    self.ignored)
 
 
@@ -225,3 +218,33 @@ def test_deprecation_access_obj(self):
         with tm.assert_produces_warning(FutureWarning,
                                         check_stacklevel=False):
             pd.datetools.monthEnd
+
+
+class TestTopLevelDeprecations(tm.TestCase):
+    # top-level API deprecations
+    # GH 13790
+
+    def test_pnow(self):
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            pd.pnow(freq='M')
+
+    def test_term(self):
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            pd.Term('index>=date')
+
+    def test_expr(self):
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            pd.Expr('2>1')
+
+    def test_match(self):
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            pd.match([1, 2, 3], [1])
+
+    def test_groupby(self):
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            pd.groupby(pd.Series([1, 2, 3]), [1, 1, 1])

pandas/tseries/api.py

@@ -7,8 +7,17 @@
 from pandas.tseries.index import DatetimeIndex, date_range, bdate_range
 from pandas.tseries.frequencies import infer_freq
 from pandas.tseries.tdi import Timedelta, TimedeltaIndex, timedelta_range
-from pandas.tseries.period import Period, PeriodIndex, period_range, pnow
+from pandas.tseries.period import Period, PeriodIndex, period_range
 from pandas.tseries.resample import TimeGrouper
 from pandas.tseries.timedeltas import to_timedelta
 from pandas.lib import NaT
 import pandas.tseries.offsets as offsets
+
+# deprecation, xref #13790
+def pnow(freq=None):
+    import warnings
+
+    warnings.warn("pd.pnow() is deprecated. Please use pandas.tseries.period.pnow()",
+                  FutureWarning, stacklevel=2)
+    from pandas.tseries.period import pnow
+    return pnow(freq=freq)