populates dsintro and frame.py with examples and warning

- adds example to frame.py
- reworked warning in dsintro
- reworked Notes in frame.py

- additional fixups

Author: datajanko

doc/source/dsintro.rst

@@ -505,9 +505,41 @@ of one argument to be called on the ``DataFrame``. A *copy* of the original
 DataFrame is returned, with the new values inserted.
 
 .. warning::
+  Starting from Python 3.6 ``**kwargs`` is an ordered dictionary and ``assign`` 
+  respects the order of the keyword arguments. It is allowed to write
 
-  Since the function signature of ``assign`` is ``**kwargs``, a dictionary,
-  the order of the new columns in the resulting DataFrame cannot be guaranteed
+  .. ipython::
+      :verbatim:
+
+      In [1]: # Allowed for Python 3.6 and later
+               df.assign(C = lambda x: x['A'] + x['B'],
+                         D = lambda x: x['A'] + x['C'])
+
+  This may subtly change the behavior of your code when you're
+  using ``.assign()`` to update an existing column. Prior to Python 3.6,
+  callables referring to other variables being updated would get the "old" values
+
+  Previous Behaviour:
+
+  .. code-block:: ipython
+
+      In [2]: df = pd.DataFrame({"A": [1, 2, 3]})
+
+      In [3]: df.assign(A=lambda df: df.A + 1, C=lambda df: df.A * -1)
+      Out[3]:
+         A  C
+      0  2 -1
+      1  3 -2
+      2  4 -3
+
+  New Behaviour:
+
+  .. ipython:: python
+
+      df.assign(A=df.A+1, C= lambda df: df.A* -1)
+
+  For Python 3.5 and earlier the function signature of ``assign`` is ``**kwargs``, 
+  a dictionary, the order of the new columns in the resulting DataFrame cannot be guaranteed
   to match the order you pass in. To make things predictable, items are inserted
   alphabetically (by key) at the end of the DataFrame.
 

doc/source/whatsnew/v0.23.0.txt

@@ -125,39 +125,39 @@ Current Behavior
 ``.assign()`` accepts dependent arguments
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The :func:`DataFrame.assign()` now accepts dependent kwargs for python version later than 3.6 (see also `PEP 468
-<https://www.python.org/dev/peps/pep-0468/>`_). Now the keyword-value pairs passed to `.assign()` may depend on their predecessors if the values are callables. (:issue:`14207`)
+The :func:`DataFrame.assign` now accepts dependent keyword arguments for python version later than 3.6 (see also `PEP 468
+<https://www.python.org/dev/peps/pep-0468/>`_). Later keyword arguments may now refer to earlier ones if the argument is a callable. (:issue:`14207`)
 
 .. ipython:: python     
 
     df = pd.DataFrame({'A': [1, 2, 3]})
     df
-	df.assign(B=df.A, C=lambda x:x['A']+ x['B'])
+    df.assign(B=df.A, C=lambda x:x['A']+ x['B'])
 
 .. warning::
 
-This may subtly change the behavior of your code when you're
-using ``.assign()`` to update an existing column. Previously, callables
-referring to other variables being updated would get the "old" values
+  This may subtly change the behavior of your code when you're
+  using ``.assign()`` to update an existing column. Previously, callables
+  referring to other variables being updated would get the "old" values
 
-Previous Behaviour:
+  Previous Behaviour:
 
-.. code-block:: ipython
+  .. code-block:: ipython
 
-    In [2]: df = pd.DataFrame({"A": [1, 2, 3]})
+      In [2]: df = pd.DataFrame({"A": [1, 2, 3]})
 
-    In [3]: df.assign(A=lambda df: df.A + 1, C=lambda df: df.A * -1)
-    Out[3]:
-       A  C
-    0  2 -1
-    1  3 -2
-    2  4 -3
+      In [3]: df.assign(A=lambda df: df.A + 1, C=lambda df: df.A * -1)
+      Out[3]:
+         A  C
+      0  2 -1
+      1  3 -2
+      2  4 -3
 
-New Behaviour:
+  New Behaviour:
 
-.. ipython:: python
+  .. ipython:: python
 
-    df.assign(A=df.A+1, C= lambda df: df.A* -1)
+      df.assign(A=df.A+1, C= lambda df: df.A* -1)
 
 
 .. _whatsnew_0230.enhancements.other:

pandas/core/frame.py

@@ -2655,15 +2655,17 @@ def assign(self, **kwargs):
 
         Notes
         -----
-        For python 3.6 and above, the columns are inserted in the order of
-        \*\*kwargs. For python 3.5 and earlier, since \*\*kwargs is unordered,
-        the columns are inserted in alphabetical order at the end of your
-        DataFrame.  Assigning multiple columns within the same ``assign``
-        is possible, but for python 3.5 and earlier, you cannot reference
-        other columns created within the same ``assign`` call.
-        For python 3.6 and above it is possible to reference columns created
-        in an assignment. To this end you have to respect the order of kwargs
-        and use callables referencing the assigned columns.
+        Assigning multiple columns within the same ``assign`` is possible.
+        For Python 3.6 and above, later items in '\*\*kwargs' may refer to
+        newly created or modified columns in 'df'; items are computed and
+        assigned into 'df' in order.  For Python 3.5 and below, the order of
+        keyword arguments is not specified, you cannot refer to newly created
+        or modified columns. All items are computed first, and then assigned
+        in alphabetical order.
+
+        .. versionmodified :: 0.23.0
+
+            Keyword argument order is maintained for Python 3.6 and later.
 
         Examples
         --------
@@ -2699,20 +2701,30 @@ def assign(self, **kwargs):
         7   8 -1.495604  2.079442
         8   9  0.549296  2.197225
         9  10 -0.758542  2.302585
+
+        Where the keyword arguments depend on each other
+
+        >>> df = pd.DataFrame({'A': [1, 2, 3]})
+
+        >>> df.assign(B=df.A, C=lambda x:x['A']+ x['B'])
+            A  B  C
+         0  1  1  2
+         1  2  2  4
+         2  3  3  6
         """
         data = self.copy()
 
-        # for 3.6 preserve order of kwargs
+        # >= 3.6 preserve order of kwargs
         if PY36:
             for k, v in kwargs.items():
                 data[k] = com._apply_if_callable(v, data)
         else:
-            # for 3.5 or earlier: do all calculations first...
+            # <= 3.5: do all calculations first...
             results = OrderedDict()
             for k, v in kwargs.items():
                 results[k] = com._apply_if_callable(v, data)
 
-            # sort by key for 3.5 and earlier
+            # <= 3.5 and earlier
             results = sorted(results.items())
             # ... and then assign
             for k, v in results: