-
-
Notifications
You must be signed in to change notification settings - Fork 18.7k
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
Open
jorisvandenbossche
wants to merge
4
commits into
pandas-dev:main
Choose a base branch
from
jorisvandenbossche:doc-whatsnew-3.0
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+101
−3
Open
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
315f743
add section about string dtype
jorisvandenbossche 14f4cfa
add section about copy-on-write
jorisvandenbossche 6010fd9
Merge remote-tracking branch 'upstream/main' into doc-whatsnew-3.0
jorisvandenbossche 70449ad
add link to migration guide
jorisvandenbossche File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. | ||||||
See the :ref:`string_migration_guide` for more details on the behaviour changes | ||||||
and how to adapt your code to the new default. | ||||||
|
||||||
.. 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
|
||||||
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: | ||||||
|
||||||
|
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
With that edit it seems to suggest that it falls back to "object" dtype (as we currently use)? But it still has a StringDtype, just using numpy instead of pyarrow under the hood. So it is "backed by NumPy object dtype under the hood", so something like:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yup that edit is clearer. Just didn't want to make this ambiguous to suggest it could be the new NumPy string type (which it isnt)