We are currently solving the following issue within our repository. Here is the issue text:
--- BEGIN ISSUE ---
[DOC] Clarify original-dataframe mutation behavior in pyjanitor function docstrings
# Brief Description of Fix
Currently, some pyjanitor functions mutate the original dataframe and others return a copy. Solutions are heavily discussed in #79 but no conclusion has been reached. At the moment, it is unclear, without experimentation from the user, which behavior applies in each function. 

In the interim, I propose to explicitly clarify this behavior in each function's docstring so the user has a clear idea regarding the function's mutating behavior. Below is a sample of what this could look like for `.clean_names()`:

"""
Clean column names.
    Takes all column names, converts them to lowercase, then replaces all
    spaces with underscores. <b>Does not mutate original dataframe.</b>
"""

Happy to add this line somewhere else in the docstring if inappropriate here. 

- [Link to documentation page](https://pyjanitor.readthedocs.io/reference/index.html)
- [Link to exact file to be edited](https://github.com/ericmjl/pyjanitor/blob/dev/janitor/functions.py)


--- END ISSUE ---

Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
--- BEGIN FILES ---
Path: `janitor/finance.py`
Content:
```
1 """
2 Finance-specific data cleaning functions.
3 """
4 
5 import json
6 from datetime import date, datetime
7 from functools import lru_cache
8 
9 import pandas as pd
10 import pandas_flavor as pf
11 import requests
12 
13 from janitor import check
14 
15 from .utils import deprecated_alias
16 
17 currency_set = {
18     "AUD",
19     "BGN",
20     "BRL",
21     "CAD",
22     "CHF",
23     "CNY",
24     "CZK",
25     "DKK",
26     "EUR",
27     "GBP",
28     "HKD",
29     "HRK",
30     "HUF",
31     "IDR",
32     "ILS",
33     "INR",
34     "ISK",
35     "JPY",
36     "KRW",
37     "MXN",
38     "MYR",
39     "NOK",
40     "NZD",
41     "PHP",
42     "PLN",
43     "RON",
44     "RUB",
45     "SEK",
46     "SGD",
47     "THB",
48     "TRY",
49     "USD",
50     "ZAR",
51 }
52 
53 
54 def _check_currency(currency: str):
55     if currency not in currency_set:
56         raise ValueError(
57             f"currency {currency} not in supported currency set, "
58             f"{currency_set}"
59         )
60 
61 
62 @lru_cache(maxsize=32)
63 def _convert_currency(
64     from_currency: str = None,
65     to_currency: str = None,
66     historical_date: date = None,
67 ):
68     """
69     Currency conversion for Pandas DataFrame column.
70 
71     Helper function for `convert_currency` method.
72 
73     The API used is: https://exchangeratesapi.io/
74     """
75 
76     url = "https://api.exchangeratesapi.io"
77 
78     if historical_date:
79         check("historical_date", historical_date, [datetime, date])
80         if isinstance(historical_date, datetime):
81             if historical_date < datetime(1999, 1, 4):
82                 raise ValueError(
83                     "historical_date:datetime must be later than 1999-01-04!"
84                 )
85             string_date = str(historical_date)[:10]
86         else:
87             if historical_date < date(1999, 1, 4):
88                 raise ValueError(
89                     "historical_date:date must be later than 1999-01-04!"
90                 )
91             string_date = str(historical_date)
92         url = url + "/%s" % string_date
93     else:
94         url = url + "/latest"
95 
96     _check_currency(from_currency)
97     _check_currency(to_currency)
98 
99     payload = {"base": from_currency, "symbols": to_currency}
100 
101     result = requests.get(url, params=payload)
102 
103     if result.status_code != 200:
104         raise ConnectionError(
105             "Exchange Rate API failed to receive a 200 "
106             "response from the server. "
107             "Please try again later."
108         )
109 
110     currency_dict = json.loads(result.text)
111     rate = currency_dict["rates"][to_currency]
112     return rate
113 
114 
115 @pf.register_dataframe_method
116 @deprecated_alias(colname="column_name")
117 def convert_currency(
118     df: pd.DataFrame,
119     column_name: str = None,
120     from_currency: str = None,
121     to_currency: str = None,
122     historical_date: date = None,
123     make_new_column: bool = False,
124 ) -> pd.DataFrame:
125     """
126     Converts a column from one currency to another, with an option to
127     convert based on historical exchange values.
128 
129     :param df: A pandas dataframe.
130     :param column_name: Name of the new column. Should be a string, in order
131         for the column name to be compatible with the Feather binary
132         format (this is a useful thing to have).
133     :param from_currency: The base currency to convert from.
134         May be any of: currency_set = {"AUD", "BGN", "BRL", "CAD", "CHF",
135         "CNY", "CZK", "DKK", "EUR", "GBP", "HKD", "HRK", "HUF", "IDR",
136         "ILS", "INR", "ISK", "JPY", "KRW", "MXN", "MYR", "NOK", "NZD",
137         "PHP", "PLN", "RON", "RUB", "SEK", "SGD", "THB", "TRY", "USD",
138         "ZAR"}
139     :param to_currency: The target currency to convert to.
140         May be any of: currency_set = {"AUD", "BGN", "BRL", "CAD", "CHF",
141         "CNY", "CZK", "DKK", "EUR", "GBP", "HKD", "HRK", "HUF", "IDR",
142         "ILS", "INR", "ISK", "JPY", "KRW", "MXN", "MYR", "NOK", "NZD",
143         "PHP", "PLN", "RON", "RUB", "SEK", "SGD", "THB", "TRY", "USD",
144         "ZAR"}
145     :param historical_date: If supplied, get exchange rate on a certain\
146         date. If not supplied, get the latest exchange rate. The exchange\
147         rates go back to Jan. 4, 1999.
148     :param make_new_column: Generates new column for converted currency if
149         True, otherwise, converts currency in place.
150 
151     :Setup:
152 
153     .. code-block:: python
154 
155         import pandas as pd
156         import janitor
157         from datetime import date
158 
159         data_dict = {
160             "a": [1.23452345, 2.456234, 3.2346125] * 3,
161             "Bell__Chart": [1/3, 2/7, 3/2] * 3,
162             "decorated-elephant": [1/234, 2/13, 3/167] * 3,
163             "animals": ["rabbit", "leopard", "lion"] * 3,
164             "cities": ["Cambridge", "Shanghai", "Basel"] * 3,
165         }
166 
167         example_dataframe = pd.DataFrame(data_dict)
168 
169     :Example: Converting a column from one currency to another using rates
170 
171     from 01/01/2018:
172 
173     .. code-block:: python
174 
175         example_dataframe.convert_currency('a', from_currency='USD',
176         to_currency='EUR', historical_date=date(2018,1,1))
177 
178     :Output:
179 
180     .. code-block:: python
181 
182                     a  Bell__Chart  decorated-elephant  animals     cities
183         0  1.029370     0.333333            0.004274   rabbit  Cambridge
184         1  2.048056     0.285714            0.153846  leopard   Shanghai
185         2  2.697084     1.500000            0.017964     lion      Basel
186         3  1.029370     0.333333            0.004274   rabbit  Cambridge
187         4  2.048056     0.285714            0.153846  leopard   Shanghai
188         5  2.697084     1.500000            0.017964     lion      Basel
189         6  1.029370     0.333333            0.004274   rabbit  Cambridge
190         7  2.048056     0.285714            0.153846  leopard   Shanghai
191         8  2.697084     1.500000            0.017964     lion      Basel
192 
193     """
194 
195     rate = _convert_currency(from_currency, to_currency, historical_date)
196 
197     if make_new_column:
198         new_column_name = column_name + "_" + to_currency
199         df[new_column_name] = df[column_name] * rate
200 
201     else:
202         df[column_name] = df[column_name] * rate
203 
204     return df
205
```
--- END FILES ---

Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.

Here is an example:

```diff
diff --git a/examples/server_async.py b/examples/server_async.py
--- a/examples/server_async.py
+++ b/examples/server_async.py
@@ -313,4 +313,4 @@
 
 
 if __name__ == "__main__":
-    asyncio.run(run_async_server("."), debug=True)
+    asyncio.run(run_async_server(), debug=True)
diff --git a/examples/server_sync.py b/examples/server_sync.py
--- a/examples/server_sync.py
+++ b/examples/server_sync.py
@@ -313,5 +313,5 @@
 
 
 if __name__ == "__main__":
-    server = run_sync_server(".")
+    server = run_sync_server()
     server.shutdown()

```

diff --git a/janitor/finance.py b/janitor/finance.py
--- a/janitor/finance.py
+++ b/janitor/finance.py
@@ -126,6 +126,8 @@
     Converts a column from one currency to another, with an option to
     convert based on historical exchange values.
 
+    This method mutates the original DataFrame.
+
     :param df: A pandas dataframe.
     :param column_name: Name of the new column. Should be a string, in order
         for the column name to be compatible with the Feather binary

{"golden_diff": "diff --git a/janitor/finance.py b/janitor/finance.py\n--- a/janitor/finance.py\n+++ b/janitor/finance.py\n@@ -126,6 +126,8 @@\n     Converts a column from one currency to another, with an option to\n     convert based on historical exchange values.\n \n+    This method mutates the original DataFrame.\n+\n     :param df: A pandas dataframe.\n     :param column_name: Name of the new column. Should be a string, in order\n         for the column name to be compatible with the Feather binary\n", "issue": "[DOC] Clarify original-dataframe mutation behavior in pyjanitor function docstrings\n# Brief Description of Fix\r\nCurrently, some pyjanitor functions mutate the original dataframe and others return a copy. Solutions are heavily discussed in #79 but no conclusion has been reached. At the moment, it is unclear, without experimentation from the user, which behavior applies in each function. \r\n\r\nIn the interim, I propose to explicitly clarify this behavior in each function's docstring so the user has a clear idea regarding the function's mutating behavior. Below is a sample of what this could look like for `.clean_names()`:\r\n\r\n\"\"\"\r\nClean column names.\r\n    Takes all column names, converts them to lowercase, then replaces all\r\n    spaces with underscores. <b>Does not mutate original dataframe.</b>\r\n\"\"\"\r\n\r\nHappy to add this line somewhere else in the docstring if inappropriate here. \r\n\r\n- [Link to documentation page](https://pyjanitor.readthedocs.io/reference/index.html)\r\n- [Link to exact file to be edited](https://github.com/ericmjl/pyjanitor/blob/dev/janitor/functions.py)\r\n\n", "before_files": [{"content": "\"\"\"\nFinance-specific data cleaning functions.\n\"\"\"\n\nimport json\nfrom datetime import date, datetime\nfrom functools import lru_cache\n\nimport pandas as pd\nimport pandas_flavor as pf\nimport requests\n\nfrom janitor import check\n\nfrom .utils import deprecated_alias\n\ncurrency_set = {\n    \"AUD\",\n    \"BGN\",\n    \"BRL\",\n    \"CAD\",\n    \"CHF\",\n    \"CNY\",\n    \"CZK\",\n    \"DKK\",\n    \"EUR\",\n    \"GBP\",\n    \"HKD\",\n    \"HRK\",\n    \"HUF\",\n    \"IDR\",\n    \"ILS\",\n    \"INR\",\n    \"ISK\",\n    \"JPY\",\n    \"KRW\",\n    \"MXN\",\n    \"MYR\",\n    \"NOK\",\n    \"NZD\",\n    \"PHP\",\n    \"PLN\",\n    \"RON\",\n    \"RUB\",\n    \"SEK\",\n    \"SGD\",\n    \"THB\",\n    \"TRY\",\n    \"USD\",\n    \"ZAR\",\n}\n\n\ndef _check_currency(currency: str):\n    if currency not in currency_set:\n        raise ValueError(\n            f\"currency {currency} not in supported currency set, \"\n            f\"{currency_set}\"\n        )\n\n\n@lru_cache(maxsize=32)\ndef _convert_currency(\n    from_currency: str = None,\n    to_currency: str = None,\n    historical_date: date = None,\n):\n    \"\"\"\n    Currency conversion for Pandas DataFrame column.\n\n    Helper function for `convert_currency` method.\n\n    The API used is: https://exchangeratesapi.io/\n    \"\"\"\n\n    url = \"https://api.exchangeratesapi.io\"\n\n    if historical_date:\n        check(\"historical_date\", historical_date, [datetime, date])\n        if isinstance(historical_date, datetime):\n            if historical_date < datetime(1999, 1, 4):\n                raise ValueError(\n                    \"historical_date:datetime must be later than 1999-01-04!\"\n                )\n            string_date = str(historical_date)[:10]\n        else:\n            if historical_date < date(1999, 1, 4):\n                raise ValueError(\n                    \"historical_date:date must be later than 1999-01-04!\"\n                )\n            string_date = str(historical_date)\n        url = url + \"/%s\" % string_date\n    else:\n        url = url + \"/latest\"\n\n    _check_currency(from_currency)\n    _check_currency(to_currency)\n\n    payload = {\"base\": from_currency, \"symbols\": to_currency}\n\n    result = requests.get(url, params=payload)\n\n    if result.status_code != 200:\n        raise ConnectionError(\n            \"Exchange Rate API failed to receive a 200 \"\n            \"response from the server. \"\n            \"Please try again later.\"\n        )\n\n    currency_dict = json.loads(result.text)\n    rate = currency_dict[\"rates\"][to_currency]\n    return rate\n\n\n@pf.register_dataframe_method\n@deprecated_alias(colname=\"column_name\")\ndef convert_currency(\n    df: pd.DataFrame,\n    column_name: str = None,\n    from_currency: str = None,\n    to_currency: str = None,\n    historical_date: date = None,\n    make_new_column: bool = False,\n) -> pd.DataFrame:\n    \"\"\"\n    Converts a column from one currency to another, with an option to\n    convert based on historical exchange values.\n\n    :param df: A pandas dataframe.\n    :param column_name: Name of the new column. Should be a string, in order\n        for the column name to be compatible with the Feather binary\n        format (this is a useful thing to have).\n    :param from_currency: The base currency to convert from.\n        May be any of: currency_set = {\"AUD\", \"BGN\", \"BRL\", \"CAD\", \"CHF\",\n        \"CNY\", \"CZK\", \"DKK\", \"EUR\", \"GBP\", \"HKD\", \"HRK\", \"HUF\", \"IDR\",\n        \"ILS\", \"INR\", \"ISK\", \"JPY\", \"KRW\", \"MXN\", \"MYR\", \"NOK\", \"NZD\",\n        \"PHP\", \"PLN\", \"RON\", \"RUB\", \"SEK\", \"SGD\", \"THB\", \"TRY\", \"USD\",\n        \"ZAR\"}\n    :param to_currency: The target currency to convert to.\n        May be any of: currency_set = {\"AUD\", \"BGN\", \"BRL\", \"CAD\", \"CHF\",\n        \"CNY\", \"CZK\", \"DKK\", \"EUR\", \"GBP\", \"HKD\", \"HRK\", \"HUF\", \"IDR\",\n        \"ILS\", \"INR\", \"ISK\", \"JPY\", \"KRW\", \"MXN\", \"MYR\", \"NOK\", \"NZD\",\n        \"PHP\", \"PLN\", \"RON\", \"RUB\", \"SEK\", \"SGD\", \"THB\", \"TRY\", \"USD\",\n        \"ZAR\"}\n    :param historical_date: If supplied, get exchange rate on a certain\\\n        date. If not supplied, get the latest exchange rate. The exchange\\\n        rates go back to Jan. 4, 1999.\n    :param make_new_column: Generates new column for converted currency if\n        True, otherwise, converts currency in place.\n\n    :Setup:\n\n    .. code-block:: python\n\n        import pandas as pd\n        import janitor\n        from datetime import date\n\n        data_dict = {\n            \"a\": [1.23452345, 2.456234, 3.2346125] * 3,\n            \"Bell__Chart\": [1/3, 2/7, 3/2] * 3,\n            \"decorated-elephant\": [1/234, 2/13, 3/167] * 3,\n            \"animals\": [\"rabbit\", \"leopard\", \"lion\"] * 3,\n            \"cities\": [\"Cambridge\", \"Shanghai\", \"Basel\"] * 3,\n        }\n\n        example_dataframe = pd.DataFrame(data_dict)\n\n    :Example: Converting a column from one currency to another using rates\n\n    from 01/01/2018:\n\n    .. code-block:: python\n\n        example_dataframe.convert_currency('a', from_currency='USD',\n        to_currency='EUR', historical_date=date(2018,1,1))\n\n    :Output:\n\n    .. code-block:: python\n\n                    a  Bell__Chart  decorated-elephant  animals     cities\n        0  1.029370     0.333333            0.004274   rabbit  Cambridge\n        1  2.048056     0.285714            0.153846  leopard   Shanghai\n        2  2.697084     1.500000            0.017964     lion      Basel\n        3  1.029370     0.333333            0.004274   rabbit  Cambridge\n        4  2.048056     0.285714            0.153846  leopard   Shanghai\n        5  2.697084     1.500000            0.017964     lion      Basel\n        6  1.029370     0.333333            0.004274   rabbit  Cambridge\n        7  2.048056     0.285714            0.153846  leopard   Shanghai\n        8  2.697084     1.500000            0.017964     lion      Basel\n\n    \"\"\"\n\n    rate = _convert_currency(from_currency, to_currency, historical_date)\n\n    if make_new_column:\n        new_column_name = column_name + \"_\" + to_currency\n        df[new_column_name] = df[column_name] * rate\n\n    else:\n        df[column_name] = df[column_name] * rate\n\n    return df\n", "path": "janitor/finance.py"}], "after_files": [{"content": "\"\"\"\nFinance-specific data cleaning functions.\n\"\"\"\n\nimport json\nfrom datetime import date, datetime\nfrom functools import lru_cache\n\nimport pandas as pd\nimport pandas_flavor as pf\nimport requests\n\nfrom janitor import check\n\nfrom .utils import deprecated_alias\n\ncurrency_set = {\n    \"AUD\",\n    \"BGN\",\n    \"BRL\",\n    \"CAD\",\n    \"CHF\",\n    \"CNY\",\n    \"CZK\",\n    \"DKK\",\n    \"EUR\",\n    \"GBP\",\n    \"HKD\",\n    \"HRK\",\n    \"HUF\",\n    \"IDR\",\n    \"ILS\",\n    \"INR\",\n    \"ISK\",\n    \"JPY\",\n    \"KRW\",\n    \"MXN\",\n    \"MYR\",\n    \"NOK\",\n    \"NZD\",\n    \"PHP\",\n    \"PLN\",\n    \"RON\",\n    \"RUB\",\n    \"SEK\",\n    \"SGD\",\n    \"THB\",\n    \"TRY\",\n    \"USD\",\n    \"ZAR\",\n}\n\n\ndef _check_currency(currency: str):\n    if currency not in currency_set:\n        raise ValueError(\n            f\"currency {currency} not in supported currency set, \"\n            f\"{currency_set}\"\n        )\n\n\n@lru_cache(maxsize=32)\ndef _convert_currency(\n    from_currency: str = None,\n    to_currency: str = None,\n    historical_date: date = None,\n):\n    \"\"\"\n    Currency conversion for Pandas DataFrame column.\n\n    Helper function for `convert_currency` method.\n\n    The API used is: https://exchangeratesapi.io/\n    \"\"\"\n\n    url = \"https://api.exchangeratesapi.io\"\n\n    if historical_date:\n        check(\"historical_date\", historical_date, [datetime, date])\n        if isinstance(historical_date, datetime):\n            if historical_date < datetime(1999, 1, 4):\n                raise ValueError(\n                    \"historical_date:datetime must be later than 1999-01-04!\"\n                )\n            string_date = str(historical_date)[:10]\n        else:\n            if historical_date < date(1999, 1, 4):\n                raise ValueError(\n                    \"historical_date:date must be later than 1999-01-04!\"\n                )\n            string_date = str(historical_date)\n        url = url + \"/%s\" % string_date\n    else:\n        url = url + \"/latest\"\n\n    _check_currency(from_currency)\n    _check_currency(to_currency)\n\n    payload = {\"base\": from_currency, \"symbols\": to_currency}\n\n    result = requests.get(url, params=payload)\n\n    if result.status_code != 200:\n        raise ConnectionError(\n            \"Exchange Rate API failed to receive a 200 \"\n            \"response from the server. \"\n            \"Please try again later.\"\n        )\n\n    currency_dict = json.loads(result.text)\n    rate = currency_dict[\"rates\"][to_currency]\n    return rate\n\n\n@pf.register_dataframe_method\n@deprecated_alias(colname=\"column_name\")\ndef convert_currency(\n    df: pd.DataFrame,\n    column_name: str = None,\n    from_currency: str = None,\n    to_currency: str = None,\n    historical_date: date = None,\n    make_new_column: bool = False,\n) -> pd.DataFrame:\n    \"\"\"\n    Converts a column from one currency to another, with an option to\n    convert based on historical exchange values.\n\n    This method mutates the original DataFrame.\n\n    :param df: A pandas dataframe.\n    :param column_name: Name of the new column. Should be a string, in order\n        for the column name to be compatible with the Feather binary\n        format (this is a useful thing to have).\n    :param from_currency: The base currency to convert from.\n        May be any of: currency_set = {\"AUD\", \"BGN\", \"BRL\", \"CAD\", \"CHF\",\n        \"CNY\", \"CZK\", \"DKK\", \"EUR\", \"GBP\", \"HKD\", \"HRK\", \"HUF\", \"IDR\",\n        \"ILS\", \"INR\", \"ISK\", \"JPY\", \"KRW\", \"MXN\", \"MYR\", \"NOK\", \"NZD\",\n        \"PHP\", \"PLN\", \"RON\", \"RUB\", \"SEK\", \"SGD\", \"THB\", \"TRY\", \"USD\",\n        \"ZAR\"}\n    :param to_currency: The target currency to convert to.\n        May be any of: currency_set = {\"AUD\", \"BGN\", \"BRL\", \"CAD\", \"CHF\",\n        \"CNY\", \"CZK\", \"DKK\", \"EUR\", \"GBP\", \"HKD\", \"HRK\", \"HUF\", \"IDR\",\n        \"ILS\", \"INR\", \"ISK\", \"JPY\", \"KRW\", \"MXN\", \"MYR\", \"NOK\", \"NZD\",\n        \"PHP\", \"PLN\", \"RON\", \"RUB\", \"SEK\", \"SGD\", \"THB\", \"TRY\", \"USD\",\n        \"ZAR\"}\n    :param historical_date: If supplied, get exchange rate on a certain\\\n        date. If not supplied, get the latest exchange rate. The exchange\\\n        rates go back to Jan. 4, 1999.\n    :param make_new_column: Generates new column for converted currency if\n        True, otherwise, converts currency in place.\n\n    :Setup:\n\n    .. code-block:: python\n\n        import pandas as pd\n        import janitor\n        from datetime import date\n\n        data_dict = {\n            \"a\": [1.23452345, 2.456234, 3.2346125] * 3,\n            \"Bell__Chart\": [1/3, 2/7, 3/2] * 3,\n            \"decorated-elephant\": [1/234, 2/13, 3/167] * 3,\n            \"animals\": [\"rabbit\", \"leopard\", \"lion\"] * 3,\n            \"cities\": [\"Cambridge\", \"Shanghai\", \"Basel\"] * 3,\n        }\n\n        example_dataframe = pd.DataFrame(data_dict)\n\n    :Example: Converting a column from one currency to another using rates\n\n    from 01/01/2018:\n\n    .. code-block:: python\n\n        example_dataframe.convert_currency('a', from_currency='USD',\n        to_currency='EUR', historical_date=date(2018,1,1))\n\n    :Output:\n\n    .. code-block:: python\n\n                    a  Bell__Chart  decorated-elephant  animals     cities\n        0  1.029370     0.333333            0.004274   rabbit  Cambridge\n        1  2.048056     0.285714            0.153846  leopard   Shanghai\n        2  2.697084     1.500000            0.017964     lion      Basel\n        3  1.029370     0.333333            0.004274   rabbit  Cambridge\n        4  2.048056     0.285714            0.153846  leopard   Shanghai\n        5  2.697084     1.500000            0.017964     lion      Basel\n        6  1.029370     0.333333            0.004274   rabbit  Cambridge\n        7  2.048056     0.285714            0.153846  leopard   Shanghai\n        8  2.697084     1.500000            0.017964     lion      Basel\n\n    \"\"\"\n\n    rate = _convert_currency(from_currency, to_currency, historical_date)\n\n    if make_new_column:\n        new_column_name = column_name + \"_\" + to_currency\n        df[new_column_name] = df[column_name] * rate\n\n    else:\n        df[column_name] = df[column_name] * rate\n\n    return df\n", "path": "janitor/finance.py"}]}