DEPR: pd.value_counts

doc/source/user_guide/basics.rst

@@ -675,7 +675,7 @@ matching index:
 Value counts (histogramming) / mode
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The :meth:`~Series.value_counts` Series method and top-level function computes a histogram
+The :meth:`~Series.value_counts` Series method computes a histogram
 of a 1D array of values. It can also be used as a function on regular arrays:
 
 .. ipython:: python
@@ -684,7 +684,6 @@ of a 1D array of values. It can also be used as a function on regular arrays:
    data
    s = pd.Series(data)
    s.value_counts()
-   pd.value_counts(data)
 
 The :meth:`~DataFrame.value_counts` method can be used to count combinations across multiple columns.
 By default all columns are used but a subset can be selected using the ``subset`` argument.
@@ -733,7 +732,6 @@ normally distributed data into equal-size quartiles like so:
    arr = np.random.randn(30)
    factor = pd.qcut(arr, [0, 0.25, 0.5, 0.75, 1])
    factor
-   pd.value_counts(factor)
 
 We can also pass infinite values to define the bins:
 

doc/source/whatsnew/v0.19.1.rst

@@ -7,6 +7,7 @@ Version 0.19.1 (November 3, 2016)
 
 .. ipython:: python
    :suppress:
+   :okwarning:
 
    from pandas import *  # noqa F401, F403
 

doc/source/whatsnew/v0.19.2.rst

@@ -7,6 +7,7 @@ Version 0.19.2 (December 24, 2016)
 
 .. ipython:: python
    :suppress:
+   :okwarning:
 
    from pandas import *  # noqa F401, F403
 

doc/source/whatsnew/v0.20.2.rst

@@ -7,6 +7,7 @@ Version 0.20.2 (June 4, 2017)
 
 .. ipython:: python
    :suppress:
+   :okwarning:
 
    from pandas import *  # noqa F401, F403
 

doc/source/whatsnew/v0.20.3.rst

@@ -7,6 +7,7 @@ Version 0.20.3 (July 7, 2017)
 
 .. ipython:: python
    :suppress:
+   :okwarning:
 
    from pandas import *  # noqa F401, F403
 

doc/source/whatsnew/v0.21.0.rst

@@ -7,6 +7,7 @@ Version 0.21.0 (October 27, 2017)
 
 .. ipython:: python
    :suppress:
+   :okwarning:
 
    from pandas import * # noqa F401, F403
 

doc/source/whatsnew/v0.21.1.rst

@@ -7,6 +7,7 @@ Version 0.21.1 (December 12, 2017)
 
 .. ipython:: python
    :suppress:
+   :okwarning:
 
    from pandas import *  # noqa F401, F403
 

doc/source/whatsnew/v0.22.0.rst

@@ -7,6 +7,7 @@ Version 0.22.0 (December 29, 2017)
 
 .. ipython:: python
    :suppress:
+   :okwarning:
 
    from pandas import *  # noqa F401, F403
 

doc/source/whatsnew/v0.23.0.rst

@@ -7,6 +7,7 @@ What's new in 0.23.0 (May 15, 2018)
 
 .. ipython:: python
    :suppress:
+   :okwarning:
 
    from pandas import * # noqa F401, F403
 

doc/source/whatsnew/v2.1.0.rst

@@ -270,6 +270,7 @@ Deprecations
 - Deprecated unused "closed" and "normalize" keywords in the :class:`DatetimeIndex` constructor (:issue:`52628`)
 - Deprecated unused "closed" keyword in the :class:`TimedeltaIndex` constructor (:issue:`52628`)
 - Deprecated logical operation between two non boolean :class:`Series` with different indexes always coercing the result to bool dtype. In a future version, this will maintain the return type of the inputs. (:issue:`52500`, :issue:`52538`)
+- Deprecated :func:`value_counts`, use ``pd.Series(obj).value_counts()`` instead (:issue:`47862`)
 - Deprecated :meth:`Series.first` and :meth:`DataFrame.first` (please create a mask and filter using ``.loc`` instead) (:issue:`45908`)
 - Deprecated allowing ``downcast`` keyword other than ``None``, ``False``, "infer", or a dict with these as values in :meth:`Series.fillna`, :meth:`DataFrame.fillna` (:issue:`40988`)
 - Deprecated allowing arbitrary ``fill_value`` in :class:`SparseDtype`, in a future version the ``fill_value`` will need to be compatible with the ``dtype.subtype``, either a scalar that can be held by that subtype or ``NaN`` for integer or bool subtypes (:issue:`23124`)

pandas/__init__.py

@@ -1,3 +1,4 @@
+# pylint: disable=undefined-all-variable
 from __future__ import annotations
 
 __docformat__ = "restructuredtext"
@@ -99,7 +100,6 @@
     Grouper,
     factorize,
     unique,
-    value_counts,
     NamedAgg,
     array,
     Categorical,
@@ -232,6 +232,25 @@
     conversion, moving window statistics, date shifting and lagging.
 """
 
+
+def __getattr__(name: str):
+    if name == "value_counts":
+        import warnings
+        from pandas.util._exceptions import find_stack_level
+        from pandas.core.algorithms import value_counts
+
+        warnings.warn(
+            # GH#47862
+            "pandas.value_counts is deprecated and will be removed in a future "
+            "version. Use pd.Series(obj).value_counts() instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return value_counts
+
+    raise AttributeError(f"module 'pandas' has no attribute '{name}'")
+
+
 # Use __all__ to let type checkers know what is part of the public API.
 # Pandas is not (yet) a py.typed library: the public API is determined
 # based on the documentation.
@@ -348,6 +367,6 @@
     "to_timedelta",
     "tseries",
     "unique",
-    "value_counts",
+    "value_counts",  # pyright: ignore [reportUnsupportedDunderAll]
     "wide_to_long",
 ]

pandas/core/arrays/string_.py

@@ -496,7 +496,7 @@ def max(self, axis=None, skipna: bool = True, **kwargs) -> Scalar:
         return self._wrap_reduction_result(axis, result)
 
     def value_counts(self, dropna: bool = True) -> Series:
-        from pandas import value_counts
+        from pandas.core.algorithms import value_counts
 
         result = value_counts(self._ndarray, dropna=dropna).astype("Int64")
         result.index = result.index.astype(self.dtype)

pandas/tests/api/test_api.py

@@ -210,6 +210,8 @@ def test_api(self):
             + self.funcs_to
             + self.private_modules
         )
+        checkthese.remove("value_counts")
+        # value_counts is deprecated, is in __all__ but not dir()
         self.check(namespace=pd, expected=checkthese, ignored=self.ignored)
 
     def test_api_all(self):