Repository: pandas-dev/pandas
Pull request #58596 (2024-05-06 16:29:23)

[pre-commit.ci] pre-commit autoupdate
<!--pre-commit.ci start-->
updates:
- [github.com/astral-sh/ruff-pre-commit: v0.3.4 → v0.4.3](https://github.com/astral-sh/ruff-pre-commit/compare/v0.3.4...v0.4.3)
- [github.com/MarcoGorelli/cython-lint: v0.16.0 → v0.16.2](https://github.com/MarcoGorelli/cython-lint/compare/v0.16.0...v0.16.2)
- [github.com/pre-commit/pre-commit-hooks: v4.5.0 → v4.6.0](https://github.com/pre-commit/pre-commit-hooks/compare/v4.5.0...v4.6.0)
- [github.com/pre-commit/mirrors-clang-format: v18.1.2 → v18.1.4](https://github.com/pre-commit/mirrors-clang-format/compare/v18.1.2...v18.1.4)
<!--pre-commit.ci end-->


Patch:
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 43fa49ed2b..43dc202fce 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -19,7 +19,7 @@ ci:
     skip: [pyright, mypy]
 repos:
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.3.4
+    rev: v0.4.3
     hooks:
     -   id: ruff
         args: [--exit-non-zero-on-fix]
@@ -46,12 +46,12 @@ repos:
         types_or: [python, rst, markdown, cython, c]
         additional_dependencies: [tomli]
 -   repo: https://github.com/MarcoGorelli/cython-lint
-    rev: v0.16.0
+    rev: v0.16.2
     hooks:
     -   id: cython-lint
     -   id: double-quote-cython-strings
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v4.6.0
     hooks:
     -   id: check-case-conflict
     -   id: check-toml
@@ -91,7 +91,7 @@ repos:
     hooks:
     - id: sphinx-lint
 -   repo: https://github.com/pre-commit/mirrors-clang-format
-    rev: v18.1.2
+    rev: v18.1.4
     hooks:
     - id: clang-format
       files: ^pandas/_libs/src|^pandas/_libs/include
diff --git a/ci/code_checks.sh b/ci/code_checks.sh
index c26840de03..32a7c85fb5 100755
--- a/ci/code_checks.sh
+++ b/ci/code_checks.sh
@@ -75,11 +75,9 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.DataFrame.median RT03,SA01" \
         -i "pandas.DataFrame.min RT03" \
         -i "pandas.DataFrame.plot PR02,SA01" \
-        -i "pandas.DataFrame.std PR01,RT03,SA01" \
         -i "pandas.DataFrame.swaplevel SA01" \
         -i "pandas.Grouper PR02" \
         -i "pandas.Index PR07" \
-        -i "pandas.Index.join PR07,RT03,SA01" \
         -i "pandas.Index.ravel PR01,RT03" \
         -i "pandas.Interval PR02" \
         -i "pandas.IntervalIndex.closed SA01" \
diff --git a/pandas/core/arrays/string_arrow.py b/pandas/core/arrays/string_arrow.py
index ec2534ce17..4fccf6da8e 100644
--- a/pandas/core/arrays/string_arrow.py
+++ b/pandas/core/arrays/string_arrow.py
@@ -196,13 +196,13 @@ class ArrowStringArray(ObjectStringArrayMixin, ArrowExtensionArray, BaseStringAr
             na_values = scalars._mask
             result = scalars._data
             result = lib.ensure_string_array(result, copy=copy, convert_na_value=False)
-            return cls(pa.array(result, mask=na_values, type=pa.string()))
+            return cls(pa.array(result, mask=na_values, type=pa.large_string()))
         elif isinstance(scalars, (pa.Array, pa.ChunkedArray)):
-            return cls(pc.cast(scalars, pa.string()))
+            return cls(pc.cast(scalars, pa.large_string()))
 
         # convert non-na-likes to str
         result = lib.ensure_string_array(scalars, copy=copy)
-        return cls(pa.array(result, type=pa.string(), from_pandas=True))
+        return cls(pa.array(result, type=pa.large_string(), from_pandas=True))
 
     @classmethod
     def _from_sequence_of_strings(
@@ -245,7 +245,7 @@ class ArrowStringArray(ObjectStringArrayMixin, ArrowExtensionArray, BaseStringAr
         value_set = [
             pa_scalar.as_py()
             for pa_scalar in [pa.scalar(value, from_pandas=True) for value in values]
-            if pa_scalar.type in (pa.string(), pa.null())
+            if pa_scalar.type in (pa.string(), pa.null(), pa.large_string())
         ]
 
         # short-circuit to return all False array.
@@ -332,7 +332,9 @@ class ArrowStringArray(ObjectStringArrayMixin, ArrowExtensionArray, BaseStringAr
             result = lib.map_infer_mask(
                 arr, f, mask.view("uint8"), convert=False, na_value=na_value
             )
-            result = pa.array(result, mask=mask, type=pa.string(), from_pandas=True)
+            result = pa.array(
+                result, mask=mask, type=pa.large_string(), from_pandas=True
+            )
             return type(self)(result)
         else:
             # This is when the result type is object. We reach this when
@@ -655,7 +657,9 @@ class ArrowStringArrayNumpySemantics(ArrowStringArray):
             result = lib.map_infer_mask(
                 arr, f, mask.view("uint8"), convert=False, na_value=na_value
             )
-            result = pa.array(result, mask=mask, type=pa.string(), from_pandas=True)
+            result = pa.array(
+                result, mask=mask, type=pa.large_string(), from_pandas=True
+            )
             return type(self)(result)
         else:
             # This is when the result type is object. We reach this when
diff --git a/pandas/core/dtypes/cast.py b/pandas/core/dtypes/cast.py
index a130983337..08adb580ff 100644
--- a/pandas/core/dtypes/cast.py
+++ b/pandas/core/dtypes/cast.py
@@ -1697,7 +1697,7 @@ def maybe_cast_to_integer_array(arr: list | np.ndarray, dtype: np.dtype) -> np.n
             )
         raise ValueError("Trying to coerce float values to integers")
     if arr.dtype == object:
-        raise ValueError("Trying to coerce float values to integers")
+        raise ValueError("Trying to coerce object values to integers")
 
     if casted.dtype < arr.dtype:
         # TODO: Can this path be hit anymore with numpy > 2
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
index 8186b0a9c9..f0e956eb86 100644
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -12299,7 +12299,6 @@ class DataFrame(NDFrame, OpsMixin):
     ) -> Series | Any: ...
 
     @deprecate_nonkeyword_arguments(version="3.0", allowed_args=["self"], name="std")
-    @doc(make_doc("std", ndim=2))
     def std(
         self,
         axis: Axis | None = 0,
@@ -12308,6 +12307,82 @@ class DataFrame(NDFrame, OpsMixin):
         numeric_only: bool = False,
         **kwargs,
     ) -> Series | Any:
+        """
+        Return sample standard deviation over requested axis.
+
+        Normalized by N-1 by default. This can be changed using the ddof argument.
+
+        Parameters
+        ----------
+        axis : {index (0), columns (1)}
+            For `Series` this parameter is unused and defaults to 0.
+
+            .. warning::
+
+                The behavior of DataFrame.std with ``axis=None`` is deprecated,
+                in a future version this will reduce over both axes and return a scalar
+                To retain the old behavior, pass axis=0 (or do not pass axis).
+
+        skipna : bool, default True
+            Exclude NA/null values. If an entire row/column is NA, the result
+            will be NA.
+        ddof : int, default 1
+            Delta Degrees of Freedom. The divisor used in calculations is N - ddof,
+            where N represents the number of elements.
+        numeric_only : bool, default False
+            Include only float, int, boolean columns. Not implemented for Series.
+        **kwargs : dict
+            Additional keyword arguments to be passed to the function.
+
+        Returns
+        -------
+        Series or scalar
+            Standard deviation over requested axis.
+
+        See Also
+        --------
+        Series.std : Return standard deviation over Series values.
+        DataFrame.mean : Return the mean of the values over the requested axis.
+        DataFrame.mediam : Return the mediam of the values over the requested axis.
+        DataFrame.mode : Get the mode(s) of each element along the requested axis.
+        DataFrame.sum : Return the sum of the values over the requested axis.
+
+        Notes
+        -----
+        To have the same behaviour as `numpy.std`, use `ddof=0` (instead of the
+        default `ddof=1`)
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(
+        ...     {
+        ...         "person_id": [0, 1, 2, 3],
+        ...         "age": [21, 25, 62, 43],
+        ...         "height": [1.61, 1.87, 1.49, 2.01],
+        ...     }
+        ... ).set_index("person_id")
+        >>> df
+                   age  height
+        person_id
+        0           21    1.61
+        1           25    1.87
+        2           62    1.49
+        3           43    2.01
+
+        The standard deviation of the columns can be found as follows:
+
+        >>> df.std()
+        age       18.786076
+        height     0.237417
+        dtype: float64
+
+        Alternatively, `ddof=0` can be set to normalize by N instead of N-1:
+
+        >>> df.std(ddof=0)
+        age       16.269219
+        height     0.205609
+        dtype: float64
+        """
         result = super().std(
             axis=axis, skipna=skipna, ddof=ddof, numeric_only=numeric_only, **kwargs
         )
diff --git a/pandas/core/generic.py b/pandas/core/generic.py
index 20d8bd3bda..3da047eaa2 100644
--- a/pandas/core/generic.py
+++ b/pandas/core/generic.py
@@ -5527,7 +5527,7 @@ class NDFrame(PandasObject, indexing.IndexingMixin):
         it returns an empty object. When ``n`` is negative, it returns
         all rows except the last ``|n|`` rows, mirroring the behavior of ``df[:n]``.
 
-        If n is larger than the number of rows, this function returns all rows.
+        If ``n`` is larger than the number of rows, this function returns all rows.
 
         Parameters
         ----------
@@ -5615,7 +5615,7 @@ class NDFrame(PandasObject, indexing.IndexingMixin):
         For negative values of `n`, this function returns all rows except
         the first `|n|` rows, equivalent to ``df[|n|:]``.
 
-        If n is larger than the number of rows, this function returns all rows.
+        If ``n`` is larger than the number of rows, this function returns all rows.
 
         Parameters
         ----------
@@ -10052,7 +10052,7 @@ class NDFrame(PandasObject, indexing.IndexingMixin):
         fill_value : object, optional
             The scalar value to use for newly introduced missing values.
             the default depends on the dtype of `self`.
-            For numeric data, ``np.nan`` is used.
+            For Boolean and numeric NumPy data types, ``np.nan`` is used.
             For datetime, timedelta, or period data, etc. :attr:`NaT` is used.
             For extension dtypes, ``self.dtype.na_value`` is used.
         suffix : str, optional
diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py
index 224e9982ca..8ae087ac24 100644
--- a/pandas/core/indexes/base.py
+++ b/pandas/core/indexes/base.py
@@ -4316,9 +4316,12 @@ class Index(IndexOpsMixin, PandasObject):
         Parameters
         ----------
         other : Index
+            The other index on which join is performed.
         how : {'left', 'right', 'inner', 'outer'}
         level : int or level name, default None
+            It is either the integer position or the name of the level.
         return_indexers : bool, default False
+            Whether to return the indexers or not for both the index objects.
         sort : bool, default False
             Sort the join keys lexicographically in the result Index. If False,
             the order of the join keys depends on the join type (how keyword).
@@ -4326,6 +4329,14 @@ class Index(IndexOpsMixin, PandasObject):
         Returns
         -------
         join_index, (left_indexer, right_indexer)
+            The new index.
+
+        See Also
+        --------
+        DataFrame.join : Join columns with `other` DataFrame either on index
+            or on a key.
+        DataFrame.merge : Merge DataFrame or named Series objects with a
+            database-style join.
 
         Examples
         --------
@@ -4333,6 +4344,9 @@ class Index(IndexOpsMixin, PandasObject):
         >>> idx2 = pd.Index([4, 5, 6])
         >>> idx1.join(idx2, how="outer")
         Index([1, 2, 3, 4, 5, 6], dtype='int64')
+        >>> idx1.join(other=idx2, how="outer", return_indexers=True)
+        (Index([1, 2, 3, 4, 5, 6], dtype='int64'),
+        array([ 0,  1,  2, -1, -1, -1]), array([-1, -1, -1,  0,  1,  2]))
         """
         other = ensure_index(other)
         sort = sort or how == "outer"
diff --git a/pandas/core/series.py b/pandas/core/series.py
index 36abc04f2e..316c4a67ad 100644
--- a/pandas/core/series.py
+++ b/pandas/core/series.py
@@ -294,7 +294,7 @@ class Series(base.IndexOpsMixin, NDFrame):  # type: ignore[misc]
     z   NaN
     dtype: float64
 
-    Note that the Index is first build with the keys from the dictionary.
+    Note that the Index is first built with the keys from the dictionary.
     After this the Series is reindexed with the given Index values, hence we
     get all NaN as a result.
 


Test patch:
diff --git a/pandas/tests/indexes/numeric/test_numeric.py b/pandas/tests/indexes/numeric/test_numeric.py
index 676d33d2b0..8dde5febe8 100644
--- a/pandas/tests/indexes/numeric/test_numeric.py
+++ b/pandas/tests/indexes/numeric/test_numeric.py
@@ -397,7 +397,7 @@ class TestIntNumericIndex:
 
         # preventing casting
         arr = np.array([1, "2", 3, "4"], dtype=object)
-        msg = "Trying to coerce float values to integers"
+        msg = "Trying to coerce object values to integers"
         with pytest.raises(ValueError, match=msg):
             index_cls(arr, dtype=dtype)