Skip to content

Commit b451cc5

Browse files
samukwekuericmjl
samukweku
and
ericmjl
authored
[DEPR] Deprecate functions (#1212)
* deprecate functions * changelog * deprecate fill_empty * use refactored function decorator * deprecate fill_direction * update changelog * deprecate add_column, add_columns * deprecate join_apply * deprecate find_replace * deprecate toset * fix deprecation message * fix import failure * fix failure for toset doctest * add find_stack_level * fix message in refactored function * add deprecation warning for change_type * deprecate groupby_agg * deprecate groupby_agg Co-authored-by: Eric Ma <[email protected]>
1 parent 8d298c7 commit b451cc5

14 files changed

+291
-60
lines changed

‎CHANGELOG.md

+1
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
- [INF] Extract docstrings tests from all tests. PR #1205 @Zeroto521
77
- [BUG] address the `TypeError` when importing v0.24.0 (issue #1201 @xujiboy and @joranbeasley)
88
- [INF] Fixed issue with missing PyPI README. PR #1216 @thatlittleboy
9+
- [DEPR] Add deprecation warnings for `process_text`, `rename_column`, `rename_columns`, `filter_on`, `remove_columns`, `fill_direction`. #1045 @samukweku
910

1011
## [v0.24.0] - 2022-11-12
1112

‎janitor/functions/add_columns.py

+27-1
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
11
import pandas_flavor as pf
22

3-
from janitor.utils import check, deprecated_alias
3+
from janitor.utils import check, deprecated_alias, refactored_function
44
import pandas as pd
55
from typing import Union, List, Any, Tuple
66
import numpy as np
77

88

99
@pf.register_dataframe_method
10+
@refactored_function(
11+
message=(
12+
"This function will be deprecated in a 1.x release. "
13+
"Please use `pd.DataFrame.assign` instead."
14+
)
15+
)
1016
@deprecated_alias(col_name="column_name")
1117
def add_column(
1218
df: pd.DataFrame,
@@ -22,6 +28,11 @@ def add_column(
2228
df[column_name] = value
2329
```
2430
31+
!!!note
32+
33+
This function will be deprecated in a 1.x release.
34+
Please use `pd.DataFrame.assign` instead.
35+
2536
Example: Add a column of constant values to the dataframe.
2637
2738
>>> import pandas as pd
@@ -118,7 +129,17 @@ def add_column(
118129
return df
119130

120131

132+
message = "This function will be deprecated in a 1.x release. "
133+
message += "Kindly use `pd.DataFrame.assign` instead."
134+
135+
121136
@pf.register_dataframe_method
137+
@refactored_function(
138+
message=(
139+
"This function will be deprecated in a 1.x release. "
140+
"Please use `pd.DataFrame.assign` instead."
141+
)
142+
)
122143
def add_columns(
123144
df: pd.DataFrame,
124145
fill_remaining: bool = False,
@@ -139,6 +160,11 @@ def add_columns(
139160
140161
Values passed can be scalar or iterable (list, ndarray, etc.)
141162
163+
!!!note
164+
165+
This function will be deprecated in a 1.x release.
166+
Please use `pd.DataFrame.assign` instead.
167+
142168
Example: Inserting two more columns into a dataframe.
143169
144170
>>> import pandas as pd

‎janitor/functions/change_type.py

+59-48
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,16 @@
55
import pandas as pd
66
import pandas_flavor as pf
77

8-
from janitor.utils import deprecated_alias
8+
from janitor.utils import deprecated_alias, refactored_function
99

1010

1111
@pf.register_dataframe_method
12+
@refactored_function(
13+
message=(
14+
"This function will be deprecated in a 1.x release. "
15+
"Please use `pd.DataFrame.astype` instead."
16+
)
17+
)
1218
@deprecated_alias(column="column_name")
1319
def change_type(
1420
df: pd.DataFrame,
@@ -18,60 +24,65 @@ def change_type(
1824
) -> pd.DataFrame:
1925
"""Change the type of a column.
2026
21-
This method does not mutate the original DataFrame.
27+
This method does not mutate the original DataFrame.
2228
23-
Exceptions that are raised can be ignored. For example, if one has a mixed
24-
dtype column that has non-integer strings and integers, and you want to
25-
coerce everything to integers, you can optionally ignore the non-integer
26-
strings and replace them with `NaN` or keep the original value.
29+
Exceptions that are raised can be ignored. For example, if one has a mixed
30+
dtype column that has non-integer strings and integers, and you want to
31+
coerce everything to integers, you can optionally ignore the non-integer
32+
strings and replace them with `NaN` or keep the original value.
2733
28-
Intended to be the method-chaining alternative to:
34+
Intended to be the method-chaining alternative to:
2935
30-
```python
31-
df[col] = df[col].astype(dtype)
36+
```python
37+
df[col] = df[col].astype(dtype)
3238
```
3339
34-
Example: Change the type of a column.
40+
!!!note
41+
42+
This function will be deprecated in a 1.x release.
43+
Please use `pd.DataFrame.astype` instead.
44+
45+
Example: Change the type of a column.
46+
47+
>>> import pandas as pd
48+
>>> import janitor
49+
>>> df = pd.DataFrame({"col1": range(3), "col2": ["m", 5, True]})
50+
>>> df
51+
col1 col2
52+
0 0 m
53+
1 1 5
54+
2 2 True
55+
>>> df.change_type(
56+
... "col1", dtype=str,
57+
... ).change_type(
58+
... "col2", dtype=float, ignore_exception="fillna",
59+
... )
60+
col1 col2
61+
0 0 NaN
62+
1 1 5.0
63+
2 2 1.0
64+
65+
Example: Change the type of multiple columns.
66+
67+
Change the type of all columns, please use `DataFrame.astype` instead.
3568
36-
>>> import pandas as pd
37-
>>> import janitor
38-
>>> df = pd.DataFrame({"col1": range(3), "col2": ["m", 5, True]})
39-
>>> df
69+
>>> import pandas as pd
70+
>>> import janitor
71+
>>> df = pd.DataFrame({"col1": range(3), "col2": ["m", 5, True]})
72+
>>> df.change_type(['col1', 'col2'], str)
4073
col1 col2
41-
0 0 m
42-
1 1 5
43-
2 2 True
44-
>>> df.change_type(
45-
... "col1", dtype=str,
46-
... ).change_type(
47-
... "col2", dtype=float, ignore_exception="fillna",
48-
... )
49-
col1 col2
50-
0 0 NaN
51-
1 1 5.0
52-
2 2 1.0
53-
54-
Example: Change the type of multiple columns.
55-
56-
Change the type of all columns, please use `DataFrame.astype` instead.
57-
58-
>>> import pandas as pd
59-
>>> import janitor
60-
>>> df = pd.DataFrame({"col1": range(3), "col2": ["m", 5, True]})
61-
>>> df.change_type(['col1', 'col2'], str)
62-
col1 col2
63-
0 0 m
64-
1 1 5
65-
2 2 True
66-
67-
:param df: A pandas DataFrame.
68-
:param column_name: The column(s) in the dataframe.
69-
:param dtype: The datatype to convert to. Should be one of the standard
70-
Python types, or a numpy datatype.
71-
:param ignore_exception: one of `{False, "fillna", "keep_values"}`.
72-
:returns: A pandas DataFrame with changed column types.
73-
:raises ValueError: If unknown option provided for
74-
`ignore_exception`.
74+
0 0 m
75+
1 1 5
76+
2 2 True
77+
78+
:param df: A pandas DataFrame.
79+
:param column_name: The column(s) in the dataframe.
80+
:param dtype: The datatype to convert to. Should be one of the standard
81+
Python types, or a numpy datatype.
82+
:param ignore_exception: one of `{False, "fillna", "keep_values"}`.
83+
:returns: A pandas DataFrame with changed column types.
84+
:raises ValueError: If unknown option provided for
85+
`ignore_exception`.
7586
"""
7687

7788
df = df.copy() # avoid mutating the original DataFrame

‎janitor/functions/fill.py

+27-2
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,22 @@
55

66
import pandas as pd
77
import pandas_flavor as pf
8-
from janitor.utils import check, check_column, deprecated_alias
8+
from janitor.utils import (
9+
check,
10+
check_column,
11+
deprecated_alias,
12+
refactored_function,
13+
)
914
from multipledispatch import dispatch
1015

1116

1217
@pf.register_dataframe_method
18+
@refactored_function(
19+
message=(
20+
"This function will be deprecated in a 1.x release. "
21+
"Please use `pd.DataFrame.assign` instead."
22+
)
23+
)
1324
def fill_direction(df: pd.DataFrame, **kwargs) -> pd.DataFrame:
1425
"""
1526
Provide a method-chainable function for filling missing values
@@ -19,6 +30,10 @@ def fill_direction(df: pd.DataFrame, **kwargs) -> pd.DataFrame:
1930
and pairs the column name with one of `up`, `down`, `updown`,
2031
and `downup`.
2132
33+
!!!note
34+
35+
This function will be deprecated in a 1.x release.
36+
Please use `pd.DataFrame.assign` instead.
2237
2338
Example:
2439
@@ -58,7 +73,7 @@ def fill_direction(df: pd.DataFrame, **kwargs) -> pd.DataFrame:
5873
:returns: A pandas DataFrame with modified column(s).
5974
:raises ValueError: if direction supplied is not one of `down`, `up`,
6075
`updown`, or `downup`.
61-
"""
76+
""" # noqa: E501
6277

6378
if not kwargs:
6479
return df
@@ -113,6 +128,10 @@ class _FILLTYPE(Enum):
113128

114129

115130
@pf.register_dataframe_method
131+
@refactored_function(
132+
message="This function will be deprecated in a 1.x release. "
133+
"Kindly use `jn.impute` instead."
134+
)
116135
@deprecated_alias(columns="column_names")
117136
def fill_empty(
118137
df: pd.DataFrame, column_names: Union[str, Iterable[str], Hashable], value
@@ -124,6 +143,11 @@ def fill_empty(
124143
125144
This method mutates the original DataFrame.
126145
146+
!!!note
147+
148+
This function will be deprecated in a 1.x release.
149+
Please use [`jn.impute`][janitor.functions.impute.impute] instead.
150+
127151
Example:
128152
129153
>>> import pandas as pd
@@ -160,6 +184,7 @@ def fill_empty(
160184
:param value: The value that replaces the `NaN` values.
161185
:returns: A pandas DataFrame with `NaN` values filled.
162186
"""
187+
163188
check_column(df, column_names)
164189
return _fill_empty(df, column_names, value=value)
165190

‎janitor/functions/filter.py

+23-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@
66
import numpy as np
77
import pandas as pd
88
import pandas_flavor as pf
9-
from janitor.utils import deprecated_alias
9+
from janitor.utils import deprecated_alias, refactored_function
10+
11+
warnings.simplefilter("always", DeprecationWarning)
1012

1113

1214
@pf.register_dataframe_method
@@ -94,6 +96,12 @@ def filter_string(
9496

9597

9698
@pf.register_dataframe_method
99+
@refactored_function(
100+
message=(
101+
"This function will be deprecated in a 1.x release. "
102+
"Please use `pd.DataFrame.query` instead."
103+
)
104+
)
97105
def filter_on(
98106
df: pd.DataFrame,
99107
criteria: str,
@@ -113,6 +121,12 @@ def filter_on(
113121
df = df[df["score"] < 3]
114122
```
115123
124+
!!!note
125+
126+
This function will be deprecated in a 1.x release.
127+
Please use `pd.DataFrame.query` instead.
128+
129+
116130
Example: Filter students who failed an exam (scored less than 50).
117131
118132
>>> import pandas as pd
@@ -140,6 +154,14 @@ def filter_on(
140154
retained instead.
141155
:returns: A filtered pandas DataFrame.
142156
"""
157+
158+
warnings.warn(
159+
"This function will be deprecated in a 1.x release. "
160+
"Kindly use `pd.DataFrame.query` instead.",
161+
DeprecationWarning,
162+
stacklevel=2,
163+
)
164+
143165
if complement:
144166
return df.query(f"not ({criteria})")
145167
return df.query(criteria)

‎janitor/functions/find_replace.py

+14
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,29 @@
11
"""Implementation for find_replace."""
22
from typing import Dict
3+
from janitor.utils import refactored_function
4+
35

46
import pandas as pd
57
import pandas_flavor as pf
68

79

810
@pf.register_dataframe_method
11+
@refactored_function(
12+
message=(
13+
"This function will be deprecated in a 1.x release. "
14+
"Please use `pd.DataFrame.replace` instead."
15+
)
16+
)
917
def find_replace(
1018
df: pd.DataFrame, match: str = "exact", **mappings
1119
) -> pd.DataFrame:
1220
"""
21+
22+
!!!note
23+
24+
This function will be deprecated in a 1.x release.
25+
Please use `pd.DataFrame.replace` instead.
26+
1327
Perform a find-and-replace action on provided columns.
1428
1529
Depending on use case, users can choose either exact, full-value matching,

‎janitor/functions/groupby_agg.py

+14-1
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,17 @@
22
import pandas_flavor as pf
33
import pandas as pd
44

5-
from janitor.utils import deprecated_alias
5+
from janitor.utils import deprecated_alias, refactored_function
66

77

88
@pf.register_dataframe_method
99
@deprecated_alias(new_column="new_column_name", agg_column="agg_column_name")
10+
@refactored_function(
11+
message=(
12+
"This function will be deprecated in a 1.x release. "
13+
"Please use `janitor.transform_column` instead."
14+
)
15+
)
1016
def groupby_agg(
1117
df: pd.DataFrame,
1218
by: Union[List, Callable, str],
@@ -25,6 +31,13 @@ def groupby_agg(
2531
df = df.assign(...=df.groupby(...)[...].transform(...))
2632
```
2733
34+
!!!note
35+
36+
This function will be deprecated in a 1.x release.
37+
Please use
38+
[`jn.transform_column`][janitor.functions.transform_columns.transform_column]
39+
instead.
40+
2841
Example: Basic usage.
2942
3043
>>> import pandas as pd

0 commit comments

Comments
 (0)