Skip to content

Commit a0babcb

Browse files
authored
DEPR: deprecate string H, BH, CBH in offsets frequencies, resolution abbreviations, _attrname_to_abbrevs (#54939)
* deprecate H in favour of h, fix tests * correct def _maybe_coerce_freq, fix tests * fix tests * correct cdef parse_iso_format_string, fix tests * deprecate BH, CBH and fix tests * fix docs * correct whatsnew * fix pre-commit errors * fix errors in v1.5.0.rst and docs * fix errors in whatsnew and docs * add tests for FutureWarning, update v2.2.0.rst * correct tables of Offset/Period aliases * correct tests * correct def to_offset, add tests * change the condition to _prefix.startswith(('c')) * correct def to_offset
1 parent fe5f0c9 commit a0babcb

File tree

180 files changed

+1298
-1045
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

180 files changed

+1298
-1045
lines changed

doc/source/user_guide/advanced.rst

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

doc/source/user_guide/timedeltas.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -392,7 +392,7 @@ The ``freq`` parameter can passed a variety of :ref:`frequency aliases <timeseri
392392
393393
pd.timedelta_range(start="1 days", end="2 days", freq="30min")
394394
395-
pd.timedelta_range(start="1 days", periods=5, freq="2D5H")
395+
pd.timedelta_range(start="1 days", periods=5, freq="2D5h")
396396
397397
398398
Specifying ``start``, ``end``, and ``periods`` will generate a range of evenly spaced

doc/source/user_guide/timeseries.rst

+26-24
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ Generate sequences of fixed-frequency dates and time spans
2828

2929
.. ipython:: python
3030
31-
dti = pd.date_range("2018-01-01", periods=3, freq="H")
31+
dti = pd.date_range("2018-01-01", periods=3, freq="h")
3232
dti
3333
3434
Manipulating and converting date times with timezone information
@@ -43,10 +43,10 @@ Resampling or converting a time series to a particular frequency
4343

4444
.. ipython:: python
4545
46-
idx = pd.date_range("2018-01-01", periods=5, freq="H")
46+
idx = pd.date_range("2018-01-01", periods=5, freq="h")
4747
ts = pd.Series(range(len(idx)), index=idx)
4848
ts
49-
ts.resample("2H").mean()
49+
ts.resample("2h").mean()
5050
5151
Performing date and time arithmetic with absolute or relative time increments
5252

@@ -641,7 +641,7 @@ We are stopping on the included end-point as it is part of the index:
641641
np.random.randn(20, 1),
642642
columns=["A"],
643643
index=pd.MultiIndex.from_product(
644-
[pd.date_range("20130101", periods=10, freq="12H"), ["a", "b"]]
644+
[pd.date_range("20130101", periods=10, freq="12h"), ["a", "b"]]
645645
),
646646
)
647647
dft2
@@ -901,10 +901,10 @@ into ``freq`` keyword arguments. The available date offsets and associated frequ
901901
:class:`~pandas.tseries.offsets.BYearBegin`, ``'BAS'``, "business year begin"
902902
:class:`~pandas.tseries.offsets.FY5253`, ``'RE'``, "retail (aka 52-53 week) year"
903903
:class:`~pandas.tseries.offsets.Easter`, None, "Easter holiday"
904-
:class:`~pandas.tseries.offsets.BusinessHour`, ``'BH'``, "business hour"
905-
:class:`~pandas.tseries.offsets.CustomBusinessHour`, ``'CBH'``, "custom business hour"
904+
:class:`~pandas.tseries.offsets.BusinessHour`, ``'bh'``, "business hour"
905+
:class:`~pandas.tseries.offsets.CustomBusinessHour`, ``'cbh'``, "custom business hour"
906906
:class:`~pandas.tseries.offsets.Day`, ``'D'``, "one absolute day"
907-
:class:`~pandas.tseries.offsets.Hour`, ``'H'``, "one hour"
907+
:class:`~pandas.tseries.offsets.Hour`, ``'h'``, "one hour"
908908
:class:`~pandas.tseries.offsets.Minute`, ``'min'``,"one minute"
909909
:class:`~pandas.tseries.offsets.Second`, ``'s'``, "one second"
910910
:class:`~pandas.tseries.offsets.Milli`, ``'ms'``, "one millisecond"
@@ -1262,8 +1262,9 @@ frequencies. We will refer to these aliases as *offset aliases*.
12621262
"BA, BY", "business year end frequency"
12631263
"AS, YS", "year start frequency"
12641264
"BAS, BYS", "business year start frequency"
1265-
"BH", "business hour frequency"
1266-
"H", "hourly frequency"
1265+
"h", "hourly frequency"
1266+
"bh", "business hour frequency"
1267+
"cbh", "custom business hour frequency"
12671268
"min", "minutely frequency"
12681269
"s", "secondly frequency"
12691270
"ms", "milliseconds"
@@ -1272,7 +1273,8 @@ frequencies. We will refer to these aliases as *offset aliases*.
12721273

12731274
.. deprecated:: 2.2.0
12741275

1275-
Aliases ``T``, ``S``, ``L``, ``U``, and ``N`` are deprecated in favour of the aliases
1276+
Aliases ``H``, ``BH``, ``CBH``, ``T``, ``S``, ``L``, ``U``, and ``N``
1277+
are deprecated in favour of the aliases ``h``, ``bh``, ``cbh``,
12761278
``min``, ``s``, ``ms``, ``us``, and ``ns``.
12771279

12781280
.. note::
@@ -1322,7 +1324,7 @@ frequencies. We will refer to these aliases as *period aliases*.
13221324
"M", "monthly frequency"
13231325
"Q", "quarterly frequency"
13241326
"Y", "yearly frequency"
1325-
"H", "hourly frequency"
1327+
"h", "hourly frequency"
13261328
"min", "minutely frequency"
13271329
"s", "secondly frequency"
13281330
"ms", "milliseconds"
@@ -1331,8 +1333,8 @@ frequencies. We will refer to these aliases as *period aliases*.
13311333

13321334
.. deprecated:: 2.2.0
13331335

1334-
Aliases ``A``, ``T``, ``S``, ``L``, ``U``, and ``N`` are deprecated in favour of the aliases
1335-
``Y``, ``min``, ``s``, ``ms``, ``us``, and ``ns``.
1336+
Aliases ``A``, ``H``, ``T``, ``S``, ``L``, ``U``, and ``N`` are deprecated in favour of the aliases
1337+
``Y``, ``h``, ``min``, ``s``, ``ms``, ``us``, and ``ns``.
13361338

13371339

13381340
Combining aliases
@@ -1889,7 +1891,7 @@ natural and functions similarly to :py:func:`itertools.groupby`:
18891891
]
18901892
),
18911893
)
1892-
resampled = small.resample("H")
1894+
resampled = small.resample("h")
18931895
18941896
for name, group in resampled:
18951897
print("Group: ", name)
@@ -1999,9 +2001,9 @@ Because ``freq`` represents a span of ``Period``, it cannot be negative like "-3
19992001
20002002
pd.Period("2012-1-1", freq="D")
20012003
2002-
pd.Period("2012-1-1 19:00", freq="H")
2004+
pd.Period("2012-1-1 19:00", freq="h")
20032005
2004-
pd.Period("2012-1-1 19:00", freq="5H")
2006+
pd.Period("2012-1-1 19:00", freq="5h")
20052007
20062008
Adding and subtracting integers from periods shifts the period by its own
20072009
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``,
20212023

20222024
.. ipython:: python
20232025
2024-
p = pd.Period("2014-07-01 09:00", freq="H")
2026+
p = pd.Period("2014-07-01 09:00", freq="h")
20252027
p + pd.offsets.Hour(2)
20262028
p + datetime.timedelta(minutes=120)
20272029
p + np.timedelta64(7200, "s")
@@ -2097,7 +2099,7 @@ objects:
20972099

20982100
.. ipython:: python
20992101
2100-
idx = pd.period_range("2014-07-01 09:00", periods=5, freq="H")
2102+
idx = pd.period_range("2014-07-01 09:00", periods=5, freq="h")
21012103
idx
21022104
idx + pd.offsets.Hour(2)
21032105
@@ -2168,13 +2170,13 @@ Passing a string representing a lower frequency than ``PeriodIndex`` returns par
21682170
index=pd.period_range("2013-01-01 9:00", periods=600, freq="min"),
21692171
)
21702172
dfp
2171-
dfp.loc["2013-01-01 10H"]
2173+
dfp.loc["2013-01-01 10h"]
21722174
21732175
As with ``DatetimeIndex``, the endpoints will be included in the result. The example below slices data starting from 10:00 to 11:59.
21742176

21752177
.. ipython:: python
21762178
2177-
dfp["2013-01-01 10H":"2013-01-01 11H"]
2179+
dfp["2013-01-01 10h":"2013-01-01 11h"]
21782180
21792181
21802182
Frequency conversion and resampling with PeriodIndex
@@ -2286,7 +2288,7 @@ the quarter end:
22862288
22872289
ts = pd.Series(np.random.randn(len(prng)), prng)
22882290
2289-
ts.index = (prng.asfreq("M", "e") + 1).asfreq("H", "s") + 9
2291+
ts.index = (prng.asfreq("M", "e") + 1).asfreq("h", "s") + 9
22902292
22912293
ts.head()
22922294
@@ -2505,7 +2507,7 @@ To remove time zone information, use ``tz_localize(None)`` or ``tz_convert(None)
25052507

25062508
.. ipython:: python
25072509
2508-
didx = pd.date_range(start="2014-08-01 09:00", freq="H", periods=3, tz="US/Eastern")
2510+
didx = pd.date_range(start="2014-08-01 09:00", freq="h", periods=3, tz="US/Eastern")
25092511
didx
25102512
didx.tz_localize(None)
25112513
didx.tz_convert(None)
@@ -2602,7 +2604,7 @@ can be controlled by the ``nonexistent`` argument. The following options are ava
26022604

26032605
.. ipython:: python
26042606
2605-
dti = pd.date_range(start="2015-03-29 02:30:00", periods=3, freq="H")
2607+
dti = pd.date_range(start="2015-03-29 02:30:00", periods=3, freq="h")
26062608
# 2:30 is a nonexistent time
26072609
26082610
Localization of nonexistent times will raise an error by default.
@@ -2619,7 +2621,7 @@ Transform nonexistent times to ``NaT`` or shift the times.
26192621
dti
26202622
dti.tz_localize("Europe/Warsaw", nonexistent="shift_forward")
26212623
dti.tz_localize("Europe/Warsaw", nonexistent="shift_backward")
2622-
dti.tz_localize("Europe/Warsaw", nonexistent=pd.Timedelta(1, unit="H"))
2624+
dti.tz_localize("Europe/Warsaw", nonexistent=pd.Timedelta(1, unit="h"))
26232625
dti.tz_localize("Europe/Warsaw", nonexistent="NaT")
26242626
26252627

doc/source/whatsnew/v0.14.0.rst

+34-5
Original file line numberDiff line numberDiff line change
@@ -880,12 +880,41 @@ Enhancements
880880

881881
- ``PeriodIndex`` fully supports partial string indexing like ``DatetimeIndex`` (:issue:`7043`)
882882

883-
.. ipython:: python
883+
.. code-block:: ipython
884884
885-
prng = pd.period_range('2013-01-01 09:00', periods=100, freq='H')
886-
ps = pd.Series(np.random.randn(len(prng)), index=prng)
887-
ps
888-
ps['2013-01-02']
885+
In [76]: prng = pd.period_range('2013-01-01 09:00', periods=100, freq='H')
886+
887+
In [77]: ps = pd.Series(np.random.randn(len(prng)), index=prng)
888+
889+
In [78]: ps
890+
Out[78]:
891+
2013-01-01 09:00 0.015696
892+
2013-01-01 10:00 -2.242685
893+
2013-01-01 11:00 1.150036
894+
2013-01-01 12:00 0.991946
895+
2013-01-01 13:00 0.953324
896+
...
897+
2013-01-05 08:00 0.285296
898+
2013-01-05 09:00 0.484288
899+
2013-01-05 10:00 1.363482
900+
2013-01-05 11:00 -0.781105
901+
2013-01-05 12:00 -0.468018
902+
Freq: H, Length: 100, dtype: float64
903+
904+
In [79]: ps['2013-01-02']
905+
Out[79]:
906+
2013-01-02 00:00 0.553439
907+
2013-01-02 01:00 1.318152
908+
2013-01-02 02:00 -0.469305
909+
2013-01-02 03:00 0.675554
910+
2013-01-02 04:00 -1.817027
911+
...
912+
2013-01-02 19:00 0.036142
913+
2013-01-02 20:00 -2.074978
914+
2013-01-02 21:00 0.247792
915+
2013-01-02 22:00 -0.897157
916+
2013-01-02 23:00 -0.136795
917+
Freq: H, Length: 24, dtype: float64
889918
890919
- ``read_excel`` can now read milliseconds in Excel dates and times with xlrd >= 0.9.3. (:issue:`5945`)
891920
- ``pd.stats.moments.rolling_var`` now uses Welford's method for increased numerical stability (:issue:`6817`)

doc/source/whatsnew/v0.15.0.rst

+56-16
Original file line numberDiff line numberDiff line change
@@ -332,16 +332,37 @@ Timezone handling improvements
332332
- ``tz_localize(None)`` for tz-aware ``Timestamp`` and ``DatetimeIndex`` now removes timezone holding local time,
333333
previously this resulted in ``Exception`` or ``TypeError`` (:issue:`7812`)
334334

335-
.. ipython:: python
335+
.. code-block:: ipython
336+
337+
In [58]: ts = pd.Timestamp('2014-08-01 09:00', tz='US/Eastern')
338+
339+
In[59]: ts
340+
Out[59]: Timestamp('2014-08-01 09:00:00-0400', tz='US/Eastern')
336341
337-
ts = pd.Timestamp('2014-08-01 09:00', tz='US/Eastern')
338-
ts
339-
ts.tz_localize(None)
342+
In [60]: ts.tz_localize(None)
343+
Out[60]: Timestamp('2014-08-01 09:00:00')
340344
341-
didx = pd.date_range(start='2014-08-01 09:00', freq='H',
342-
periods=10, tz='US/Eastern')
343-
didx
344-
didx.tz_localize(None)
345+
In [61]: didx = pd.date_range(start='2014-08-01 09:00', freq='H',
346+
....: periods=10, tz='US/Eastern')
347+
....:
348+
349+
In [62]: didx
350+
Out[62]:
351+
DatetimeIndex(['2014-08-01 09:00:00-04:00', '2014-08-01 10:00:00-04:00',
352+
'2014-08-01 11:00:00-04:00', '2014-08-01 12:00:00-04:00',
353+
'2014-08-01 13:00:00-04:00', '2014-08-01 14:00:00-04:00',
354+
'2014-08-01 15:00:00-04:00', '2014-08-01 16:00:00-04:00',
355+
'2014-08-01 17:00:00-04:00', '2014-08-01 18:00:00-04:00'],
356+
dtype='datetime64[ns, US/Eastern]', freq='H')
357+
358+
In [63]: didx.tz_localize(None)
359+
Out[63]:
360+
DatetimeIndex(['2014-08-01 09:00:00', '2014-08-01 10:00:00',
361+
'2014-08-01 11:00:00', '2014-08-01 12:00:00',
362+
'2014-08-01 13:00:00', '2014-08-01 14:00:00',
363+
'2014-08-01 15:00:00', '2014-08-01 16:00:00',
364+
'2014-08-01 17:00:00', '2014-08-01 18:00:00'],
365+
dtype='datetime64[ns]', freq=None)
345366
346367
- ``tz_localize`` now accepts the ``ambiguous`` keyword which allows for passing an array of bools
347368
indicating whether the date belongs in DST or not, 'NaT' for setting transition times to NaT,
@@ -1050,16 +1071,35 @@ Other:
10501071

10511072
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.
10521073

1053-
.. ipython:: python
1074+
.. code-block:: ipython
10541075
1055-
idx = pd.period_range('2014-07-01 09:00', periods=5, freq='H')
1056-
idx
1057-
idx + pd.offsets.Hour(2)
1058-
idx + pd.Timedelta('120m')
1076+
In [104]: idx = pd.period_range('2014-07-01 09:00', periods=5, freq='H')
10591077
1060-
idx = pd.period_range('2014-07', periods=5, freq='M')
1061-
idx
1062-
idx + pd.offsets.MonthEnd(3)
1078+
In [105]: idx
1079+
Out[105]:
1080+
PeriodIndex(['2014-07-01 09:00', '2014-07-01 10:00', '2014-07-01 11:00',
1081+
'2014-07-01 12:00', '2014-07-01 13:00'],
1082+
dtype='period[H]')
1083+
1084+
In [106]: idx + pd.offsets.Hour(2)
1085+
Out[106]:
1086+
PeriodIndex(['2014-07-01 11:00', '2014-07-01 12:00', '2014-07-01 13:00',
1087+
'2014-07-01 14:00', '2014-07-01 15:00'],
1088+
dtype='period[H]')
1089+
1090+
In [107]: idx + pd.Timedelta('120m')
1091+
Out[107]:
1092+
PeriodIndex(['2014-07-01 11:00', '2014-07-01 12:00', '2014-07-01 13:00',
1093+
'2014-07-01 14:00', '2014-07-01 15:00'],
1094+
dtype='period[H]')
1095+
1096+
In [108]: idx = pd.period_range('2014-07', periods=5, freq='M')
1097+
1098+
In [109]: idx
1099+
Out[109]: PeriodIndex(['2014-07', '2014-08', '2014-09', '2014-10', '2014-11'], dtype='period[M]')
1100+
1101+
In [110]: idx + pd.offsets.MonthEnd(3)
1102+
Out[110]: PeriodIndex(['2014-10', '2014-11', '2014-12', '2015-01', '2015-02'], dtype='period[M]')
10631103
10641104
- Added experimental compatibility with ``openpyxl`` for versions >= 2.0. The ``DataFrame.to_excel``
10651105
method ``engine`` keyword now recognizes ``openpyxl1`` and ``openpyxl2``

doc/source/whatsnew/v0.18.0.rst

+9-3
Original file line numberDiff line numberDiff line change
@@ -1000,10 +1000,16 @@ Other API changes
10001000
^^^^^^^^^^^^^^^^^
10011001
- ``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`)
10021002

1003-
.. ipython:: python
1003+
.. code-block:: ipython
1004+
1005+
In [107]: s = pd.Series(range(10), pd.date_range('2015-01-01', freq='H', periods=10))
10041006
1005-
s = pd.Series(range(10), pd.date_range('2015-01-01', freq='H', periods=10))
1006-
s.between_time("7:00am", "9:00am")
1007+
In [108]: s.between_time("7:00am", "9:00am")
1008+
Out[108]:
1009+
2015-01-01 07:00:00 7
1010+
2015-01-01 08:00:00 8
1011+
2015-01-01 09:00:00 9
1012+
Freq: H, Length: 3, dtype: int64
10071013
10081014
This will now raise.
10091015

0 commit comments

Comments
 (0)