NDFrame.astype doc string, some further cleanup

Author: tp

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,15 +3652,15 @@ 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
         1    2
         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
@@ -3667,16 +3669,15 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs):
         Categories (2, int64): [2 < 1]
 
         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]
+        pandas object may propagate changes:
+
+        >>> 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
         --------