From 2a43b034960117dea90aad098e7253c1b110f8bf Mon Sep 17 00:00:00 2001 From: Jordan Murphy <35613487+jordan-d-murphy@users.noreply.github.com> Date: Sun, 10 Mar 2024 22:35:39 -0600 Subject: [PATCH] Fix PR01 errors for melt, option_context, read_fwf, reset_option (#57806) * Fix PR01 errors for melt, option_context, read_fwf, reset_option * removed shared docstring and fixed PR02 error in pandas.DataFrame.melt --- ci/code_checks.sh | 6 +- pandas/core/frame.py | 122 ++++++++++++++++++++++++++++++++- pandas/core/reshape/melt.py | 128 +++++++++++++++++++++++++++++++++-- pandas/core/shared_docs.py | 114 ------------------------------- pandas/io/parsers/readers.py | 5 ++ 5 files changed, 251 insertions(+), 124 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 84070b415e672..158650a7c54be 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -490,11 +490,7 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.errors.AbstractMethodError\ pandas.errors.UndefinedVariableError\ pandas.get_option\ - pandas.io.formats.style.Styler.to_excel\ - pandas.melt\ - pandas.option_context\ - pandas.read_fwf\ - pandas.reset_option # There should be no backslash in the final line, please keep this comment in the last ignored function + pandas.io.formats.style.Styler.to_excel # There should be no backslash in the final line, please keep this comment in the last ignored function RET=$(($RET + $?)) ; echo $MSG "DONE" MSG='Partially validate docstrings (PR07)' ; echo $MSG diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 2a6daf4bab937..d00c659392ef3 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -9682,7 +9682,6 @@ def unstack( return result.__finalize__(self, method="unstack") - @Appender(_shared_docs["melt"] % {"caller": "df.melt(", "other": "melt"}) def melt( self, id_vars=None, @@ -9692,6 +9691,127 @@ def melt( col_level: Level | None = None, ignore_index: bool = True, ) -> DataFrame: + """ + Unpivot DataFrame from wide to long format, optionally leaving identifiers set. + + This function is useful to massage a DataFrame into a format where one + or more columns are identifier variables (`id_vars`), while all other + columns, considered measured variables (`value_vars`), are "unpivoted" to + the row axis, leaving just two non-identifier columns, 'variable' and + 'value'. + + Parameters + ---------- + id_vars : scalar, tuple, list, or ndarray, optional + Column(s) to use as identifier variables. + value_vars : scalar, tuple, list, or ndarray, optional + Column(s) to unpivot. If not specified, uses all columns that + are not set as `id_vars`. + var_name : scalar, default None + Name to use for the 'variable' column. If None it uses + ``frame.columns.name`` or 'variable'. + value_name : scalar, default 'value' + Name to use for the 'value' column, can't be an existing column label. + col_level : scalar, optional + If columns are a MultiIndex then use this level to melt. + ignore_index : bool, default True + If True, original index is ignored. If False, original index is retained. + Index labels will be repeated as necessary. + + Returns + ------- + DataFrame + Unpivoted DataFrame. + + See Also + -------- + melt : Identical method. + pivot_table : Create a spreadsheet-style pivot table as a DataFrame. + DataFrame.pivot : Return reshaped DataFrame organized + by given index / column values. + DataFrame.explode : Explode a DataFrame from list-like + columns to long format. + + Notes + ----- + Reference :ref:`the user guide ` for more examples. + + Examples + -------- + >>> df = pd.DataFrame( + ... { + ... "A": {0: "a", 1: "b", 2: "c"}, + ... "B": {0: 1, 1: 3, 2: 5}, + ... "C": {0: 2, 1: 4, 2: 6}, + ... } + ... ) + >>> df + A B C + 0 a 1 2 + 1 b 3 4 + 2 c 5 6 + + >>> df.melt(id_vars=["A"], value_vars=["B"]) + A variable value + 0 a B 1 + 1 b B 3 + 2 c B 5 + + >>> df.melt(id_vars=["A"], value_vars=["B", "C"]) + A variable value + 0 a B 1 + 1 b B 3 + 2 c B 5 + 3 a C 2 + 4 b C 4 + 5 c C 6 + + The names of 'variable' and 'value' columns can be customized: + + >>> df.melt( + ... id_vars=["A"], + ... value_vars=["B"], + ... var_name="myVarname", + ... value_name="myValname", + ... ) + A myVarname myValname + 0 a B 1 + 1 b B 3 + 2 c B 5 + + Original index values can be kept around: + + >>> df.melt(id_vars=["A"], value_vars=["B", "C"], ignore_index=False) + A variable value + 0 a B 1 + 1 b B 3 + 2 c B 5 + 0 a C 2 + 1 b C 4 + 2 c C 6 + + If you have multi-index columns: + + >>> df.columns = [list("ABC"), list("DEF")] + >>> df + A B C + D E F + 0 a 1 2 + 1 b 3 4 + 2 c 5 6 + + >>> df.melt(col_level=0, id_vars=["A"], value_vars=["B"]) + A variable value + 0 a B 1 + 1 b B 3 + 2 c B 5 + + >>> df.melt(id_vars=[("A", "D")], value_vars=[("B", "E")]) + (A, D) variable_0 variable_1 value + 0 a B E 1 + 1 b B E 3 + 2 c B E 5 + """ return melt( self, id_vars=id_vars, diff --git a/pandas/core/reshape/melt.py b/pandas/core/reshape/melt.py index 7b8ef8da3ab46..24a070a536150 100644 --- a/pandas/core/reshape/melt.py +++ b/pandas/core/reshape/melt.py @@ -5,8 +5,6 @@ import numpy as np -from pandas.util._decorators import Appender - from pandas.core.dtypes.common import is_list_like from pandas.core.dtypes.concat import concat_compat from pandas.core.dtypes.missing import notna @@ -15,7 +13,6 @@ from pandas.core.indexes.api import MultiIndex from pandas.core.reshape.concat import concat from pandas.core.reshape.util import tile_compat -from pandas.core.shared_docs import _shared_docs from pandas.core.tools.numeric import to_numeric if TYPE_CHECKING: @@ -40,7 +37,6 @@ def ensure_list_vars(arg_vars, variable: str, columns) -> list: return [] -@Appender(_shared_docs["melt"] % {"caller": "pd.melt(df, ", "other": "DataFrame.melt"}) def melt( frame: DataFrame, id_vars=None, @@ -50,6 +46,130 @@ def melt( col_level=None, ignore_index: bool = True, ) -> DataFrame: + """ + Unpivot a DataFrame from wide to long format, optionally leaving identifiers set. + + This function is useful to massage a DataFrame into a format where one + or more columns are identifier variables (`id_vars`), while all other + columns, considered measured variables (`value_vars`), are "unpivoted" to + the row axis, leaving just two non-identifier columns, 'variable' and + 'value'. + + Parameters + ---------- + frame : DataFrame + The DataFrame to unpivot. + id_vars : scalar, tuple, list, or ndarray, optional + Column(s) to use as identifier variables. + value_vars : scalar, tuple, list, or ndarray, optional + Column(s) to unpivot. If not specified, uses all columns that + are not set as `id_vars`. + var_name : scalar, default None + Name to use for the 'variable' column. If None it uses + ``frame.columns.name`` or 'variable'. + value_name : scalar, default 'value' + Name to use for the 'value' column, can't be an existing column label. + col_level : scalar, optional + If columns are a MultiIndex then use this level to melt. + ignore_index : bool, default True + If True, original index is ignored. If False, the original index is retained. + Index labels will be repeated as necessary. + + Returns + ------- + DataFrame + Unpivoted DataFrame. + + See Also + -------- + DataFrame.melt : Identical method. + pivot_table : Create a spreadsheet-style pivot table as a DataFrame. + DataFrame.pivot : Return reshaped DataFrame organized + by given index / column values. + DataFrame.explode : Explode a DataFrame from list-like + columns to long format. + + Notes + ----- + Reference :ref:`the user guide ` for more examples. + + Examples + -------- + >>> df = pd.DataFrame( + ... { + ... "A": {0: "a", 1: "b", 2: "c"}, + ... "B": {0: 1, 1: 3, 2: 5}, + ... "C": {0: 2, 1: 4, 2: 6}, + ... } + ... ) + >>> df + A B C + 0 a 1 2 + 1 b 3 4 + 2 c 5 6 + + >>> pd.melt(df, id_vars=["A"], value_vars=["B"]) + A variable value + 0 a B 1 + 1 b B 3 + 2 c B 5 + + >>> pd.melt(df, id_vars=["A"], value_vars=["B", "C"]) + A variable value + 0 a B 1 + 1 b B 3 + 2 c B 5 + 3 a C 2 + 4 b C 4 + 5 c C 6 + + The names of 'variable' and 'value' columns can be customized: + + >>> pd.melt( + ... df, + ... id_vars=["A"], + ... value_vars=["B"], + ... var_name="myVarname", + ... value_name="myValname", + ... ) + A myVarname myValname + 0 a B 1 + 1 b B 3 + 2 c B 5 + + Original index values can be kept around: + + >>> pd.melt(df, id_vars=["A"], value_vars=["B", "C"], ignore_index=False) + A variable value + 0 a B 1 + 1 b B 3 + 2 c B 5 + 0 a C 2 + 1 b C 4 + 2 c C 6 + + If you have multi-index columns: + + >>> df.columns = [list("ABC"), list("DEF")] + >>> df + A B C + D E F + 0 a 1 2 + 1 b 3 4 + 2 c 5 6 + + >>> pd.melt(df, col_level=0, id_vars=["A"], value_vars=["B"]) + A variable value + 0 a B 1 + 1 b B 3 + 2 c B 5 + + >>> pd.melt(df, id_vars=[("A", "D")], value_vars=[("B", "E")]) + (A, D) variable_0 variable_1 value + 0 a B E 1 + 1 b B E 3 + 2 c B E 5 + """ if value_name in frame.columns: raise ValueError( f"value_name ({value_name}) cannot match an element in " diff --git a/pandas/core/shared_docs.py b/pandas/core/shared_docs.py index 06621f7127da3..15aa210a09d6d 100644 --- a/pandas/core/shared_docs.py +++ b/pandas/core/shared_docs.py @@ -186,120 +186,6 @@ they compare. See the user guide linked above for more details. """ -_shared_docs["melt"] = """ -Unpivot a DataFrame from wide to long format, optionally leaving identifiers set. - -This function is useful to massage a DataFrame into a format where one -or more columns are identifier variables (`id_vars`), while all other -columns, considered measured variables (`value_vars`), are "unpivoted" to -the row axis, leaving just two non-identifier columns, 'variable' and -'value'. - -Parameters ----------- -id_vars : scalar, tuple, list, or ndarray, optional - Column(s) to use as identifier variables. -value_vars : scalar, tuple, list, or ndarray, optional - Column(s) to unpivot. If not specified, uses all columns that - are not set as `id_vars`. -var_name : scalar, default None - Name to use for the 'variable' column. If None it uses - ``frame.columns.name`` or 'variable'. -value_name : scalar, default 'value' - Name to use for the 'value' column, can't be an existing column label. -col_level : scalar, optional - If columns are a MultiIndex then use this level to melt. -ignore_index : bool, default True - If True, original index is ignored. If False, the original index is retained. - Index labels will be repeated as necessary. - -Returns -------- -DataFrame - Unpivoted DataFrame. - -See Also --------- -%(other)s : Identical method. -pivot_table : Create a spreadsheet-style pivot table as a DataFrame. -DataFrame.pivot : Return reshaped DataFrame organized - by given index / column values. -DataFrame.explode : Explode a DataFrame from list-like - columns to long format. - -Notes ------ -Reference :ref:`the user guide ` for more examples. - -Examples --------- ->>> df = pd.DataFrame({'A': {0: 'a', 1: 'b', 2: 'c'}, -... 'B': {0: 1, 1: 3, 2: 5}, -... 'C': {0: 2, 1: 4, 2: 6}}) ->>> df - A B C -0 a 1 2 -1 b 3 4 -2 c 5 6 - ->>> %(caller)sid_vars=['A'], value_vars=['B']) - A variable value -0 a B 1 -1 b B 3 -2 c B 5 - ->>> %(caller)sid_vars=['A'], value_vars=['B', 'C']) - A variable value -0 a B 1 -1 b B 3 -2 c B 5 -3 a C 2 -4 b C 4 -5 c C 6 - -The names of 'variable' and 'value' columns can be customized: - ->>> %(caller)sid_vars=['A'], value_vars=['B'], -... var_name='myVarname', value_name='myValname') - A myVarname myValname -0 a B 1 -1 b B 3 -2 c B 5 - -Original index values can be kept around: - ->>> %(caller)sid_vars=['A'], value_vars=['B', 'C'], ignore_index=False) - A variable value -0 a B 1 -1 b B 3 -2 c B 5 -0 a C 2 -1 b C 4 -2 c C 6 - -If you have multi-index columns: - ->>> df.columns = [list('ABC'), list('DEF')] ->>> df - A B C - D E F -0 a 1 2 -1 b 3 4 -2 c 5 6 - ->>> %(caller)scol_level=0, id_vars=['A'], value_vars=['B']) - A variable value -0 a B 1 -1 b B 3 -2 c B 5 - ->>> %(caller)sid_vars=[('A', 'D')], value_vars=[('B', 'E')]) - (A, D) variable_0 variable_1 value -0 a B E 1 -1 b B E 3 -2 c B E 5 -""" - _shared_docs["transform"] = """ Call ``func`` on self producing a {klass} with the same axis shape as self. diff --git a/pandas/io/parsers/readers.py b/pandas/io/parsers/readers.py index 539d9abf84f90..9ce169c3fe880 100644 --- a/pandas/io/parsers/readers.py +++ b/pandas/io/parsers/readers.py @@ -1155,6 +1155,11 @@ def read_fwf( infer_nrows : int, default 100 The number of rows to consider when letting the parser determine the `colspecs`. + iterator : bool, default False + Return ``TextFileReader`` object for iteration or getting chunks with + ``get_chunk()``. + chunksize : int, optional + Number of lines to read from the file per chunk. **kwds : optional Optional keyword arguments can be passed to ``TextFileReader``.