diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 4e3ba3526ee96..81a769d3073e0 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -13019,18 +13019,26 @@ def stack( axis, defined as one index or label, or a list of indices or labels. dropna : bool, default True - Whether to drop rows in the resulting Frame/Series with - missing values. Stacking a column level onto the index - axis can create combinations of index and column values - that are missing from the original dataframe. See Examples - section. + Whether to drop rows in the resulting stacked output that contain + all missing values. + + .. deprecated:: 3.0 + This parameter is deprecated and no longer has any effect. + It will be removed in a future version. sort : bool, default True - Whether to sort the levels of the resulting MultiIndex. - future_stack : bool, default True - Whether to use the new implementation that will replace the current - implementation in pandas 3.0. When True, dropna and sort have no impact - on the result and must remain unspecified. See :ref:`pandas 2.1.0 Release - notes ` for more details. + Whether to sort the index after stacking. + + .. deprecated:: 3.0 + This parameter is deprecated and no longer has any effect. + It will be removed in a future version. + future_stack : bool, default False + Whether to use the future stacking behavior, where only existing + combinations of column levels are included in the result. When False, + missing combinations may be generated in the stacked output. + + .. deprecated:: 3.0 + This parameter is deprecated and no longer has any effect. + It will be removed in a future version. Returns ------- @@ -13048,11 +13056,15 @@ def stack( Notes ----- - The function is named by analogy with a collection of books - being reorganized from being side by side on a horizontal - position (the columns of the dataframe) to being stacked - vertically on top of each other (in the index of the - dataframe). + Starting from pandas 3.0, ``stack`` always uses the new implementation + that previously required ``future_stack=True``. The parameters ``dropna``, + ``sort``, and ``future_stack`` are deprecated and no longer have any effect. + They will be removed in a future version of pandas. + + The function is named by analogy with a collection of books being + reorganized from lying side-by-side horizontally (the columns of the + DataFrame) to being stacked vertically on top of each other (in the + index of the DataFrame). Reference :ref:`the user guide ` for more examples. @@ -13107,10 +13119,10 @@ def stack( ... [[1.0, 2.0], [3.0, 4.0]], index=["cat", "dog"], columns=multicol2 ... ) - It is common to have missing values when stacking a dataframe - with multi-level columns, as the stacked dataframe typically - has more values than the original dataframe. Missing values - are filled with NaNs: + When stacking a DataFrame with multi-level columns, the new + implementation does not generate rows of missing values. The + result includes only combinations that exist in the original + data. >>> df_multi_level_cols2 weight height