DEPR: deprecate some top-level non-used functions (pandas-dev#15538)

closes pandas-dev#13790

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

remove info.py

Author: jreback

doc/source/comparison_with_r.rst

@@ -206,14 +206,6 @@ of its first argument in its second:
    s <- 0:4
    match(s, c(2,4))
 
-The :meth:`~pandas.core.groupby.GroupBy.apply` method can be used to replicate
-this:
-
-.. ipython:: python
-
-   s = pd.Series(np.arange(5),dtype=np.float32)
-   pd.Series(pd.match(s,[2,4],np.nan))
-
 For more details and examples see :ref:`the reshaping documentation
 <indexing.basics.indexing_isin>`.
 

doc/source/whatsnew/v0.20.0.txt

@@ -537,6 +537,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``, is removed, as it is not applicable to user code. Instead use in-line string expressions in the where clause when searching in HDFStore
+  * ``pd.Expr``, is removed, as it is not applicable to user code.
+  * ``pd.match()``, is removed.
+  * ``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
@@ -63,3 +62,45 @@
 v = get_versions()
 __version__ = v.get('closest-tag', v['version'])
 del get_versions, v
+
+# module level doc-string
+__doc__ = """
+pandas - a powerful data analysis and manipulation library for Python
+=====================================================================
+
+**pandas** is a Python package providing fast, flexible, and expressive data
+structures designed to make working with "relational" or "labeled" data both
+easy and intuitive. It aims to be the fundamental high-level building block for
+doing practical, **real world** data analysis in Python. Additionally, it has
+the broader goal of becoming **the most powerful and flexible open source data
+analysis / manipulation tool available in any language**. It is already well on
+its way toward this goal.
+
+Main Features
+-------------
+Here are just a few of the things that pandas does well:
+
+  - Easy handling of missing data in floating point as well as non-floating
+    point data
+  - Size mutability: columns can be inserted and deleted from DataFrame and
+    higher dimensional objects
+  - Automatic and explicit data alignment: objects can  be explicitly aligned
+    to a set of labels, or the user can simply ignore the labels and let
+    `Series`, `DataFrame`, etc. automatically align the data for you in
+    computations
+  - Powerful, flexible group by functionality to perform split-apply-combine
+    operations on data sets, for both aggregating and transforming data
+  - Make it easy to convert ragged, differently-indexed data in other Python
+    and NumPy data structures into DataFrame objects
+  - Intelligent label-based slicing, fancy indexing, and subsetting of large
+    data sets
+  - Intuitive merging and joining data sets
+  - Flexible reshaping and pivoting of data sets
+  - Hierarchical labeling of axes (possible to have multiple labels per tick)
+  - Robust IO tools for loading data from flat files (CSV and delimited),
+    Excel files, databases, and saving/loading data from the ultrafast HDF5
+    format
+  - Time series-specific functionality: date range generation and frequency
+    conversion, moving window statistics, moving window linear regressions,
+    date shifting and lagging, etc.
+"""

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,24 @@
 
 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 and will be removed "
+                  "in a future version",
+                  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 and will be removed "
+                  "Please use the Series.groupby() or "
+                  "DataFrame.groupby() methods",
+                  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,15 @@
 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 the where clause when "
+                  "searching in 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):