DEPR: lower/uppercase strings such as 'y', 'q', 'H', 'MIN', etc. denoting freqs/units for time series, period, and timedelta

doc/source/user_guide/10min.rst

@@ -612,7 +612,7 @@ financial applications. See the :ref:`Time Series section <timeseries>`.
 
    rng = pd.date_range("1/1/2012", periods=100, freq="s")
    ts = pd.Series(np.random.randint(0, 500, len(rng)), index=rng)
-   ts.resample("5Min").sum()
+   ts.resample("5min").sum()
 
 :meth:`Series.tz_localize` localizes a time series to a time zone:
 

doc/source/user_guide/timeseries.rst

@@ -1645,7 +1645,7 @@ Basics
 
    ts = pd.Series(np.random.randint(0, 500, len(rng)), index=rng)
 
-   ts.resample("5Min").sum()
+   ts.resample("5min").sum()
 
 The ``resample`` function is very flexible and allows you to specify many
 different parameters to control the frequency conversion and resampling
@@ -1657,31 +1657,31 @@ a method of the returned object, including ``sum``, ``mean``, ``std``, ``sem``,
 
 .. ipython:: python
 
-   ts.resample("5Min").mean()
+   ts.resample("5min").mean()
 
-   ts.resample("5Min").ohlc()
+   ts.resample("5min").ohlc()
 
-   ts.resample("5Min").max()
+   ts.resample("5min").max()
 
 
 For downsampling, ``closed`` can be set to 'left' or 'right' to specify which
 end of the interval is closed:
 
 .. ipython:: python
 
-   ts.resample("5Min", closed="right").mean()
+   ts.resample("5min", closed="right").mean()
 
-   ts.resample("5Min", closed="left").mean()
+   ts.resample("5min", closed="left").mean()
 
 Parameters like ``label`` are used to manipulate the resulting labels.
 ``label`` specifies whether the result is labeled with the beginning or
 the end of the interval.
 
 .. ipython:: python
 
-   ts.resample("5Min").mean()  # by default label='left'
+   ts.resample("5min").mean()  # by default label='left'
 
-   ts.resample("5Min", label="left").mean()
+   ts.resample("5min", label="left").mean()
 
 .. warning::
 

doc/source/whatsnew/v2.2.0.rst

@@ -408,6 +408,41 @@ For example:
 
     pd.date_range('2020-01-01', periods=3, freq='QE-NOV')
 
+Deprecate lowercase strings ``'w'``, ``'m'``, ``'q'``, etc. and uppercase strings ``'H'``, ``'MIN'``, ``'S'``, etc. for time series, period, and timedelta
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Previously, both ``'h'`` and ``'H'`` were allowed for 'hour' offset/period alias. We now require the case to be correct - check the :ref:`offset aliases <timeseries.offset_aliases>` and the :ref:`period aliases <timeseries.period_aliases>` parts of the docs and make sure you're using the correct one (:issue:`56346`)
+
+Deprecated lowercase strings in favour of uppercase strings denoting:
+
+- period aliases weekly, monthly and bigger frequency
+- offsets aliases representing :class:`DateOffset` subclasses that are a week or bigger (``Week``, ``MonthBegin``, ``MonthEnd``, etc.)
+- timedelta units for week, month or bigger
+
+Deprecated uppercase strings in favour of lowercase strings denoting:
+
+- period aliases hourly, minutely or smaller frequency
+- offsets aliases representing :class:`DateOffset` subclasses that are an hour or smaller (``Hour``, ``Minute``, etc.)
+- timedelta units for hour, minute or smaller
+
+For example:
+
+*Previous behavior*:
+
+.. code-block:: ipython
+
+    In [9]: pd.date_range('2020-01-01', periods=3, freq='H')
+    Out[9]:
+    DatetimeIndex(['2020-01-01 00:00:00', '2020-01-01 01:00:00',
+                   '2020-01-01 02:00:00'],
+                  dtype='datetime64[ns]', freq='H')
+
+*Future behavior*:
+
+.. ipython:: python
+
+    pd.date_range('2020-01-01', periods=3, freq='h')
+
 Deprecated automatic downcasting
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

pandas/_libs/tslibs/dtypes.pyx

@@ -407,8 +407,10 @@ cdef dict c_DEPR_ABBREVS = {
     "L": "ms",
     "l": "ms",
     "U": "us",
+    "US": "us",
     "u": "us",
     "N": "ns",
+    "NS": "ns",
     "n": "ns",
 }
 
@@ -509,7 +511,7 @@ class Resolution(Enum):
                 warnings.warn(
                     f"\'{freq}\' is deprecated and will be removed in a future "
                     f"version. Please use \'{abbrev}\' "
-                    "instead of \'{freq}\'.",
+                    f"instead of \'{freq}\'.",
                     FutureWarning,
                     stacklevel=find_stack_level(),
                 )

pandas/_libs/tslibs/offsets.pyx

@@ -1766,7 +1766,7 @@ cdef class BusinessDay(BusinessMixin):
                     s -= hrs * 3600
                 mts = int(s / 60)
                 if mts != 0:
-                    off_str += str(mts) + "Min"
+                    off_str += str(mts) + "min"
                     s -= mts * 60
                 if s != 0:
                     off_str += str(s) + "s"
@@ -4654,36 +4654,13 @@ _lite_rule_alias = {
     "BYE": "BYE-DEC",    # BYearEnd(month=12),
     "BYS": "BYS-JAN",  # BYearBegin(month=1),
 
-    "Min": "min",
     "min": "min",
     "ms": "ms",
     "us": "us",
     "ns": "ns",
 }
 
-_dont_uppercase = {
-    "h",
-    "bh",
-    "cbh",
-    "MS",
-    "ms",
-    "s",
-    "me",
-    "qe",
-    "qe-dec",
-    "qe-jan",
-    "qe-feb",
-    "qe-mar",
-    "qe-apr",
-    "qe-may",
-    "qe-jun",
-    "qe-jul",
-    "qe-aug",
-    "qe-sep",
-    "qe-oct",
-    "qe-nov",
-    "ye",
-}
+_dont_uppercase = {"h", "bh", "cbh", "MS", "ms", "s"}
 
 
 INVALID_FREQ_ERR_MSG = "Invalid frequency: {0}"
@@ -4702,7 +4679,29 @@ def _get_offset(name: str) -> BaseOffset:
     --------
     _get_offset('EOM') --> BMonthEnd(1)
     """
-    if name.lower() not in _dont_uppercase:
+    if (
+        name not in _lite_rule_alias
+        and (name.upper() in _lite_rule_alias)
+        and name != "ms"
+    ):
+        warnings.warn(
+            f"\'{name}\' is deprecated and will be removed "
+            f"in a future version, please use \'{name.upper()}\' instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+    elif (
+        name not in _lite_rule_alias
+        and (name.lower() in _lite_rule_alias)
+        and name != "MS"
+    ):
+        warnings.warn(
+            f"\'{name}\' is deprecated and will be removed "
+            f"in a future version, please use \'{name.lower()}\' instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+    if name not in _dont_uppercase:
         name = name.upper()
         name = _lite_rule_alias.get(name, name)
         name = _lite_rule_alias.get(name.lower(), name)
@@ -4795,40 +4794,60 @@ cpdef to_offset(freq, bint is_period=False):
 
             tups = zip(split[0::4], split[1::4], split[2::4])
             for n, (sep, stride, name) in enumerate(tups):
-                if is_period is False and name in c_OFFSET_DEPR_FREQSTR:
+                if is_period is False and name.upper() in c_OFFSET_DEPR_FREQSTR:
                     warnings.warn(
                         f"\'{name}\' is deprecated and will be removed "
                         f"in a future version, please use "
-                        f"\'{c_OFFSET_DEPR_FREQSTR.get(name)}\' instead.",
+                        f"\'{c_OFFSET_DEPR_FREQSTR.get(name.upper())}\' instead.",
                         FutureWarning,
                         stacklevel=find_stack_level(),
                     )
-                    name = c_OFFSET_DEPR_FREQSTR[name]
-                if is_period is True and name in c_REVERSE_OFFSET_DEPR_FREQSTR:
-                    if name.startswith("Y"):
+                    name = c_OFFSET_DEPR_FREQSTR[name.upper()]
+                elif (is_period is False and
+                        name != name.upper() and
+                        name.upper() in c_REVERSE_OFFSET_DEPR_FREQSTR):
+                    warnings.warn(
+                        f"\'{name}\' is deprecated and will be removed "
+                        f"in a future version, please use "
+                        f"\'{name.upper()}\' instead.",
+                        FutureWarning,
+                        stacklevel=find_stack_level(),
+                    )
+                    name = name.upper()
+                if is_period is True and name.upper() in c_REVERSE_OFFSET_DEPR_FREQSTR:
+                    if name.upper().startswith("Y"):
                         raise ValueError(
-                            f"for Period, please use \'Y{name[2:]}\' "
+                            f"for Period, please use \'Y{name.upper()[2:]}\' "
                             f"instead of \'{name}\'"
                         )
-                    if (name.startswith("B") or
-                            name.startswith("S") or name.startswith("C")):
+                    if (name.upper().startswith("B") or
+                            name.upper().startswith("S") or
+                            name.upper().startswith("C")):
                         raise ValueError(INVALID_FREQ_ERR_MSG.format(name))
                     else:
                         raise ValueError(
                             f"for Period, please use "
-                            f"\'{c_REVERSE_OFFSET_DEPR_FREQSTR.get(name)}\' "
+                            f"\'{c_REVERSE_OFFSET_DEPR_FREQSTR.get(name.upper())}\' "
                             f"instead of \'{name}\'"
                         )
-                elif is_period is True and name in c_OFFSET_DEPR_FREQSTR:
-                    if name.startswith("A"):
+                elif is_period is True and name.upper() in c_OFFSET_DEPR_FREQSTR:
+                    if name.upper().startswith("A"):
                         warnings.warn(
                             f"\'{name}\' is deprecated and will be removed in a future "
-                            f"version, please use \'{c_DEPR_ABBREVS.get(name)}\' "
+                            f"version, please use "
+                            f"\'{c_DEPR_ABBREVS.get(name.upper())}\' instead.",
+                            FutureWarning,
+                            stacklevel=find_stack_level(),
+                        )
+                    if name.upper() != name:
+                        warnings.warn(
+                            f"\'{name}\' is deprecated and will be removed in "
+                            f"a future version, please use \'{name.upper()}\' "
                             f"instead.",
                             FutureWarning,
                             stacklevel=find_stack_level(),
                         )
-                    name = c_OFFSET_DEPR_FREQSTR.get(name)
+                    name = c_OFFSET_DEPR_FREQSTR.get(name.upper())
 
                 if sep != "" and not sep.isspace():
                     raise ValueError("separator must be spaces")

pandas/_libs/tslibs/timedeltas.pyx

@@ -719,15 +719,24 @@ cpdef inline str parse_timedelta_unit(str unit):
         return "ns"
     elif unit == "M":
         return unit
-    elif unit in c_DEPR_ABBREVS:
+    elif unit.upper() == "MIN" and unit.lower() != unit:
         warnings.warn(
             f"\'{unit}\' is deprecated and will be removed in a "
-            f"future version. Please use \'{c_DEPR_ABBREVS.get(unit)}\' "
+            f"future version. Please use \'{unit.lower()}\' "
             f"instead of \'{unit}\'.",
             FutureWarning,
             stacklevel=find_stack_level(),
         )
-        unit = c_DEPR_ABBREVS[unit]
+        unit = unit.lower()
+    elif unit.upper() in c_DEPR_ABBREVS and unit != c_DEPR_ABBREVS.get(unit.upper()):
+        warnings.warn(
+            f"\'{unit}\' is deprecated and will be removed in a "
+            f"future version. Please use \'{c_DEPR_ABBREVS.get(unit.upper())}\' "
+            f"instead of \'{unit}\'.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        unit = c_DEPR_ABBREVS[unit.upper()]
     try:
         return timedelta_abbrevs[unit.lower()]
     except KeyError:

pandas/tests/arrays/test_datetimes.py

@@ -784,6 +784,43 @@ def test_date_range_frequency_M_Q_Y_A_deprecated(self, freq, freq_depr):
             result = pd.date_range("1/1/2000", periods=4, freq=freq_depr)
         tm.assert_index_equal(result, expected)
 
+    @pytest.mark.parametrize(
+        "freq, freq_depr",
+        [
+            ("2h", "2H"),
+            ("2s", "2S"),
+        ],
+    )
+    def test_date_range_uppercase_frequency_deprecated(self, freq, freq_depr):
+        # GH#9586, GH#54939
+        depr_msg = f"'{freq_depr[1:]}' is deprecated and will be removed in a "
+        f"future version. Please use '{freq[1:]}' instead."
+
+        expected = pd.date_range("1/1/2000", periods=4, freq=freq)
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            result = pd.date_range("1/1/2000", periods=4, freq=freq_depr)
+        tm.assert_index_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "freq, freq_depr",
+        [
+            ("2ME", "2me"),
+            ("2ME", "2m"),
+            ("2QE-SEP", "2q-sep"),
+            ("2W", "2w"),
+            ("2min", "2MIN"),
+        ],
+    )
+    def test_date_range_lowercase_frequency_deprecated(self, freq, freq_depr):
+        # GH#9586, GH#54939
+        depr_msg = f"'{freq_depr[1:]}' is deprecated and will be removed in a "
+        f"future version, please use '{freq[1:]}' instead."
+
+        expected = pd.date_range("1/1/2000", periods=4, freq=freq)
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            result = pd.date_range("1/1/2000", periods=4, freq=freq_depr)
+        tm.assert_index_equal(result, expected)
+
 
 def test_factorize_sort_without_freq():
     dta = DatetimeArray._from_sequence([0, 2, 1], dtype="M8[ns]")

pandas/tests/frame/methods/test_at_time.py

@@ -58,7 +58,7 @@ def test_at_time_midnight(self, frame_or_series):
 
     def test_at_time_nonexistent(self, frame_or_series):
         # time doesn't exist
-        rng = date_range("1/1/2012", freq="23Min", periods=384)
+        rng = date_range("1/1/2012", freq="23min", periods=384)
         ts = DataFrame(np.random.default_rng(2).standard_normal(len(rng)), rng)
         ts = tm.get_obj(ts, frame_or_series)
         rs = ts.at_time("16:00")

pandas/tests/indexes/datetimes/methods/test_repeat.py

@@ -63,7 +63,7 @@ def test_repeat(self, tz_naive_fixture, unit):
         reps = 2
         msg = "the 'axis' parameter is not supported"
 
-        rng = date_range(start="2016-01-01", periods=2, freq="30Min", tz=tz, unit=unit)
+        rng = date_range(start="2016-01-01", periods=2, freq="30min", tz=tz, unit=unit)
 
         expected_rng = DatetimeIndex(
             [

pandas/tests/indexes/datetimes/methods/test_round.py

@@ -42,7 +42,7 @@ def test_round_invalid(self, freq, error_msg):
 
     def test_round(self, tz_naive_fixture, unit):
         tz = tz_naive_fixture
-        rng = date_range(start="2016-01-01", periods=5, freq="30Min", tz=tz, unit=unit)
+        rng = date_range(start="2016-01-01", periods=5, freq="30min", tz=tz, unit=unit)
         elt = rng[1]
 
         expected_rng = DatetimeIndex(
@@ -104,7 +104,7 @@ def test_round4(self, tz_naive_fixture):
     def test_no_rounding_occurs(self, tz_naive_fixture):
         # GH 21262
         tz = tz_naive_fixture
-        rng = date_range(start="2016-01-01", periods=5, freq="2Min", tz=tz)
+        rng = date_range(start="2016-01-01", periods=5, freq="2min", tz=tz)
 
         expected_rng = DatetimeIndex(
             [

pandas/tests/indexes/datetimes/test_partial_slicing.py

@@ -236,7 +236,7 @@ def test_partial_slice_second_precision(self):
         rng = date_range(
             start=datetime(2005, 1, 1, 0, 0, 59, microsecond=999990),
             periods=20,
-            freq="US",
+            freq="us",
         )
         s = Series(np.arange(20), rng)