review comments

doc/source/indexing.rst

@@ -644,22 +644,22 @@ 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()``.
 
 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:
 

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 <indexing.deprecate_loc_reindex_listlike>`.
 
 
 .. 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:

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: