-
-
Notifications
You must be signed in to change notification settings - Fork 18.9k
DOC: add sections about big new features (CoW, string dtype) to 3.0.0 whatsnew notes #61724
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 2 commits
315f743
14f4cfa
6010fd9
70449ad
5d76195
873f624
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
|
@@ -14,10 +14,108 @@ including other versions of pandas. | |||||
Enhancements | ||||||
~~~~~~~~~~~~ | ||||||
|
||||||
.. _whatsnew_300.enhancements.enhancement1: | ||||||
.. _whatsnew_300.enhancements.string_dtype: | ||||||
|
||||||
Enhancement1 | ||||||
^^^^^^^^^^^^ | ||||||
Dedicated string data type by default | ||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||||||
|
||||||
Historically, pandas represented string columns with NumPy ``object`` data type. | ||||||
This representation has numerous problems: it is not specific to strings (any | ||||||
Python object can be stored in an ``object``-dtype array, not just strings) and | ||||||
it is often not very efficient (both performance wise and for memory usage). | ||||||
|
||||||
Starting with pandas 3.0, a dedicated string data type is enabled by default | ||||||
(backed by PyArrow under the hood, if installed, otherwise falling back to | ||||||
NumPy). This means that pandas will start inferring columns containing string | ||||||
data as the new ``str`` data type when creating pandas objects, such as in | ||||||
constructors or IO functions. | ||||||
|
||||||
Old behavior: | ||||||
|
||||||
.. code-block:: python | ||||||
|
||||||
>>> ser = pd.Series(["a", "b"]) | ||||||
0 a | ||||||
1 b | ||||||
dtype: object | ||||||
|
||||||
New behavior: | ||||||
|
||||||
.. code-block:: python | ||||||
|
||||||
>>> ser = pd.Series(["a", "b"]) | ||||||
0 a | ||||||
1 b | ||||||
dtype: str | ||||||
|
||||||
The string data type that is used in these scenarios will mostly behave as NumPy | ||||||
object would, including missing value semantics and general operations on these | ||||||
columns. | ||||||
|
||||||
The main characteristic of the new string data type: | ||||||
|
||||||
- Inferred by default for string data (instead of object dtype) | ||||||
- The ``str`` dtype can only hold strings (or missing values), in contrast to | ||||||
``object`` dtype. (setitem with non string fails) | ||||||
- The missing value sentinel is always ``NaN`` (``np.nan``) and follows the same | ||||||
missing value semantics as the other default dtypes. | ||||||
|
||||||
Those intentional changes can have breaking consequences, for example when checking | ||||||
for the ``.dtype`` being object dtype or checking the exact missing value sentinel. | ||||||
|
||||||
TODO add link to migration guide for more details | ||||||
jorisvandenbossche marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
.. seealso:: | ||||||
|
||||||
`PDEP-14: Dedicated string data type for pandas 3.0 <https://pandas.pydata.org/pdeps/0014-string-dtype.html>`__ | ||||||
|
||||||
|
||||||
.. _whatsnew_300.enhancements.copy_on_write: | ||||||
|
||||||
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: | ||||||
|
||||||
1. The result of *any* indexing operation (subsetting a DataFrame or Series in any way, | ||||||
i.e. including accessing a DataFrame column as a Series) or any method returning a | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I am going to keep the current wording here because I specifically wanted to highlight that accessing a column is also an indexing operation (people might think first about selecting rows, boolean filtering etc, but accessing a column is probably the most common (and most affected) case) |
||||||
new DataFrame or Series, always *behaves as if* it were a copy in terms of user | ||||||
API. | ||||||
2. As a consequence, if you want to modify an object (DataFrame or Series), the only way | ||||||
to do this is to directly modify that object itself. | ||||||
|
||||||
The main goal of this change is to make the user API more consistent and | ||||||
predictable. There is now a clear rule: *any* subset or returned | ||||||
series/dataframe **always** behaves as a copy of the original, and thus never | ||||||
modifies the original (before pandas 3.0, whether a derived object would be a | ||||||
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. | ||||||
|
||||||
The new behavioral semantics are explained in more detail in the | ||||||
:ref:`user guide about Copy-on-Write <copy_on_write>`. | ||||||
|
||||||
A secondary goal is to improve performance by avoiding unnecessary copies. As | ||||||
mentioned above, every new DataFrame or Series returned from an indexing | ||||||
operation or method *behaves* as a copy, but under the hood pandas will use | ||||||
views as much as possible, and only copy when needed to guarantee the "behaves | ||||||
as a copy" behaviour (this is the actual "copy-on-write" mechanism used as an | ||||||
implementation detail). | ||||||
|
||||||
Some of the behaviour changes described above are breaking changes in pandas | ||||||
3.0. When upgrading to pandas 3.0, it is recommended to first upgrade to pandas | ||||||
2.3 to get deprecation warnings for a subset of those changes. The | ||||||
:ref:`migration guide <copy_on_write.migration_guide>` explains the upgrade | ||||||
process in more detail. | ||||||
|
||||||
.. seealso:: | ||||||
|
||||||
`PDEP-7: Consistent copy/view semantics in pandas with Copy-on-Write <https://pandas.pydata.org/pdeps/0007-copy-on-write.html>`__ | ||||||
|
||||||
.. _whatsnew_300.enhancements.enhancement2: | ||||||
|
||||||
|
Uh oh!
There was an error while loading. Please reload this page.