Skip to content

DOC: Add clearer info when copy is False but memory shared only for certain objects #41514

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.

Sign up for GitHub

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

Merged
merged 10 commits into from
May 21, 2021
Merged

DOC: Add clearer info when copy is False but memory shared only for certain objects #41514

Changes from 3 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f9efd2a
DOC: Add info on memory location sharing when copy=False (#41423).
mdhsieh May 14, 2021
0c70b9f
DOC: Add 2 examples when creating Series and copy is False (#41423).
mdhsieh May 16, 2021
2ed2b8d
DOC: Fix code format of 2 examples added to Series section (#41423).
mdhsieh May 16, 2021
1a56449
DOC: Fix spacing and reword parameter info and examples (#41423).
mdhsieh May 18, 2021
ac82b6b
DOC: Try fix PEP8 spacing issue.
mdhsieh May 18, 2021
5eab8f9
Merge remote-tracking branch 'upstream/master' into 41423-doc-series-…
mdhsieh May 18, 2021
0e147a1
DOC: Try fix one line which is too long.
mdhsieh May 18, 2021
dfd10c8
Revert "Merge remote-tracking branch 'upstream/master' into 41423-doc…
mdhsieh May 18, 2021
52ce3ba
DOC: Add reworded parameter info and and 2 examples again (#41423).
mdhsieh May 18, 2021
818d5d6
DOC: Change type output from int32 to int64 in ndarray data Series co…
mdhsieh May 20, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 34 additions & 1 deletion pandas/core/series.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -223,7 +223,10 @@ class Series(base.IndexOpsMixin, generic.NDFrame):
name : str, optional
The name to give to the Series.
copy : bool, default False
Copy input data.
Copy input data. If False and the Series returns a `copy`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment on usage of "returns" as below.

Generally I think this description might be too verbose for a parameter description and could be shortened to basically just get the idea across that a copy may still be made if necessary (as in the case of a list where we cannot share memory). Then the examples below should suffice to explain the different possible cases.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html has a good example of this)

of the data, the memory location for the values is not shared.
If False and the Series returns a `view` on the data,
the memory location for the values is shared.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Copy input data. If False and the Series returns a `copy`
of the data, the memory location for the values is not shared.
If False and the Series returns a `view` on the data,
the memory location for the values is shared.
Copy input data. Only affects Series or 1d ndarray input. See examples.


Examples
--------
Expand Down Expand Up @@ -251,6 +254,36 @@ class Series(base.IndexOpsMixin, generic.NDFrame):
Note that the Index is first build 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.

Constructing Series from an array with `copy=False`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd call this a list, since the difference between an array and list in this context is important in terms of ability to share memory.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Constructing Series from an array with `copy=False`.
Constructing Series from a list with `copy=False`.


>>> r = [1,2]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
>>> r = [1,2]
>>> r = [1, 2]

>>> ser = pd.Series(r, copy=False)
>>> ser.iloc[0] = 999
>>> r
[1, 2]
>>> ser
0 999
1 2
dtype: int64

The Series returns a `copy` of the original data, so
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you mean by returns here? It's more like the data backing the series does not share the same memory as the input r.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh right, by "returns" a copy I meant the Series created had a copy of the data. I guess "returns" is not the correct word to use.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The Series returns a `copy` of the original data, so
Due to input data type the Series is created with a `copy` even though `copy=False`, so

the original data is unchanged.

Constructing Series from a `numpy.array` with `copy=False`.

>>> r = np.array([1,2])
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
>>> r = np.array([1,2])
>>> r = np.array([1, 2])

>>> ser = pd.Series(r, copy=False)
>>> ser.iloc[0] = 999
>>> r
array([999, 2])
>>> ser
0 999
1 2
dtype: int32

The Series returns a `view` on the original data, so
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The Series returns a `view` on the original data, so
Due to input data type here the Series represents a `view` on the original data, so

the original data is changed as well.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment as above on wording of returns

"""

_typ = "series"
Expand Down