From e527140d40ad606b6784ca797ee2de70c98c2ed1 Mon Sep 17 00:00:00 2001 From: Jeff Reback Date: Tue, 26 Sep 2017 06:29:18 -0400 Subject: [PATCH] review comments --- doc/source/indexing.rst | 23 ++++++++++++----------- doc/source/whatsnew/v0.21.0.txt | 14 +++++++------- pandas/core/indexing.py | 2 +- 3 files changed, 20 insertions(+), 19 deletions(-) diff --git a/doc/source/indexing.rst b/doc/source/indexing.rst index 0802e910f1fcaf..1ba5d7506108fd 100644 --- a/doc/source/indexing.rst +++ b/doc/source/indexing.rst @@ -644,14 +644,14 @@ For getting *multiple* indexers, using ``.get_indexer`` .. _indexing.deprecate_loc_reindex_listlike: -Using loc with missing keys in a list is Deprecated ---------------------------------------------------- +Indexing with missing list-of-labels is Deprecated +-------------------------------------------------- .. warning:: - Starting in 0.21.0, using ``.loc`` with a list-like containing missing key, is deprecated, in favor of ``.reindex``. + Starting in 0.21.0, using ``.loc`` or ``[]`` with a list-like containing one or more missing labels, is deprecated, in favor of ``.reindex``. -In prior versions, using ``.loc[list-of-keys]`` would work as long as *at least 1* of the keys was found (otherwise it +In prior versions, using ``.loc[list-of-labels]`` would work as long as *at least 1* of the keys was found (otherwise it would raise a ``KeyError``). This behavior is deprecated and will show a warning message pointing to this section. The recommeded alternative is to use ``.reindex()``. @@ -659,7 +659,7 @@ For example. .. ipython:: python - s = Series([1, 2, 3]) + s = pd.Series([1, 2, 3]) s Selection with all keys found is unchanged. @@ -706,29 +706,30 @@ The idiomatic way to achieve selecting potentially not-found elmenents is via `` s.reindex([1, 2, 3]) -Alternatively, if you want to select only *valid* keys, the following is idiomatic; furthermore this is more efficient, and is guaranteed to preserve the dtype of the selection. +Alternatively, if you want to select only *valid* keys, the following is idiomatic and efficient; it is guaranteed to preserve the dtype of the selection. .. ipython:: python - keys = [1, 2, 3] - s.loc[s.index & keys] + labels = [1, 2, 3] + s.loc[s.index.intersection(labels)] Having a duplicated index will raise for a ``.reindex()``: .. ipython:: python s = pd.Series(np.arange(4), index=['a', 'a', 'b', 'c']) + labels = ['c', 'd'] .. code-block:: python - In [17]: s.reindex(['c', 'd']) + In [17]: s.reindex(labels) ValueError: cannot reindex from a duplicate axis -The idiomatic expression again allows this operation to proceed +The idiomatic expression allows this operation to proceed. .. ipython:: python - s.loc[s.index & ['c', 'd']] + s.loc[s.index.intersection(labels)].reindex(labels) .. _indexing.basics.partial_setting: diff --git a/doc/source/whatsnew/v0.21.0.txt b/doc/source/whatsnew/v0.21.0.txt index 308c9cb12d0903..63947dc76a8c55 100644 --- a/doc/source/whatsnew/v0.21.0.txt +++ b/doc/source/whatsnew/v0.21.0.txt @@ -193,18 +193,18 @@ We have updated our minimum supported versions of dependencies (:issue:`15206`, .. _whatsnew_0210.api_breaking.loc: -Indexing with a list-like containing missing keys is Deprecated -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Indexing with missing list-of-labels is Deprecated +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Previously, selecting at least 1 valid key with a list-like indexer would succeed and return ``NaN`` for non-found elements. -This is exactly the function of ``.reindex()``. This will now show a ``FutureWarning`` message; in the future this will raise ``KeyError`` (:issue:`15747`). -This warning will trigger on a ``DataFrame`` or a ``Series`` for using ``.loc[]`` on the Index, or ``[[]]`` on a ``Series``. +Previously, selecting at least 1 valid label with a list-like indexer would always succeed, returning ``NaN`` for missing labels. +This will now show a ``FutureWarning``, in the future this will raise a ``KeyError`` (:issue:`15747`). +This warning will trigger on a ``DataFrame`` or a ``Series`` for using ``.loc[]`` or ``[[]]`` when passing a list-of-labels with at least 1 missing label. See the :ref:`deprecation docs `. .. ipython:: python - s = Series([1, 2, 3]) + s = pd.Series([1, 2, 3]) s Previous Behavior @@ -223,7 +223,7 @@ Previous Behavior Current Behavior In [4]: s.loc[[1, 2, 3]] - Passing list-likes to .loc with any non-matching elements will raise + Passing list-likes to .loc or [] with any missing label will raise KeyError in the future, you can use .reindex() as an alternative. See the documentation here: diff --git a/pandas/core/indexing.py b/pandas/core/indexing.py index 36d32122fc0c69..782007b71b7afa 100755 --- a/pandas/core/indexing.py +++ b/pandas/core/indexing.py @@ -1437,7 +1437,7 @@ def _has_valid_type(self, key, axis): # code, so we want to avoid warning & then # just raising _missing_key_warning = textwrap.dedent(""" - Passing list-likes to .loc with any non-matching labels will raise + Passing list-likes to .loc or [] with any missing label will raise KeyError in the future, you can use .reindex() as an alternative. See the documentation here: