Merge remote-tracking branch 'upstream/main' into ref/copy/deep_kw_only

Author: mroeschke

.github/workflows/unit-tests.yml

@@ -320,8 +320,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # Separate out macOS 13 and 14, since macOS 14 is arm64 only
-        os: [ubuntu-24.04, macOS-13, macOS-14, windows-2025]
+        os: [ubuntu-24.04, macos-15-intel, macos-15, windows-2025]
 
     timeout-minutes: 90
 

doc/source/user_guide/io.rst

@@ -303,8 +303,6 @@ compression : {``'infer'``, ``'gzip'``, ``'bz2'``, ``'zip'``, ``'xz'``, ``'zstd'
   As an example, the following could be passed for faster compression and to
   create a reproducible gzip archive:
   ``compression={'method': 'gzip', 'compresslevel': 1, 'mtime': 1}``.
-
-  .. versionchanged:: 1.2.0 Previous versions forwarded dict entries for 'gzip' to ``gzip.open``.
 thousands : str, default ``None``
   Thousands separator.
 decimal : str, default ``'.'``
@@ -1472,7 +1470,7 @@ rather than reading the entire file into memory, such as the following:
    table
 
 
-By specifying a ``chunksize`` to ``read_csv``, the return
+By specifying a ``chunksize`` to :func:`read_csv` as a context manager, the return
 value will be an iterable object of type ``TextFileReader``:
 
 .. ipython:: python
@@ -1482,10 +1480,6 @@ value will be an iterable object of type ``TextFileReader``:
        for chunk in reader:
            print(chunk)
 
-.. versionchanged:: 1.2
-
-  ``read_csv/json/sas`` return a context-manager when iterating through a file.
-
 Specifying ``iterator=True`` will also return the ``TextFileReader`` object:
 
 .. ipython:: python

doc/source/user_guide/visualization.rst

@@ -326,8 +326,6 @@ The ``by`` keyword can be specified to plot grouped histograms:
 
 In addition, the ``by`` keyword can also be specified in :meth:`DataFrame.plot.hist`.
 
-.. versionchanged:: 1.4.0
-
 .. ipython:: python
 
    data = pd.DataFrame(
@@ -480,8 +478,6 @@ columns:
 
 You could also create groupings with :meth:`DataFrame.plot.box`, for instance:
 
-.. versionchanged:: 1.4.0
-
 .. ipython:: python
    :suppress:
 

doc/source/whatsnew/v3.0.0.rst

@@ -740,6 +740,7 @@ Other Deprecations
 - Deprecated allowing strings representing full dates in :meth:`DataFrame.at_time` and :meth:`Series.at_time` (:issue:`50839`)
 - Deprecated backward-compatibility behavior for :meth:`DataFrame.select_dtypes` matching "str" dtype when ``np.object_`` is specified (:issue:`61916`)
 - Deprecated option "future.no_silent_downcasting", as it is no longer used. In a future version accessing this option will raise (:issue:`59502`)
+- Deprecated passing non-Index types to :meth:`Index.join`; explicitly convert to Index first (:issue:`62897`)
 - Deprecated silent casting of non-datetime 'other' to datetime in :meth:`Series.combine_first` (:issue:`62931`)
 - Deprecated slicing on a :class:`Series` or :class:`DataFrame` with a :class:`DatetimeIndex` using a ``datetime.date`` object, explicitly cast to :class:`Timestamp` instead (:issue:`35830`)
 - Deprecated support for the Dataframe Interchange Protocol (:issue:`56732`)
@@ -1199,6 +1200,7 @@ Reshaping
 - Bug in :meth:`DataFrame.combine` with non-unique columns incorrectly raising (:issue:`51340`)
 - Bug in :meth:`DataFrame.explode` producing incorrect result for :class:`pyarrow.large_list` type (:issue:`61091`)
 - Bug in :meth:`DataFrame.join` inconsistently setting result index name (:issue:`55815`)
+- Bug in :meth:`DataFrame.join` not producing the correct row order when joining with a list of Series/DataFrames (:issue:`62954`)
 - Bug in :meth:`DataFrame.join` when a :class:`DataFrame` with a :class:`MultiIndex` would raise an ``AssertionError`` when :attr:`MultiIndex.names` contained ``None``. (:issue:`58721`)
 - Bug in :meth:`DataFrame.merge` where merging on a column containing only ``NaN`` values resulted in an out-of-bounds array access (:issue:`59421`)
 - Bug in :meth:`Series.combine_first` incorrectly replacing ``None`` entries with ``NaN`` (:issue:`58977`)

pandas/core/arrays/categorical.py

@@ -2545,10 +2545,6 @@ def unique(self) -> Self:
         Return the ``Categorical`` which ``categories`` and ``codes`` are
         unique.
 
-        .. versionchanged:: 1.3.0
-
-            Previously, unused categories were dropped from the new categories.
-
         Returns
         -------
         Categorical

pandas/core/arrays/masked.py

@@ -1686,8 +1686,6 @@ def any(
         missing values are present, similar :ref:`Kleene logic <boolean.kleene>`
         is used as for logical operations.
 
-        .. versionchanged:: 1.4.0
-
         Parameters
         ----------
         skipna : bool, default True
@@ -1774,8 +1772,6 @@ def all(
         missing values are present, similar :ref:`Kleene logic <boolean.kleene>`
         is used as for logical operations.
 
-        .. versionchanged:: 1.4.0
-
         Parameters
         ----------
         skipna : bool, default True

pandas/core/arrays/string_.py

@@ -573,9 +573,7 @@ class StringArray(BaseStringArray, NumpyExtensionArray):  # type: ignore[misc]
            :meth:`pandas.array` with ``dtype="string"`` for a stable way of
            creating a `StringArray` from any sequence.
 
-        .. versionchanged:: 1.5.0
-
-           StringArray now accepts array-likes containing
+           StringArray accepts array-likes containing
            nan-likes(``None``, ``np.nan``) for the ``values`` parameter
            in addition to strings and :attr:`pandas.NA`
 

pandas/core/frame.py

@@ -554,8 +554,6 @@ class DataFrame(NDFrame, OpsMixin):
         If data is a dict containing one or more Series (possibly of different dtypes),
         ``copy=False`` will ensure that these inputs are not copied.
 
-        .. versionchanged:: 1.3.0
-
     See Also
     --------
     DataFrame.from_records : Constructor from tuples, also record arrays.
@@ -2686,17 +2684,13 @@ def to_stata(
             8 characters and values are repeated.
         {compression_options}
 
-            .. versionchanged:: 1.4.0 Zstandard support.
-
         {storage_options}
 
         value_labels : dict of dicts
             Dictionary containing columns as keys and dictionaries of column value
             to labels as values. Labels for a single variable must be 32,000
             characters or smaller.
 
-            .. versionadded:: 1.4.0
-
         Raises
         ------
         NotImplementedError
@@ -3534,8 +3528,6 @@ def to_xml(
             scripts and not later versions is currently supported.
         {compression_options}
 
-            .. versionchanged:: 1.4.0 Zstandard support.
-
         {storage_options}
 
         Returns
@@ -9487,13 +9479,6 @@ def groupby(
             when the result's index (and column) labels match the inputs, and
             are included otherwise.
 
-            .. versionchanged:: 1.5.0
-
-               Warns that ``group_keys`` will no longer be ignored when the
-               result from ``apply`` is a like-indexed Series or DataFrame.
-               Specify ``group_keys`` explicitly to include the group keys or
-               not.
-
             .. versionchanged:: 2.0.0
 
                ``group_keys`` now defaults to ``True``.
@@ -11408,12 +11393,18 @@ def join(
 
             # join indexes only using concat
             if can_concat:
-                if how == "left":
+                if how == "left" or how == "right":
                     res = concat(
                         frames, axis=1, join="outer", verify_integrity=True, sort=sort
                     )
-                    return res.reindex(self.index)
+                    index = self.index if how == "left" else frames[-1].index
+                    if sort:
+                        index = index.sort_values()
+                    result = res.reindex(index)
+                    return result
                 else:
+                    if how == "outer":
+                        sort = True
                     return concat(
                         frames, axis=1, join=how, verify_integrity=True, sort=sort
                     )
@@ -11424,6 +11415,7 @@ def join(
                 joined = merge(
                     joined,
                     frame,
+                    sort=sort,
                     how=how,
                     left_index=True,
                     right_index=True,

pandas/core/generic.py

@@ -2415,8 +2415,6 @@ def to_json(
             list-like.
         {compression_options}
 
-            .. versionchanged:: 1.4.0 Zstandard support.
-
         index : bool or None, default None
             The index is only used when 'orient' is 'split', 'index', 'column',
             or 'table'. Of these, 'index' and 'column' do not support
@@ -3850,12 +3848,6 @@ def to_csv(
             The newline character or character sequence to use in the output
             file. Defaults to `os.linesep`, which depends on the OS in which
             this method is called ('\\n' for linux, '\\r\\n' for Windows, i.e.).
-
-            .. versionchanged:: 1.5.0
-
-                Previously was line_terminator, changed for consistency with
-                read_csv and the standard library 'csv' module.
-
         chunksize : int or None
             Rows to write at a time.
         date_format : str, default None
@@ -5859,11 +5851,6 @@ def sample(
             If int, array-like, or BitGenerator, seed for random number generator.
             If np.random.RandomState or np.random.Generator, use as given.
             Default ``None`` results in sampling with the current state of np.random.
-
-            .. versionchanged:: 1.4.0
-
-                np.random.Generator objects now accepted
-
         axis : {0 or 'index', 1 or 'columns', None}, default None
             Axis to sample. Accepts axis number or name. Default is stat axis
             for given data type. For `Series` this parameter is unused and defaults to `None`.

pandas/core/groupby/generic.py

@@ -251,9 +251,7 @@ def _get_data_to_aggregate(
     1        1        2
     2        3        4
 
-    .. versionchanged:: 1.3.0
-
-        The resulting dtype will reflect the return value of the aggregating function.
+    The resulting dtype will reflect the return value of the aggregating function.
 
     >>> s.groupby([1, 1, 2, 2]).agg(lambda x: x.astype(float).min())
     1    1.0
@@ -307,11 +305,8 @@ def apply(self, func, *args, **kwargs) -> Series:
 
         Notes
         -----
-
-        .. versionchanged:: 1.3.0
-
-            The resulting dtype will reflect the return value of the passed ``func``,
-            see the examples below.
+        The resulting dtype will reflect the return value of the passed ``func``,
+        see the examples below.
 
         Functions that mutate the passed object can produce unexpected
         behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
@@ -332,9 +327,7 @@ def apply(self, func, *args, **kwargs) -> Series:
         its argument and returns a Series.  `apply` combines the result for
         each group together into a new Series.
 
-        .. versionchanged:: 1.3.0
-
-            The resulting dtype will reflect the return value of the passed ``func``.
+        The resulting dtype will reflect the return value of the passed ``func``.
 
         >>> g1.apply(lambda x: x * 2 if x.name == "a" else x / 2)
         a    0.0
@@ -455,10 +448,8 @@ def aggregate(self, func=None, *args, engine=None, engine_kwargs=None, **kwargs)
         behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
         for more details.
 
-        .. versionchanged:: 1.3.0
-
-            The resulting dtype will reflect the return value of the passed ``func``,
-            see the examples below.
+        The resulting dtype will reflect the return value of the passed ``func``,
+        see the examples below.
 
         Examples
         --------
@@ -497,10 +488,8 @@ def aggregate(self, func=None, *args, engine=None, engine_kwargs=None, **kwargs)
         1        1        2
         2        3        4
 
-        .. versionchanged:: 1.3.0
-
-            The resulting dtype will reflect the return value of the aggregating
-            function.
+        The resulting dtype will reflect the return value of the aggregating
+        function.
 
         >>> s.groupby([1, 1, 2, 2]).agg(lambda x: x.astype(float).min())
         1    1.0
@@ -705,8 +694,6 @@ def _wrap_applied_output(
     Parrot     25.0
     Name: Max Speed, dtype: float64
 
-    .. versionchanged:: 1.3.0
-
     The resulting dtype will reflect the return value of the passed ``func``,
     for example:
 
@@ -1788,9 +1775,7 @@ class DataFrameGroupBy(GroupBy[DataFrame]):
 
     See :ref:`groupby.aggregate.named` for more.
 
-    .. versionchanged:: 1.3.0
-
-        The resulting dtype will reflect the return value of the aggregating function.
+    The resulting dtype will reflect the return value of the aggregating function.
 
     >>> df.groupby("A")[["B"]].agg(lambda x: x.astype(float).min())
           B
@@ -1881,10 +1866,8 @@ def aggregate(self, func=None, *args, engine=None, engine_kwargs=None, **kwargs)
         behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
         for more details.
 
-        .. versionchanged:: 1.3.0
-
-            The resulting dtype will reflect the return value of the passed ``func``,
-            see the examples below.
+        The resulting dtype will reflect the return value of the passed ``func``,
+        see the examples below.
 
         Examples
         --------
@@ -1964,10 +1947,8 @@ def aggregate(self, func=None, *args, engine=None, engine_kwargs=None, **kwargs)
 
         See :ref:`groupby.aggregate.named` for more.
 
-        .. versionchanged:: 1.3.0
-
-            The resulting dtype will reflect the return value of the aggregating
-            function.
+        The resulting dtype will reflect the return value of the aggregating
+        function.
 
         >>> df.groupby("A")[["B"]].agg(lambda x: x.astype(float).min())
               B
@@ -2326,8 +2307,6 @@ def _transform_general(self, func, engine, engine_kwargs, *args, **kwargs):
     4  3.666667  4.0
     5  4.000000  5.0
 
-    .. versionchanged:: 1.3.0
-
     The resulting dtype will reflect the return value of the passed ``func``,
     for example: