Update docs on reserved attributes

[mgoodhand]

Code Sample, a copy-pastable example if possible

>>> t = pd.DataFrame({'foo': [1,2], 'labels': [3,4], 'bar': [5,6]})
>>> t.foo
0    1
1    2
Name: foo, dtype: int64
>>> t.bar
0    5
1    6
Name: bar, dtype: int64
>>> t.labels
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/mrg/git/xdash/env/lib/python2.7/site-packages/pandas/core/generic.py", line 3077, in __getattr__
    return object.__getattribute__(self, name)
AttributeError: 'DataFrame' object has no attribute 'labels'

Problem description

I would expect the labels column to be accessible as an attribute on the DataFrame, like t.foo and t.bar.

Instead, t.labels gives an AttributeError.

I eventually found the relevant section of the docs, which notes that index, major_axis, minor_axis, items, and labels are reserved.

http://pandas.pydata.org/pandas-docs/stable/indexing.html#attribute-access

Expected Output

Given the limitation, I would expect a warning at DataFrame creation time that the labels column will not be accessible as an attribute.

I see that this issue has been raised before (#8082, #8100) and closed, but I saw no warning. It looks like the only change was to expand the documentation (9b12ccb).

The suggestion from @jtratner on 7 Sep 2014 looked good to me:

UserWarning: Using reserved column name `labels` will be inaccessible by `getattr` calls - you must use `[]` instead.

Output of pd.show_versions()

[paste the output of pd.show_versions() here below this line]

INSTALLED VERSIONS

commit: None
python: 2.7.10.final.0
python-bits: 64
OS: Darwin
OS-release: 17.4.0
machine: x86_64
processor: i386
byteorder: little
LC_ALL: None
LANG: en_GB.UTF-8
LOCALE: None.None

pandas: 0.20.3
pytest: None
pip: 9.0.1
setuptools: 36.4.0
Cython: None
numpy: 1.13.1
scipy: None
xarray: None
IPython: None
sphinx: None
patsy: None
dateutil: 2.6.1
pytz: 2017.2
blosc: None
bottleneck: None
tables: None
numexpr: None
feather: None
matplotlib: None
openpyxl: None
xlrd: None
xlwt: None
xlsxwriter: None
lxml: None
bs4: 4.6.0
html5lib: 0.999999999
sqlalchemy: None
pymysql: None
psycopg2: None
jinja2: 2.9.6
s3fs: None
pandas_gbq: None
pandas_datareader: 0.5.0

[TomAugspurger]

On master, labels goes through for me.

In [1]: import pandas as pd

In [2]: t = pd.DataFrame({'foo': [1,2], 'labels': [3,4], 'bar': [5,6]})

In [3]: t.labels
Out[3]:
0    3
1    4
Name: labels, dtype: int64

Did this change recently? If so, we should update the docs.

I don't think we would do a warning for this (so e.g. index). The . accessing is a convenience for interactive use. We wouldn't want to force people using these column names to catch warnings every time they make a series / dataframe.

[mgoodhand]

Fair enough. I can see that not everyone will use the . access, and for them the warning would be an annoyance. Now that I'm aware of the issue, it shouldn't catch me out again.

Interesting that t.labels works on master. I was initially running 0.20.3, but I get the same behaviour (AttributeError) from 0.22.0.

[TomAugspurger]

Added this as a docs issues. We should update the reserved attr names to be the ones that we're using.

[sharad-vm]

I can take a stab at it.

[TomAugspurger]

👍 thanks @sharad-vm. Let us know if you get stuck.

[jreback]

I think was like this before because of Panel4D (which is removed in this version)