DOC: clarify docs related to deprecation of indexing DataFrame with single partial datetime-string (#38088)

Author: jorisvandenbossche

doc/source/user_guide/timeseries.rst

@@ -588,45 +588,43 @@ would include matching times on an included date:
 
 .. warning::
 
-   Indexing ``DataFrame`` rows with strings is deprecated in pandas 1.2.0 and will be removed in a future version.  Use ``frame.loc[dtstring]`` instead.
+   Indexing ``DataFrame`` rows with a *single* string with getitem (e.g. ``frame[dtstring]``)
+   is deprecated starting with pandas 1.2.0 (given the ambiguity whether it is indexing
+   the rows or selecting a column) and will be removed in a future version. The equivalent
+   with ``.loc`` (e.g. ``frame.loc[dtstring]``) is still supported.
 
 .. ipython:: python
-   :okwarning:
 
    dft = pd.DataFrame(
        np.random.randn(100000, 1),
        columns=["A"],
        index=pd.date_range("20130101", periods=100000, freq="T"),
    )
    dft
-   dft["2013"]
+   dft.loc["2013"]
 
 This starts on the very first time in the month, and includes the last date and
 time for the month:
 
 .. ipython:: python
-   :okwarning:
 
    dft["2013-1":"2013-2"]
 
 This specifies a stop time **that includes all of the times on the last day**:
 
 .. ipython:: python
-   :okwarning:
 
    dft["2013-1":"2013-2-28"]
 
 This specifies an **exact** stop time (and is not the same as the above):
 
 .. ipython:: python
-   :okwarning:
 
    dft["2013-1":"2013-2-28 00:00:00"]
 
 We are stopping on the included end-point as it is part of the index:
 
 .. ipython:: python
-   :okwarning:
 
    dft["2013-1-15":"2013-1-15 12:30:00"]
 
@@ -652,7 +650,6 @@ We are stopping on the included end-point as it is part of the index:
 Slicing with string indexing also honors UTC offset.
 
 .. ipython:: python
-   :okwarning:
 
     df = pd.DataFrame([0], index=pd.DatetimeIndex(["2019-01-01"], tz="US/Pacific"))
     df
@@ -704,15 +701,14 @@ If index resolution is second, then the minute-accurate timestamp gives a
     series_second.index.resolution
     series_second["2011-12-31 23:59"]
 
-If the timestamp string is treated as a slice, it can be used to index ``DataFrame`` with ``[]`` as well.
+If the timestamp string is treated as a slice, it can be used to index ``DataFrame`` with ``.loc[]`` as well.
 
 .. ipython:: python
-    :okwarning:
 
     dft_minute = pd.DataFrame(
         {"a": [1, 2, 3], "b": [4, 5, 6]}, index=series_minute.index
     )
-    dft_minute["2011-12-31 23"]
+    dft_minute.loc["2011-12-31 23"]
 
 
 .. warning::
@@ -2080,7 +2076,6 @@ You can pass in dates and strings to ``Series`` and ``DataFrame`` with ``PeriodI
 Passing a string representing a lower frequency than ``PeriodIndex`` returns partial sliced data.
 
 .. ipython:: python
-   :okwarning:
 
    ps["2011"]
 
@@ -2090,7 +2085,7 @@ Passing a string representing a lower frequency than ``PeriodIndex`` returns par
        index=pd.period_range("2013-01-01 9:00", periods=600, freq="T"),
    )
    dfp
-   dfp["2013-01-01 10H"]
+   dfp.loc["2013-01-01 10H"]
 
 As with ``DatetimeIndex``, the endpoints will be included in the result. The example below slices data starting from 10:00 to 11:59.
 

doc/source/whatsnew/v1.2.0.rst

@@ -467,7 +467,9 @@ Deprecations
 - Date parser functions :func:`~pandas.io.date_converters.parse_date_time`, :func:`~pandas.io.date_converters.parse_date_fields`, :func:`~pandas.io.date_converters.parse_all_fields` and :func:`~pandas.io.date_converters.generic_parser` from ``pandas.io.date_converters`` are deprecated and will be removed in a future version; use :func:`to_datetime` instead (:issue:`35741`)
 - :meth:`DataFrame.lookup` is deprecated and will be removed in a future version, use :meth:`DataFrame.melt` and :meth:`DataFrame.loc` instead (:issue:`18682`)
 - The method :meth:`Index.to_native_types` is deprecated. Use ``.astype(str)`` instead (:issue:`28867`)
-- Deprecated indexing :class:`DataFrame` rows with datetime-like strings ``df[string]``, use ``df.loc[string]`` instead (:issue:`36179`)
+- Deprecated indexing :class:`DataFrame` rows with a single datetime-like string as ``df[string]``
+  (given the ambiguity whether it is indexing the rows or selecting a column), use
+  ``df.loc[string]`` instead (:issue:`36179`)
 - Deprecated casting an object-dtype index of ``datetime`` objects to :class:`.DatetimeIndex` in the :class:`Series` constructor (:issue:`23598`)
 - Deprecated :meth:`Index.is_all_dates` (:issue:`27744`)
 - The default value of ``regex`` for :meth:`Series.str.replace` will change from ``True`` to ``False`` in a future release. In addition, single character regular expressions will *not* be treated as literal strings when ``regex=True`` is set. (:issue:`24804`)

pandas/core/indexing.py

@@ -2199,9 +2199,10 @@ def convert_to_index_sliceable(obj: "DataFrame", key):
             try:
                 res = idx._get_string_slice(key)
                 warnings.warn(
-                    "Indexing on datetimelike rows with `frame[string]` is "
-                    "deprecated and will be removed in a future version. "
-                    "Use `frame.loc[string]` instead.",
+                    "Indexing a DataFrame with a datetimelike index using a single "
+                    "string to slice the rows, like `frame[string]`, is deprecated "
+                    "and will be removed in a future version. Use `frame.loc[string]` "
+                    "instead.",
                     FutureWarning,
                     stacklevel=3,
                 )