diff --git a/doc/source/user_guide/timeseries.rst b/doc/source/user_guide/timeseries.rst index 169c0cfbbb87e..354c510b843dd 100644 --- a/doc/source/user_guide/timeseries.rst +++ b/doc/source/user_guide/timeseries.rst @@ -588,10 +588,12 @@ 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), @@ -599,34 +601,30 @@ would include matching times on an included date: 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. diff --git a/doc/source/whatsnew/v1.2.0.rst b/doc/source/whatsnew/v1.2.0.rst index 6f046d3a9379d..c171004f08aab 100644 --- a/doc/source/whatsnew/v1.2.0.rst +++ b/doc/source/whatsnew/v1.2.0.rst @@ -466,7 +466,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`) diff --git a/pandas/core/indexing.py b/pandas/core/indexing.py index f6d14a1c1503c..83a28e3fb9089 100644 --- a/pandas/core/indexing.py +++ b/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, )