DEPR: deprecate string H, BH, CBH in offsets frequencies, resolution abbreviations, _attrname_to_abbrevs

doc/source/user_guide/advanced.rst

@@ -976,7 +976,7 @@ of :ref:`frequency aliases <timeseries.offset_aliases>` with datetime-like inter
 
    pd.interval_range(start=pd.Timestamp("2017-01-01"), periods=4, freq="W")
 
-   pd.interval_range(start=pd.Timedelta("0 days"), periods=3, freq="9H")
+   pd.interval_range(start=pd.Timedelta("0 days"), periods=3, freq="9h")
 
 Additionally, the ``closed`` parameter can be used to specify which side(s) the intervals
 are closed on.  Intervals are closed on the right side by default.

doc/source/user_guide/timedeltas.rst

@@ -392,7 +392,7 @@ The ``freq`` parameter can passed a variety of :ref:`frequency aliases <timeseri
 
    pd.timedelta_range(start="1 days", end="2 days", freq="30min")
 
-   pd.timedelta_range(start="1 days", periods=5, freq="2D5H")
+   pd.timedelta_range(start="1 days", periods=5, freq="2D5h")
 
 
 Specifying ``start``, ``end``, and ``periods`` will generate a range of evenly spaced

doc/source/user_guide/timeseries.rst

@@ -28,7 +28,7 @@ Generate sequences of fixed-frequency dates and time spans
 
 .. ipython:: python
 
-   dti = pd.date_range("2018-01-01", periods=3, freq="H")
+   dti = pd.date_range("2018-01-01", periods=3, freq="h")
    dti
 
 Manipulating and converting date times with timezone information
@@ -43,10 +43,10 @@ Resampling or converting a time series to a particular frequency
 
 .. ipython:: python
 
-   idx = pd.date_range("2018-01-01", periods=5, freq="H")
+   idx = pd.date_range("2018-01-01", periods=5, freq="h")
    ts = pd.Series(range(len(idx)), index=idx)
    ts
-   ts.resample("2H").mean()
+   ts.resample("2h").mean()
 
 Performing date and time arithmetic with absolute or relative time increments
 
@@ -641,7 +641,7 @@ We are stopping on the included end-point as it is part of the index:
        np.random.randn(20, 1),
        columns=["A"],
        index=pd.MultiIndex.from_product(
-           [pd.date_range("20130101", periods=10, freq="12H"), ["a", "b"]]
+           [pd.date_range("20130101", periods=10, freq="12h"), ["a", "b"]]
        ),
    )
    dft2
@@ -901,10 +901,10 @@ into ``freq`` keyword arguments. The available date offsets and associated frequ
     :class:`~pandas.tseries.offsets.BYearBegin`, ``'BAS'``, "business year begin"
     :class:`~pandas.tseries.offsets.FY5253`, ``'RE'``, "retail (aka 52-53 week) year"
     :class:`~pandas.tseries.offsets.Easter`, None, "Easter holiday"
-    :class:`~pandas.tseries.offsets.BusinessHour`, ``'BH'``, "business hour"
-    :class:`~pandas.tseries.offsets.CustomBusinessHour`, ``'CBH'``, "custom business hour"
+    :class:`~pandas.tseries.offsets.BusinessHour`, ``'bh'``, "business hour"
+    :class:`~pandas.tseries.offsets.CustomBusinessHour`, ``'cbh'``, "custom business hour"
     :class:`~pandas.tseries.offsets.Day`, ``'D'``, "one absolute day"
-    :class:`~pandas.tseries.offsets.Hour`, ``'H'``, "one hour"
+    :class:`~pandas.tseries.offsets.Hour`, ``'h'``, "one hour"
     :class:`~pandas.tseries.offsets.Minute`, ``'min'``,"one minute"
     :class:`~pandas.tseries.offsets.Second`, ``'s'``, "one second"
     :class:`~pandas.tseries.offsets.Milli`, ``'ms'``, "one millisecond"
@@ -1262,8 +1262,9 @@ frequencies. We will refer to these aliases as *offset aliases*.
     "BA, BY", "business year end frequency"
     "AS, YS", "year start frequency"
     "BAS, BYS", "business year start frequency"
-    "BH", "business hour frequency"
-    "H", "hourly frequency"
+    "h", "hourly frequency"
+    "bh", "business hour frequency"
+    "cbh", "custom business hour frequency"
     "min", "minutely frequency"
     "s", "secondly frequency"
     "ms", "milliseconds"
@@ -1272,7 +1273,8 @@ frequencies. We will refer to these aliases as *offset aliases*.
 
 .. deprecated:: 2.2.0
 
-   Aliases ``T``, ``S``, ``L``, ``U``, and ``N`` are deprecated in favour of the aliases
+   Aliases ``H``, ``BH``, ``CBH``, ``T``, ``S``, ``L``, ``U``, and ``N``
+   are deprecated in favour of the aliases ``h``, ``bh``, ``cbh``,
    ``min``, ``s``, ``ms``, ``us``, and ``ns``.
 
 .. note::
@@ -1322,7 +1324,7 @@ frequencies. We will refer to these aliases as *period aliases*.
     "M", "monthly frequency"
     "Q", "quarterly frequency"
     "Y", "yearly frequency"
-    "H", "hourly frequency"
+    "h", "hourly frequency"
     "min", "minutely frequency"
     "s", "secondly frequency"
     "ms", "milliseconds"
@@ -1331,8 +1333,8 @@ frequencies. We will refer to these aliases as *period aliases*.
 
 .. deprecated:: 2.2.0
 
-   Aliases ``A``, ``T``, ``S``, ``L``, ``U``, and ``N`` are deprecated in favour of the aliases
-   ``Y``, ``min``, ``s``, ``ms``, ``us``, and ``ns``.
+   Aliases ``A``, ``H``, ``T``, ``S``, ``L``, ``U``, and ``N`` are deprecated in favour of the aliases
+   ``Y``, ``h``, ``min``, ``s``, ``ms``, ``us``, and ``ns``.
 
 
 Combining aliases
@@ -1889,7 +1891,7 @@ natural and functions similarly to :py:func:`itertools.groupby`:
            ]
        ),
    )
-   resampled = small.resample("H")
+   resampled = small.resample("h")
 
    for name, group in resampled:
        print("Group: ", name)
@@ -1999,9 +2001,9 @@ Because ``freq`` represents a span of ``Period``, it cannot be negative like "-3
 
    pd.Period("2012-1-1", freq="D")
 
-   pd.Period("2012-1-1 19:00", freq="H")
+   pd.Period("2012-1-1 19:00", freq="h")
 
-   pd.Period("2012-1-1 19:00", freq="5H")
+   pd.Period("2012-1-1 19:00", freq="5h")
 
 Adding and subtracting integers from periods shifts the period by its own
 frequency. Arithmetic is not allowed between ``Period`` with different ``freq`` (span).
@@ -2021,7 +2023,7 @@ If ``Period`` freq is daily or higher (``D``, ``H``, ``T``, ``S``, ``L``, ``U``,
 
 .. ipython:: python
 
-   p = pd.Period("2014-07-01 09:00", freq="H")
+   p = pd.Period("2014-07-01 09:00", freq="h")
    p + pd.offsets.Hour(2)
    p + datetime.timedelta(minutes=120)
    p + np.timedelta64(7200, "s")
@@ -2097,7 +2099,7 @@ objects:
 
 .. ipython:: python
 
-   idx = pd.period_range("2014-07-01 09:00", periods=5, freq="H")
+   idx = pd.period_range("2014-07-01 09:00", periods=5, freq="h")
    idx
    idx + pd.offsets.Hour(2)
 
@@ -2168,13 +2170,13 @@ Passing a string representing a lower frequency than ``PeriodIndex`` returns par
        index=pd.period_range("2013-01-01 9:00", periods=600, freq="min"),
    )
    dfp
-   dfp.loc["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.
 
 .. ipython:: python
 
-   dfp["2013-01-01 10H":"2013-01-01 11H"]
+   dfp["2013-01-01 10h":"2013-01-01 11h"]
 
 
 Frequency conversion and resampling with PeriodIndex
@@ -2286,7 +2288,7 @@ the quarter end:
 
    ts = pd.Series(np.random.randn(len(prng)), prng)
 
-   ts.index = (prng.asfreq("M", "e") + 1).asfreq("H", "s") + 9
+   ts.index = (prng.asfreq("M", "e") + 1).asfreq("h", "s") + 9
 
    ts.head()
 
@@ -2505,7 +2507,7 @@ To remove time zone information, use ``tz_localize(None)`` or ``tz_convert(None)
 
 .. ipython:: python
 
-   didx = pd.date_range(start="2014-08-01 09:00", freq="H", periods=3, tz="US/Eastern")
+   didx = pd.date_range(start="2014-08-01 09:00", freq="h", periods=3, tz="US/Eastern")
    didx
    didx.tz_localize(None)
    didx.tz_convert(None)
@@ -2602,7 +2604,7 @@ can be controlled by the ``nonexistent`` argument. The following options are ava
 
 .. ipython:: python
 
-    dti = pd.date_range(start="2015-03-29 02:30:00", periods=3, freq="H")
+    dti = pd.date_range(start="2015-03-29 02:30:00", periods=3, freq="h")
     # 2:30 is a nonexistent time
 
 Localization of nonexistent times will raise an error by default.
@@ -2619,7 +2621,7 @@ Transform nonexistent times to ``NaT`` or shift the times.
     dti
     dti.tz_localize("Europe/Warsaw", nonexistent="shift_forward")
     dti.tz_localize("Europe/Warsaw", nonexistent="shift_backward")
-    dti.tz_localize("Europe/Warsaw", nonexistent=pd.Timedelta(1, unit="H"))
+    dti.tz_localize("Europe/Warsaw", nonexistent=pd.Timedelta(1, unit="h"))
     dti.tz_localize("Europe/Warsaw", nonexistent="NaT")
 
 

doc/source/whatsnew/v0.14.0.rst

@@ -880,12 +880,41 @@ Enhancements
 
 - ``PeriodIndex`` fully supports partial string indexing like ``DatetimeIndex`` (:issue:`7043`)
 
-  .. ipython:: python
+  .. code-block:: ipython
 
-     prng = pd.period_range('2013-01-01 09:00', periods=100, freq='H')
-     ps = pd.Series(np.random.randn(len(prng)), index=prng)
-     ps
-     ps['2013-01-02']
+     In [76]: prng = pd.period_range('2013-01-01 09:00', periods=100, freq='H')
+
+     In [77]: ps = pd.Series(np.random.randn(len(prng)), index=prng)
+
+     In [78]: ps
+     Out[78]:
+     2013-01-01 09:00    0.015696
+     2013-01-01 10:00   -2.242685
+     2013-01-01 11:00    1.150036
+     2013-01-01 12:00    0.991946
+     2013-01-01 13:00    0.953324
+                           ...
+     2013-01-05 08:00    0.285296
+     2013-01-05 09:00    0.484288
+     2013-01-05 10:00    1.363482
+     2013-01-05 11:00   -0.781105
+     2013-01-05 12:00   -0.468018
+     Freq: H, Length: 100, dtype: float64
+
+     In [79]: ps['2013-01-02']
+     Out[79]:
+     2013-01-02 00:00    0.553439
+     2013-01-02 01:00    1.318152
+     2013-01-02 02:00   -0.469305
+     2013-01-02 03:00    0.675554
+     2013-01-02 04:00   -1.817027
+                           ...
+     2013-01-02 19:00    0.036142
+     2013-01-02 20:00   -2.074978
+     2013-01-02 21:00    0.247792
+     2013-01-02 22:00   -0.897157
+     2013-01-02 23:00   -0.136795
+     Freq: H, Length: 24, dtype: float64
 
 - ``read_excel`` can now read milliseconds in Excel dates and times with xlrd >= 0.9.3. (:issue:`5945`)
 - ``pd.stats.moments.rolling_var`` now uses Welford's method for increased numerical stability (:issue:`6817`)

doc/source/whatsnew/v0.15.0.rst

@@ -332,16 +332,37 @@ Timezone handling improvements
 - ``tz_localize(None)`` for tz-aware ``Timestamp`` and ``DatetimeIndex`` now removes timezone holding local time,
   previously this resulted in ``Exception`` or ``TypeError`` (:issue:`7812`)
 
-  .. ipython:: python
+  .. code-block:: ipython
+
+     In [58]: ts = pd.Timestamp('2014-08-01 09:00', tz='US/Eastern')
+
+     In[59]: ts
+     Out[59]: Timestamp('2014-08-01 09:00:00-0400', tz='US/Eastern')
 
-     ts = pd.Timestamp('2014-08-01 09:00', tz='US/Eastern')
-     ts
-     ts.tz_localize(None)
+     In [60]: ts.tz_localize(None)
+     Out[60]: Timestamp('2014-08-01 09:00:00')
 
-     didx = pd.date_range(start='2014-08-01 09:00', freq='H',
-                          periods=10, tz='US/Eastern')
-     didx
-     didx.tz_localize(None)
+     In [61]: didx = pd.date_range(start='2014-08-01 09:00', freq='H',
+        ....:                      periods=10, tz='US/Eastern')
+        ....:
+
+     In [62]: didx
+     Out[62]:
+     DatetimeIndex(['2014-08-01 09:00:00-04:00', '2014-08-01 10:00:00-04:00',
+                    '2014-08-01 11:00:00-04:00', '2014-08-01 12:00:00-04:00',
+                    '2014-08-01 13:00:00-04:00', '2014-08-01 14:00:00-04:00',
+                    '2014-08-01 15:00:00-04:00', '2014-08-01 16:00:00-04:00',
+                    '2014-08-01 17:00:00-04:00', '2014-08-01 18:00:00-04:00'],
+                   dtype='datetime64[ns, US/Eastern]', freq='H')
+
+     In [63]: didx.tz_localize(None)
+     Out[63]:
+     DatetimeIndex(['2014-08-01 09:00:00', '2014-08-01 10:00:00',
+                    '2014-08-01 11:00:00', '2014-08-01 12:00:00',
+                    '2014-08-01 13:00:00', '2014-08-01 14:00:00',
+                    '2014-08-01 15:00:00', '2014-08-01 16:00:00',
+                    '2014-08-01 17:00:00', '2014-08-01 18:00:00'],
+                   dtype='datetime64[ns]', freq=None)
 
 - ``tz_localize`` now accepts the ``ambiguous`` keyword which allows for passing an array of bools
   indicating whether the date belongs in DST or not, 'NaT' for setting transition times to NaT,
@@ -1050,16 +1071,35 @@ Other:
 
   If ``Period`` freq is ``D``, ``H``, ``T``, ``S``, ``L``, ``U``, ``N``, ``Timedelta``-like can be added if the result can have same freq. Otherwise, only the same ``offsets`` can be added.
 
-  .. ipython:: python
+  .. code-block:: ipython
 
-     idx = pd.period_range('2014-07-01 09:00', periods=5, freq='H')
-     idx
-     idx + pd.offsets.Hour(2)
-     idx + pd.Timedelta('120m')
+     In [104]: idx = pd.period_range('2014-07-01 09:00', periods=5, freq='H')
 
-     idx = pd.period_range('2014-07', periods=5, freq='M')
-     idx
-     idx + pd.offsets.MonthEnd(3)
+     In [105]: idx
+     Out[105]:
+     PeriodIndex(['2014-07-01 09:00', '2014-07-01 10:00', '2014-07-01 11:00',
+                  '2014-07-01 12:00', '2014-07-01 13:00'],
+                 dtype='period[H]')
+
+     In [106]: idx + pd.offsets.Hour(2)
+     Out[106]:
+     PeriodIndex(['2014-07-01 11:00', '2014-07-01 12:00', '2014-07-01 13:00',
+                  '2014-07-01 14:00', '2014-07-01 15:00'],
+                 dtype='period[H]')
+
+     In [107]: idx + pd.Timedelta('120m')
+     Out[107]:
+     PeriodIndex(['2014-07-01 11:00', '2014-07-01 12:00', '2014-07-01 13:00',
+                  '2014-07-01 14:00', '2014-07-01 15:00'],
+                 dtype='period[H]')
+
+     In [108]: idx = pd.period_range('2014-07', periods=5, freq='M')
+
+     In [109]: idx
+     Out[109]: PeriodIndex(['2014-07', '2014-08', '2014-09', '2014-10', '2014-11'], dtype='period[M]')
+
+     In [110]: idx + pd.offsets.MonthEnd(3)
+     Out[110]: PeriodIndex(['2014-10', '2014-11', '2014-12', '2015-01', '2015-02'], dtype='period[M]')
 
 - Added experimental compatibility with ``openpyxl`` for versions >= 2.0. The ``DataFrame.to_excel``
   method ``engine`` keyword now recognizes ``openpyxl1`` and ``openpyxl2``

doc/source/whatsnew/v0.18.0.rst

@@ -1000,10 +1000,16 @@ Other API changes
 ^^^^^^^^^^^^^^^^^
 - ``DataFrame.between_time`` and ``Series.between_time`` now only parse a fixed set of time strings. Parsing of date strings is no longer supported and raises a ``ValueError``. (:issue:`11818`)
 
-  .. ipython:: python
+  .. code-block:: ipython
+
+     In [107]: s = pd.Series(range(10), pd.date_range('2015-01-01', freq='H', periods=10))
 
-     s = pd.Series(range(10), pd.date_range('2015-01-01', freq='H', periods=10))
-     s.between_time("7:00am", "9:00am")
+     In [108]: s.between_time("7:00am", "9:00am")
+     Out[108]:
+     2015-01-01 07:00:00    7
+     2015-01-01 08:00:00    8
+     2015-01-01 09:00:00    9
+     Freq: H, Length: 3, dtype: int64
 
   This will now raise.