[DEPR] Deprecate functions

CHANGELOG.md

@@ -6,6 +6,7 @@
 -   [INF] Extract docstrings tests from all tests. PR #1205 @Zeroto521
 -   [BUG] address the `TypeError` when importing v0.24.0 (issue #1201 @xujiboy and @joranbeasley)
 -   [INF] Fixed issue with missing PyPI README. PR #1216 @thatlittleboy
+-   [DEPR] Add deprecation warnings for `process_text`, `rename_column`, `rename_columns`, `filter_on`, `remove_columns`, `fill_direction`. #1045 @samukweku
 
 ## [v0.24.0] - 2022-11-12
 

janitor/functions/add_columns.py

@@ -1,12 +1,18 @@
 import pandas_flavor as pf
 
-from janitor.utils import check, deprecated_alias
+from janitor.utils import check, deprecated_alias, refactored_function
 import pandas as pd
 from typing import Union, List, Any, Tuple
 import numpy as np
 
 
 @pf.register_dataframe_method
+@refactored_function(
+    message=(
+        "This function will be deprecated in a 1.x release. "
+        "Please use `pd.DataFrame.assign` instead."
+    )
+)
 @deprecated_alias(col_name="column_name")
 def add_column(
     df: pd.DataFrame,
@@ -22,6 +28,11 @@ def add_column(
     df[column_name] = value
     ```
 
+    !!!note
+
+        This function will be deprecated in a 1.x release.
+        Please use `pd.DataFrame.assign` instead.
+
     Example: Add a column of constant values to the dataframe.
 
         >>> import pandas as pd
@@ -118,7 +129,17 @@ def add_column(
     return df
 
 
+message = "This function will be deprecated in a 1.x release. "
+message += "Kindly use `pd.DataFrame.assign` instead."
+
+
 @pf.register_dataframe_method
+@refactored_function(
+    message=(
+        "This function will be deprecated in a 1.x release. "
+        "Please use `pd.DataFrame.assign` instead."
+    )
+)
 def add_columns(
     df: pd.DataFrame,
     fill_remaining: bool = False,
@@ -139,6 +160,11 @@ def add_columns(
 
     Values passed can be scalar or iterable (list, ndarray, etc.)
 
+    !!!note
+
+        This function will be deprecated in a 1.x release.
+        Please use `pd.DataFrame.assign` instead.
+
     Example: Inserting two more columns into a dataframe.
 
         >>> import pandas as pd

janitor/functions/change_type.py

@@ -5,10 +5,16 @@
 import pandas as pd
 import pandas_flavor as pf
 
-from janitor.utils import deprecated_alias
+from janitor.utils import deprecated_alias, refactored_function
 
 
 @pf.register_dataframe_method
+@refactored_function(
+    message=(
+        "This function will be deprecated in a 1.x release. "
+        "Please use `pd.DataFrame.astype` instead."
+    )
+)
 @deprecated_alias(column="column_name")
 def change_type(
     df: pd.DataFrame,
@@ -18,60 +24,65 @@ def change_type(
 ) -> pd.DataFrame:
     """Change the type of a column.
 
-    This method does not mutate the original DataFrame.
+     This method does not mutate the original DataFrame.
 
-    Exceptions that are raised can be ignored. For example, if one has a mixed
-    dtype column that has non-integer strings and integers, and you want to
-    coerce everything to integers, you can optionally ignore the non-integer
-    strings and replace them with `NaN` or keep the original value.
+     Exceptions that are raised can be ignored. For example, if one has a mixed
+     dtype column that has non-integer strings and integers, and you want to
+     coerce everything to integers, you can optionally ignore the non-integer
+     strings and replace them with `NaN` or keep the original value.
 
-    Intended to be the method-chaining alternative to:
+     Intended to be the method-chaining alternative to:
 
-    ```python
-    df[col] = df[col].astype(dtype)
+     ```python
+     df[col] = df[col].astype(dtype)
     ```
 
-    Example: Change the type of a column.
+     !!!note
+
+         This function will be deprecated in a 1.x release.
+         Please use `pd.DataFrame.astype` instead.
+
+     Example: Change the type of a column.
+
+         >>> import pandas as pd
+         >>> import janitor
+         >>> df = pd.DataFrame({"col1": range(3), "col2": ["m", 5, True]})
+         >>> df
+            col1  col2
+         0     0     m
+         1     1     5
+         2     2  True
+         >>> df.change_type(
+         ...     "col1", dtype=str,
+         ... ).change_type(
+         ...     "col2", dtype=float, ignore_exception="fillna",
+         ... )
+           col1  col2
+         0    0   NaN
+         1    1   5.0
+         2    2   1.0
+
+     Example: Change the type of multiple columns.
+
+     Change the type of all columns, please use `DataFrame.astype` instead.
 
-        >>> import pandas as pd
-        >>> import janitor
-        >>> df = pd.DataFrame({"col1": range(3), "col2": ["m", 5, True]})
-        >>> df
+         >>> import pandas as pd
+         >>> import janitor
+         >>> df = pd.DataFrame({"col1": range(3), "col2": ["m", 5, True]})
+         >>> df.change_type(['col1', 'col2'], str)
            col1  col2
-        0     0     m
-        1     1     5
-        2     2  True
-        >>> df.change_type(
-        ...     "col1", dtype=str,
-        ... ).change_type(
-        ...     "col2", dtype=float, ignore_exception="fillna",
-        ... )
-          col1  col2
-        0    0   NaN
-        1    1   5.0
-        2    2   1.0
-
-    Example: Change the type of multiple columns.
-
-    Change the type of all columns, please use `DataFrame.astype` instead.
-
-        >>> import pandas as pd
-        >>> import janitor
-        >>> df = pd.DataFrame({"col1": range(3), "col2": ["m", 5, True]})
-        >>> df.change_type(['col1', 'col2'], str)
-          col1  col2
-        0    0     m
-        1    1     5
-        2    2  True
-
-    :param df: A pandas DataFrame.
-    :param column_name: The column(s) in the dataframe.
-    :param dtype: The datatype to convert to. Should be one of the standard
-        Python types, or a numpy datatype.
-    :param ignore_exception: one of `{False, "fillna", "keep_values"}`.
-    :returns: A pandas DataFrame with changed column types.
-    :raises ValueError: If unknown option provided for
-        `ignore_exception`.
+         0    0     m
+         1    1     5
+         2    2  True
+
+     :param df: A pandas DataFrame.
+     :param column_name: The column(s) in the dataframe.
+     :param dtype: The datatype to convert to. Should be one of the standard
+         Python types, or a numpy datatype.
+     :param ignore_exception: one of `{False, "fillna", "keep_values"}`.
+     :returns: A pandas DataFrame with changed column types.
+     :raises ValueError: If unknown option provided for
+         `ignore_exception`.
     """
 
     df = df.copy()  # avoid mutating the original DataFrame

janitor/functions/fill.py

@@ -5,11 +5,22 @@
 
 import pandas as pd
 import pandas_flavor as pf
-from janitor.utils import check, check_column, deprecated_alias
+from janitor.utils import (
+    check,
+    check_column,
+    deprecated_alias,
+    refactored_function,
+)
 from multipledispatch import dispatch
 
 
 @pf.register_dataframe_method
+@refactored_function(
+    message=(
+        "This function will be deprecated in a 1.x release. "
+        "Please use `pd.DataFrame.assign` instead."
+    )
+)
 def fill_direction(df: pd.DataFrame, **kwargs) -> pd.DataFrame:
     """
     Provide a method-chainable function for filling missing values
@@ -19,6 +30,10 @@ def fill_direction(df: pd.DataFrame, **kwargs) -> pd.DataFrame:
     and pairs the column name with one of `up`, `down`, `updown`,
     and `downup`.
 
+    !!!note
+
+        This function will be deprecated in a 1.x release.
+        Please use `pd.DataFrame.assign` instead.
 
     Example:
 
@@ -58,7 +73,7 @@ def fill_direction(df: pd.DataFrame, **kwargs) -> pd.DataFrame:
     :returns: A pandas DataFrame with modified column(s).
     :raises ValueError: if direction supplied is not one of `down`, `up`,
         `updown`, or `downup`.
-    """
+    """  # noqa: E501
 
     if not kwargs:
         return df
@@ -113,6 +128,10 @@ class _FILLTYPE(Enum):
 
 
 @pf.register_dataframe_method
+@refactored_function(
+    message="This function will be deprecated in a 1.x release. "
+    "Kindly use `jn.impute` instead."
+)
 @deprecated_alias(columns="column_names")
 def fill_empty(
     df: pd.DataFrame, column_names: Union[str, Iterable[str], Hashable], value
@@ -124,6 +143,11 @@ def fill_empty(
 
     This method mutates the original DataFrame.
 
+    !!!note
+
+        This function will be deprecated in a 1.x release.
+        Please use [`jn.impute`][janitor.functions.impute.impute] instead.
+
     Example:
 
         >>> import pandas as pd
@@ -160,6 +184,7 @@ def fill_empty(
     :param value: The value that replaces the `NaN` values.
     :returns: A pandas DataFrame with `NaN` values filled.
     """
+
     check_column(df, column_names)
     return _fill_empty(df, column_names, value=value)
 

janitor/functions/filter.py

@@ -6,7 +6,9 @@
 import numpy as np
 import pandas as pd
 import pandas_flavor as pf
-from janitor.utils import deprecated_alias
+from janitor.utils import deprecated_alias, refactored_function
+
+warnings.simplefilter("always", DeprecationWarning)
 
 
 @pf.register_dataframe_method
@@ -94,6 +96,12 @@ def filter_string(
 
 
 @pf.register_dataframe_method
+@refactored_function(
+    message=(
+        "This function will be deprecated in a 1.x release. "
+        "Please use `pd.DataFrame.query` instead."
+    )
+)
 def filter_on(
     df: pd.DataFrame,
     criteria: str,
@@ -113,6 +121,12 @@ def filter_on(
     df = df[df["score"] < 3]
     ```
 
+    !!!note
+
+        This function will be deprecated in a 1.x release.
+        Please use `pd.DataFrame.query` instead.
+
+
     Example: Filter students who failed an exam (scored less than 50).
 
         >>> import pandas as pd
@@ -140,6 +154,14 @@ def filter_on(
         retained instead.
     :returns: A filtered pandas DataFrame.
     """
+
+    warnings.warn(
+        "This function will be deprecated in a 1.x release. "
+        "Kindly use `pd.DataFrame.query` instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
     if complement:
         return df.query(f"not ({criteria})")
     return df.query(criteria)

janitor/functions/find_replace.py

@@ -1,15 +1,29 @@
 """Implementation for find_replace."""
 from typing import Dict
+from janitor.utils import refactored_function
+
 
 import pandas as pd
 import pandas_flavor as pf
 
 
 @pf.register_dataframe_method
+@refactored_function(
+    message=(
+        "This function will be deprecated in a 1.x release. "
+        "Please use `pd.DataFrame.replace` instead."
+    )
+)
 def find_replace(
     df: pd.DataFrame, match: str = "exact", **mappings
 ) -> pd.DataFrame:
     """
+
+    !!!note
+
+        This function will be deprecated in a 1.x release.
+        Please use `pd.DataFrame.replace` instead.
+
     Perform a find-and-replace action on provided columns.
 
     Depending on use case, users can choose either exact, full-value matching,

janitor/functions/groupby_agg.py

@@ -2,11 +2,17 @@
 import pandas_flavor as pf
 import pandas as pd
 
-from janitor.utils import deprecated_alias
+from janitor.utils import deprecated_alias, refactored_function
 
 
 @pf.register_dataframe_method
 @deprecated_alias(new_column="new_column_name", agg_column="agg_column_name")
+@refactored_function(
+    message=(
+        "This function will be deprecated in a 1.x release. "
+        "Please use `janitor.transform_column` instead."
+    )
+)
 def groupby_agg(
     df: pd.DataFrame,
     by: Union[List, Callable, str],
@@ -25,6 +31,13 @@ def groupby_agg(
     df = df.assign(...=df.groupby(...)[...].transform(...))
     ```
 
+    !!!note
+
+        This function will be deprecated in a 1.x release.
+        Please use
+        [`jn.transform_column`][janitor.functions.transform_columns.transform_column]
+        instead.
+
     Example: Basic usage.
 
         >>> import pandas as pd