DOC: adds column/attribute warnings to whatsnew

Author: deniederhut

doc/source/whatsnew/v0.21.0.txt

@@ -29,7 +29,6 @@ New features
 - Added ``skipna`` parameter to :func:`~pandas.api.types.infer_dtype` to
   support type inference in the presence of missing values (:issue:`17059`).
 
-
 .. _whatsnew_0210.enhancements.infer_objects:
 
 ``infer_objects`` type conversion
@@ -62,6 +61,63 @@ using the :func:`to_numeric` function (or :func:`to_datetime`, :func:`to_timedel
    df['C'] = pd.to_numeric(df['C'], errors='coerce')
    df.dtypes
 
+.. _whatsnew_0210.enhancements.column_creation:
+
+Improved warnings when attempting to create columns
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+New users are often flummoxed by the relationship between column operations and attribute
+access on ``DataFrame`` instances (:issue:`5904` & :issue:`7175`). Two specific instances
+of this confusion include attempting to create a new column by setting into an attribute:
+
+.. code-block:: ipython
+
+  In[1]: df = pd.DataFrame({'one': [1., 2., 3.]})
+  In[2]: df.two = [4, 5, 6]
+
+which does not raise any obvious exceptions, but also does not create a new column:
+
+.. code-block:: ipython
+
+  In[3]: df
+  Out[3]:
+      one
+  0  1.0
+  1  2.0
+  2  3.0
+
+and creating a column whose name collides with a method or attribute already in the instance
+namespace:
+
+.. code-block:: ipython
+
+  In[4]: df['sum'] = [5., 7., 9.]
+
+which does not permit that column to be accessed as an attribute:
+
+.. code-block:: ipython
+
+  In[5]: df.sum
+  Out[5]:
+  <bound method DataFrame.sum of    one  sum
+  0  1.0  5.0
+  1  2.0  7.0
+  2  3.0  9.0>
+
+Both of these now raise a ``UserWarning`` about the potential for unexpected behavior. Upon executing input 2, you can now expect to see:
+
+.. code-block:: ipython
+
+  In[2]: df.two = [4, 5, 6]
+  UserWarning: Pandas doesn't allow Series to be assigned into nonexistent columns - see https://pandas.pydata.org/pandas-docs/stable/indexing.html#attribute-access
+
+and the example in input 4 will now produce:
+
+.. code-block:: ipython
+
+  In[4]: df['sum'] = [5., 7., 9.]
+  UserWarning: Column name 'sum' collides with a built-in method, which will cause unexpected attribute behavior
+
 .. _whatsnew_0210.enhancements.other:
 
 Other Enhancements