API: remove the copy kw from .xs to prevent an expectation of a view (which may not be possible)

[jreback]

closes #6894

Deprecate passing keyword copy to:

• DataFrame/Series/Panel/.xs
• Panel.minor_xs
• Panel.major_xs

.xs returns a view (as does .loc) IF POSSIBLE

MultiIndexing with Slicers eliminates the need for this (and .xs for the too, but for
some cases its 'simpler').

[jorisvandenbossche]

Should we go first through a deprecation cycle? So to not let fail your code when you provided the copy keyword, but only warning it is ignored and will be removed?

[jreback]

good point..will add on the user facing code

[jreback]

@jorisvandenbossche updated.....so this still allows one to do

df.xs('foo')[:] = 10

but now is undocumented (was in a doc string before)
(and will give a SettingWithCopyWarning if its actually a copy, rather than a view).

But that is not supported / dangerous anyhow

MultiIndex Slicers is the correct method

df.loc['foo'] = 10

so nothing lost

maybe should add to the doc string that .xs is only for getting?

[jreback]

@jorisvandenbossche how do I do a See also and have it refer to loc? in the docstring (so you can click it)

[jreback]

@jorisvandenbossche

can I use a :ref: directly in the See Also?

e.g.

For more information on ``.at``, ``.iat``, ``.ix``, ``.loc``, and
``.iloc``,  see the :ref:`indexing documentation <indexing>`.

[jorisvandenbossche]

like this:

See also
--------
DataFrame.loc : some explanation why this would be related

only the docstring of loc is not that informative ... (http://pandas.pydata.org/pandas-docs/dev/generated/pandas.DataFrame.loc.html#pandas.DataFrame.loc) maybe should open an issue about that

[jreback]

just did #6920

[jorisvandenbossche]

Aha :-)

Yes, you can use all sphinx referencing in the docstrings as in the normal docs (only if you see the docstring as plain text in eg the terminal, then it makes less sense, but for the api pages on the online docs this is very useful)

[jreback]

gr8..makes sense

[jorisvandenbossche]

Maybe explicitly add in the description of xs is only for getting? I found that a good idea.
And the See also has to be a Notes now ('see also' is really only for python/pandas objects that sphinx can make a link to, and not for a general sentence)