Merge remote-tracking branch 'upstream/main' into series-init-copy-cleanup

Author: jorisvandenbossche

.github/workflows/docbuild-and-upload.yml

@@ -93,7 +93,7 @@ jobs:
       run: mv doc/build/html web/build/docs
 
     - name: Save website as an artifact
-      uses: actions/upload-artifact@v5
+      uses: actions/upload-artifact@v6
       with:
         name: website
         path: web/build

.github/workflows/wheels.yml

@@ -64,7 +64,7 @@ jobs:
           python -m pip install build
           python -m build --sdist
 
-      - uses: actions/upload-artifact@v5
+      - uses: actions/upload-artifact@v6
         with:
           name: sdist
           path: ./dist/*
@@ -138,7 +138,7 @@ jobs:
       # removes unnecessary files from the release
       - name: Download sdist (not macOS)
         #if: ${{ matrix.buildplat[1] != 'macosx_*' }}
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v7
         with:
           name: sdist
           path: ./dist
@@ -197,7 +197,7 @@ jobs:
         shell: bash -el {0}
         run: for whl in $(ls ./dist/*.whl); do wheel unpack $whl -d /tmp; done
 
-      - uses: actions/upload-artifact@v5
+      - uses: actions/upload-artifact@v6
         with:
           name: ${{ matrix.python[0] }}-${{ matrix.buildplat[1] }}
           path: ./dist/*.whl
@@ -229,11 +229,11 @@ jobs:
 
     steps:
       - name: Download all artefacts
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v7
         with:
           path: dist          # everything lands in ./dist/**
 
-      # TODO: This step can be probably be achieved by actions/download-artifact@v6
+      # TODO: This step can be probably be achieved by actions/download-artifact@v7
       # by specifying merge-multiple: true, and a glob pattern
       - name: Collect files
         run: |

ci/code_checks.sh

@@ -79,6 +79,8 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.api.typing.DataFrameGroupBy.plot PR02" \
         -i "pandas.api.typing.SeriesGroupBy.plot PR02" \
         -i "pandas.api.typing.Resampler.quantile PR01,PR07" \
+        -i "pandas.StringDtype.storage SA01" \
+        -i "pandas.StringDtype.na_value SA01" \
         -i "pandas.tseries.offsets.BDay PR02,SA01" \
         -i "pandas.tseries.offsets.BHalfYearBegin.is_on_offset GL08" \
         -i "pandas.tseries.offsets.BHalfYearBegin.n GL08" \

doc/source/_static/schemas/01_table_dataframe.svg

@@ -72,6 +72,8 @@ SQL table or the ``data.frame`` in `R <https://www.r-project.org/>`__.
 -  The column ``Name`` consists of textual data with each value a
    string, the column ``Age`` are numbers and the column ``Sex`` is
    textual data.
+-  The index labels each row. By default, this is a sequence of integers
+   starting at 0.
 
 In spreadsheet software, the table representation of our data would look
 very similar:

doc/source/getting_started/intro_tutorials/01_table_oriented.rst

@@ -637,6 +637,8 @@ with a bool :class:`numpy.ndarray`.
       DatetimeTZDtype.tz
       PeriodDtype.freq
       IntervalDtype.subtype
+      StringDtype.storage
+      StringDtype.na_value
 
 *********
 Utilities

doc/source/reference/arrays.rst

@@ -431,6 +431,36 @@ an error will be raised. For instance, in the above example, ``s.loc[2:5]`` woul
 For more information about duplicate labels, see
 :ref:`Duplicate Labels <duplicates>`.
 
+When using a slice with a step, such as ``.loc[start:stop:step]``, note that
+*start* and *stop* are interpreted as **labels**, while *step* is applied over
+the **positional index** within that label range. This means a stepped slice
+will behave differently than using the labels ``range(start, stop, step)`` when
+the index is not contiguous integers.
+
+For example, in a ``Series`` with a non-contiguous integer index:
+
+.. ipython:: python
+
+    s = pd.Series(range(10), index=[0, 5, 10, 15, 20, 25, 30, 35, 40, 45])
+    s.loc[10:50:5]              # (10), then skip 3 positions → 35 only
+    s.loc[[10, 15, 20, 25]]     # explicit label selection
+
+The first applies *step* across **positional locations** between the start/stop
+labels. The second selects each label directly.
+
+Similarly, with a string-based index, the behavior is identical:
+
+.. ipython:: python
+
+    s = pd.Series(range(10), index=['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j'])
+    s.loc['b':'i':2]            # Start at 'b' (position 1), stop at 'i' (position 8), step 2 positions → 'b', 'd', 'f', 'h'
+    s.loc[['b', 'd', 'f', 'h']] # explicit label selection
+
+In both cases, *start* and *stop* determine the label boundaries (inclusive),
+while *step* skips positions within that range, regardless of the index type.
+
+
+
 .. _indexing.integer:
 
 Selection by position

doc/source/user_guide/indexing.rst

@@ -20,6 +20,14 @@ enable it with:
 
 This allows you to test your code before the final 3.0 release.
 
+.. note::
+
+   This migration guide focuses on the changes and migration steps needed when
+   you are currently using ``object`` dtype for string data, which is used by
+   default in pandas < 3.0. If you are already using one of the opt-in string
+   dtypes, you can continue to do so without change.
+   See :ref:`string_migration_guide-for_existing_users` for more details.
+
 Background
 ----------
 
@@ -457,7 +465,23 @@ raise an error regardless of the number of strings:
    ...
    TypeError: Cannot perform reduction 'prod' with string dtype
 
-.. For existing users of the nullable ``StringDtype``
-.. --------------------------------------------------
 
-.. TODO
+.. _string_migration_guide-for_existing_users:
+
+For existing users of the nullable ``StringDtype``
+--------------------------------------------------
+
+While pandas 3.0 introduces a new _default_ string data type, pandas had an
+opt-in nullable string data type since pandas 1.0, which can be specified using
+``dtype="string"``. This nullable string dtype uses ``pd.NA`` as the missing
+value indicator. In addition, also through :class:`ArrowDtype` (by using
+``dtypes_backend="pyarrow"``) since pandas 1.5, one could already make use of
+a dedicated string dtype.
+
+If you are already using one of the nullable string dtypes, for example by
+specifying ``dtype="string"``, by using :meth:`~DataFrame.convert_dtypes`, or
+by specifying the ``dtype_backend`` argument in IO functions, you can continue
+to do so without change.
+
+The migration guide above applies to code that is currently (< 3.0) using object
+dtype for string data.

doc/source/user_guide/migration-3-strings.rst

@@ -753,7 +753,10 @@ Differences in behavior will be primarily due to the kind of NA value.
 The four :class:`StringDtype` variants
 ======================================
 
-There are four :class:`StringDtype` variants that are available to users.
+There are four :class:`StringDtype` variants that are available to users,
+controlled by the ``storage`` and ``na_value`` parameters of :class:`StringDtype`.
+At runtime, these can be checked via the :attr:`StringDtype.storage`
+and :attr:`StringDtype.na_value` attributes.
 
 Python storage with ``np.nan`` values
 -------------------------------------

doc/source/user_guide/text.rst

@@ -1294,15 +1294,6 @@ frequencies. We will refer to these aliases as *offset aliases*.
     "us", "microseconds"
     "ns", "nanoseconds"
 
-.. deprecated:: 2.2.0
-
-   Aliases ``H``, ``BH``, ``CBH``, ``T``, ``S``, ``L``, ``U``, and ``N``
-   are deprecated in favour of the aliases ``h``, ``bh``, ``cbh``,
-   ``min``, ``s``, ``ms``, ``us``, and ``ns``.
-
-   Aliases ``Y``, ``M``, and ``Q`` are deprecated in favour of the aliases
-   ``YE``, ``ME``, ``QE``.
-
 
 .. note::
 
@@ -1358,11 +1349,6 @@ frequencies. We will refer to these aliases as *period aliases*.
     "us", "microseconds"
     "ns", "nanoseconds"
 
-.. deprecated:: 2.2.0
-
-   Aliases ``H``, ``T``, ``S``, ``L``, ``U``, and ``N`` are deprecated in favour of the aliases
-   ``h``, ``min``, ``s``, ``ms``, ``us``, and ``ns``.
-
 
 Combining aliases
 ~~~~~~~~~~~~~~~~~