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

Author: jreback

doc/source/whatsnew/v0.20.0.txt

@@ -536,6 +536,12 @@ Deprecations
 - 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`)
 - ``FrozenList`` addition (new object and inplace) have been deprecated in favor of the ``.union()`` method. (:issue: `15475`)
+- The following top-level pandas functions have been deprecated and will be removed in a future version (:issue:`13790`)
+  * ``pd.pnow()``, replaced by ``Period.now()``
+  * ``pd.Term``, not applicable to the user
+  * ``pd.Expr``, not applicable to the user
+  * ``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,14 @@
 # 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 as it is not "
+                  "applicable to user code",
+                  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/info.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,14 @@
 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 as it is not "
+                  "applicable to user code. Instead use in-line "
+                  "string expressions in for searching HDFStore",
+                  FutureWarning, stacklevel=2)
+    from pandas.io.pytables import Term
+    return Term(*args, **kwargs)

pandas/io/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/tests/api/test_api.py

@@ -864,17 +864,11 @@ def test_properties_nat(self):
             self.assertTrue(np.isnan(getattr(t_nat, f)))
 
     def test_pnow(self):
-        dt = datetime.now()
 
-        val = period.pnow('D')
-        exp = Period(dt, freq='D')
-        self.assertEqual(val, exp)
-
-        val2 = period.pnow('2D')
-        exp2 = Period(dt, freq='2D')
-        self.assertEqual(val2, exp2)
-        self.assertEqual(val.ordinal, val2.ordinal)
-        self.assertEqual(val.ordinal, exp2.ordinal)
+        # deprecation, xref #13790
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            period.pnow('D')
 
     def test_constructor_corner(self):
         expected = Period('2007-01', freq='2M')

pandas/tests/scalar/test_period.py

@@ -1144,7 +1144,13 @@ def _make_field_arrays(*fields):
 
 
 def pnow(freq=None):
-    return Period(datetime.now(), freq=freq)
+    # deprecation, xref #13790
+    import warnings
+
+    warnings.warn("pd.pnow() and pandas.tseries.period.pnow() "
+                  "are deprecated. Please use Period.now()",
+                  FutureWarning, stacklevel=2)
+    return Period.now(freq=freq)
 
 
 def period_range(start=None, end=None, periods=None, freq='D', name=None):