Merge remote-tracking branch 'upstream/main' into bug/cow/index_readonly_input

Author: mroeschke

doc/_templates/docs-announcement-banner.html

@@ -0,0 +1 @@
+Announcement: pandas 3.0.0 release candidate ready for testing! Read more <a href="https://pandas.pydata.org/community/blog/pandas-3.0-release-candidate.html">in the blog post</a>

doc/source/conf.py

@@ -258,6 +258,7 @@
     # This shows a warning for patch releases since the
     # patch version doesn't compare as equal (e.g. 2.2.1 != 2.2.0 but it should be)
     "show_version_warning_banner": False,
+    "announcement": "https://raw.githubusercontent.com/pandas-dev/pandas/main/doc/_templates/docs-announcement-banner.html",
     "icon_links": [
         {
             "name": "X",

doc/source/whatsnew/v3.0.0.rst

@@ -80,8 +80,8 @@ and how to adapt your code to the new default.
 
 .. _whatsnew_300.enhancements.copy_on_write:
 
-Copy-on-Write
-^^^^^^^^^^^^^
+Consistent copy/view behaviour with Copy-on-Write
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The new "copy-on-write" behaviour in pandas 3.0 brings changes in behavior in
 how pandas operates with respect to copies and views. A summary of the changes:
@@ -101,9 +101,10 @@ copy or a view depended on the exact operation performed, which was often
 confusing).
 
 Because every single indexing step now behaves as a copy, this also means that
-"chained assignment" (updating a DataFrame with multiple setitem steps) will
-stop working. Because this now consistently never works, the
-``SettingWithCopyWarning`` is removed.
+**"chained assignment"** (updating a DataFrame with multiple setitem steps)
+**will stop working**. Because this now consistently never works, the
+``SettingWithCopyWarning`` is removed,  and defensive ``.copy()`` calls to
+silence the warning are no longer needed.
 
 The new behavioral semantics are explained in more detail in the
 :ref:`user guide about Copy-on-Write <copy_on_write>`.
@@ -130,10 +131,18 @@ and will be removed in pandas 4.0.
 
 .. _whatsnew_300.enhancements.col:
 
-``pd.col`` syntax can now be used in :meth:`DataFrame.assign` and :meth:`DataFrame.loc`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Initial support for ``pd.col()`` syntax to create expressions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-You can now use ``pd.col`` to create callables for use in dataframe methods which accept them. For example, if you have a dataframe
+This release introduces :func:`col` to refer to a DataFrame column by name
+and build up expressions.
+
+This can be used as a simplified syntax to create callables for use in
+methods such as :meth:`DataFrame.assign`. In practice, where you would
+have to use a ``lambda`` function before, you can now use ``pd.col()``
+instead.
+
+For example, if you have a dataframe
 
 .. ipython:: python
 
@@ -151,6 +160,18 @@ you can now write:
 
     df.assign(c = pd.col('a') + pd.col('b'))
 
+The expression object returned by :func:`col` supports all standard operators
+(like ``+``, ``-``, ``*``, ``/``, etc.) and all Series methods and namespaces
+(like ``pd.col("name").sum()``, ``pd.col("name").str.upper()``, etc.).
+
+Currently, the ``pd.col()`` syntax can be used in any place which accepts a
+callable that takes the calling DataFrame as first argument and returns a
+Series, like ``lambda df: df[col_name]``.
+This includes :meth:`DataFrame.assign`, :meth:`DataFrame.loc`, and getitem/setitem.
+
+It is expected that the support for ``pd.col()`` will be expanded to more methods
+in future releases.
+
 New Deprecation Policy
 ^^^^^^^^^^^^^^^^^^^^^^
 pandas 3.0.0 introduces a new 3-stage deprecation policy: using ``DeprecationWarning`` initially, then switching to ``FutureWarning`` for broader visibility in the last minor version before the next major release, and then removal of the deprecated functionality in the major release. This was done to give downstream packages more time to adjust to pandas deprecations, which should reduce the amount of warnings that a user gets from code that isn't theirs. See `PDEP 17 <https://pandas.pydata.org/pdeps/0017-backwards-compatibility-and-deprecation-policy.html>`_ for more details.

environment.yml

@@ -86,7 +86,8 @@ dependencies:
   - natsort  # DataFrame.sort_values doctest
   - pickleshare  # Needed for IPython Sphinx directive in the docs GH#60429
   - numpydoc
-  - pydata-sphinx-theme=0.16
+  # temporary installed with pip with custom patch until released
+  # - pydata-sphinx-theme=0.16
   - pytest-cython  # doctest
   - sphinx
   - sphinx-design
@@ -126,3 +127,4 @@ dependencies:
 
   - pip:
       - tzdata>=2023.3
+      - https://github.com/jorisvandenbossche/pydata-sphinx-theme/archive/refs/heads/v0.16.1+dismissable-announcement-banner.zip

pandas/core/col.py

@@ -260,6 +260,8 @@ def col(col_name: Hashable) -> Expression:
     :meth:`DataFrame.assign` or :meth:`DataFrame.loc`, can also accept
     ``pd.col(col_name)``.
 
+    .. versionadded:: 3.0.0
+
     Parameters
     ----------
     col_name : Hashable

pandas/core/reshape/tile.py

@@ -108,7 +108,7 @@ def cut(
         The precision at which to store and display the bins labels.
     include_lowest : bool, default False
         Whether the first interval should be left-inclusive or not.
-    duplicates : {default 'raise', 'drop'}, optional
+    duplicates : {'raise', 'drop'}, default 'raise'
         If bin edges are not unique, raise ValueError or drop non-uniques.
     ordered : bool, default True
         Whether the labels are ordered or not. Applies to returned types

requirements-dev.txt

@@ -61,7 +61,6 @@ gitpython
 natsort
 pickleshare
 numpydoc
-pydata-sphinx-theme==0.16
 pytest-cython
 sphinx
 sphinx-design
@@ -87,3 +86,4 @@ pygments
 jupyterlite-core
 jupyterlite-pyodide-kernel
 tzdata>=2023.3
+https://github.com/jorisvandenbossche/pydata-sphinx-theme/archive/refs/heads/v0.16.1+dismissable-announcement-banner.zip

web/pandas/_templates/layout.html

@@ -56,9 +56,11 @@
             </nav>
         </header>
         <main role="main">
-            <div class="container">
+            {% block body_container %}
+            <div class="container container-main">
                 {% block body %}{% endblock %}
             </div>
+            {% endblock %}
         </main>
         <footer class="container pt-4 pt-md-5 border-top">
             <ul class="list-inline social-buttons float-end">

web/pandas/community/blog/pandas-3.0-release-candidate.md

@@ -0,0 +1,130 @@
+Title: pandas 3.0.0 release candidate ready for testing!
+Date: 2025-12-12
+
+# pandas 3.0.0 release candidate ready for testing!
+
+We're excited to announce the release candidate for pandas 3.0. This major
+release brings significant improvements to pandas, but also features some
+potentially breaking changes.
+
+To ensure a smooth pandas 3.0 release, we can use your help to [test the
+release candidate now](#call-to-action-test-the-release-candidate).
+
+## Highlights of pandas 3.0
+
+pandas 3.0 introduces several major enhancements:
+
+- **Dedicated string data type by default**: string columns are now inferred as
+  the new `str` dtype instead of `object`, providing better performance and type
+  safety
+- **Consistent copy/view behaviour with Copy-on-Write (CoW)** (a.k.a. getting
+  rid of the SettingWithCopyWarning): more predictable and consistent behavior
+  for all operations, with improved performance through avoiding unnecessary
+  copies
+- **New `pd.col` syntax**: initial support for `pd.col()` as a simplified syntax
+  for creating callables in `DataFrame.assign`
+
+Further, pandas 3.0 includes a lot of other improvements and bug fixes. You can
+find the complete list of changes in our
+[release notes](https://pandas.pydata.org/docs/dev/whatsnew/v3.0.0.html).
+
+## Important changes requiring code updates
+
+As a major release, pandas 3.0 includes some breaking changes that may require
+updates to your code. The two most significant changes are:
+
+### 1. Dedicated string data type by default
+
+Starting with pandas 3.0, string columns are automatically inferred as `str`
+dtype instead of the numpy `object` (which can store any Python object).
+
+**Example:**
+```python
+# Old behavior (pandas < 3.0)
+>>> ser = pd.Series(["a", "b"])
+>>> ser
+0    a
+1    b
+dtype: object  # <-- numpy object dtype
+
+# New behavior (pandas 3.0)
+>>> ser = pd.Series(["a", "b"])
+>>> ser.dtype
+>>> ser
+0    a
+1    b
+dtype: str  # <-- new string dtype
+```
+
+This change improves performance and type safety, but may require code updates,
+especially for library code that currently looks for "object" dtype when
+expecting string data.
+
+For more details, see the
+[migration guide for the new string data type](https://pandas.pydata.org/docs/dev/user_guide/migration-3-strings.html).
+
+### 2. Consistent copy/view behaviour with Copy-on-Write (CoW)
+
+Copy-on-Write is now the default and only mode in pandas 3.0. This makes
+behavior more consistent and predictable, but requires updates to certain coding
+patterns.
+
+The most impactfull change is that **chained assignment will no longer work**.
+As a result, the `SettingWithCopyWarning` is also removed (since there is no
+longer ambiguity whether it would work or not), and defensive `.copy()` calls
+to silence the warning are no longer needed.
+
+**Example:**
+```python
+# Old behavior (pandas < 3.0) - chained assignment
+df["foo"][df["bar"] > 5] =   # This might modify df (unpredictable)
+
+# New behavior (pandas 3.0) - must do the modification in one step (e.g. with .loc)
+df.loc[df["bar"] > 5, "foo"] = 100
+```
+
+In general, any result of an indexing operation or method now always behaves as
+if it were a copy, so modifications of the result won't affect the original
+DataFrame.
+
+For more details, see the
+[Copy-on-Write migration guide](https://pandas.pydata.org/docs/dev/user_guide/copy_on_write.html#migrating-to-copy-on-write).
+
+
+## Call to Action: test the Release Candidate
+
+We need your help to ensure a smooth pandas 3.0 release!
+
+Especially if you have pandas code in production or maintain a library with
+pandas as a dependency, it is strongly recommended to run your test suites with
+the release candidate, and report any issue to our issue tracker before the
+official 3.0.0 release.
+
+How can you best test the release candidate?
+
+1. **First update to the latest released pandas 2.3** (if you are not already
+   running that version) and test it with your codebase. It is recommended to
+   resolve any deprecation warning before upgrading to pandas 3.0.
+2. Optionally, you can already enable the new string dtype and Copy-on-Write
+   mode using pandas 2.3 (`pd.options.future.infer_string = True` and
+   `pd.options.mode.copy_on_write = True`).
+3. **Install the release candidate** (see below) and test it with your codebase
+4. **Run your existing code** to identify any issues or needed updates
+5. **Report any problems** you encounter on our [GitHub repository issue tracker](https://github.com/pandas-dev/pandas/issues)
+
+The more testing we get now, the smoother the final pandas 3.0 release will be
+for everyone. Your feedback is crucial for making this a successful release!
+
+### Getting the Release Candidate
+
+You can install the pandas 3.0 release candidate from PyPI:
+
+```bash
+python -m pip install --upgrade pandas==3.0.0rc0
+```
+
+Or from conda-forge using conda/mamba:
+
+```bash
+conda install -c conda-forge/label/pandas_rc pandas==3.0.0rc0
+```

web/pandas/index.html

@@ -1,5 +1,5 @@
 {% extends "layout.html" %}
-{% block body %}
+{% block body_container %}
     <div class="container">
         <div class="row">
             <div class="col-md-9">