diff --git a/pandas/core/generic.py b/pandas/core/generic.py index c60d78303d4841..1f5e1430115e89 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -3610,7 +3610,7 @@ def blocks(self): mapping={True: 'raise', False: 'ignore'}) def astype(self, dtype, copy=True, errors='raise', **kwargs): """ - Cast a pandas object to new dtype ``dtype``. + Cast a pandas object to a specified dtype ``dtype``. Parameters ---------- @@ -3620,7 +3620,9 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs): column label and dtype is a numpy.dtype or Python type to cast one or more of the DataFrame's columns to column-specific types. copy : bool, default True. - Return a copy when ``copy=True`` (be really careful with this!). + Return a copy when ``copy=True`` (be very careful setting + ``copy=False`` as changes to values then may propagate to other + pandas objects). errors : {'raise', 'ignore'}, default 'raise'. Control raising of exceptions on invalid data for provided dtype. @@ -3650,7 +3652,7 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs): 1 2 dtype: int64 - Convert to pd.Categorial: + Convert to categorical type: >>> ser.astype('category') 0 1 @@ -3658,7 +3660,7 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs): dtype: category Categories (2, int64): [1, 2] - Convert to ordered pd.Categorial with custom ordering: + Convert to ordered categorical type with custom ordering: >>> ser.astype('category', ordered=True, categories=[2, 1]) 0 1 @@ -3669,14 +3671,13 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs): Note that using ``copy=False`` and changing data on a new pandas object may propagate changes upwards: - >>> cat1 = pd.Series([1,2], dtype='category') - >>> cat2 = cat1.astype('category', copy=False) - >>> cat2[0] = 2 - >>> cat1 # note that cat1[0] is changed too - 0 2 - 1 2 - dtype: category - Categories (2, int64): [1, 2] + >>> s1 = pd.Series([1,2]) + >>> s2 = s1.astype('int', copy=False) + >>> s2[0] = 10 + >>> s1 # note that s1[0] has changed too + 0 10 + 1 2 + dtype: int64 See also --------