DEPR: lowercase strings w, d, b and c denoting frequencies in Week, Day, BusinessDay and CustomBusinessDay classes (pandas-dev#58998)

* deprecate lowercase 'd'

* fix tests, add tests

* deprecate lowercase alias 'b', fix tests

* fix tests and docs

* fix tests, fix an example in v0.20.0

* deprecate 'c',fix examples in v0.22.0, add tests and a note to v3.0.0

* correct examples in whatsnew

* update examples in user_guide/io.rst

---------

Co-authored-by: Matthew Roeschke <[email protected]>

Author: natmokval

doc/source/user_guide/io.rst

@@ -2161,7 +2161,7 @@ a JSON string with two fields, ``schema`` and ``data``.
        {
            "A": [1, 2, 3],
            "B": ["a", "b", "c"],
-           "C": pd.date_range("2016-01-01", freq="d", periods=3),
+           "C": pd.date_range("2016-01-01", freq="D", periods=3),
        },
        index=pd.Index(range(3), name="idx"),
    )
@@ -2270,7 +2270,7 @@ round-trippable manner.
        {
            "foo": [1, 2, 3, 4],
            "bar": ["a", "b", "c", "d"],
-           "baz": pd.date_range("2018-01-01", freq="d", periods=4),
+           "baz": pd.date_range("2018-01-01", freq="D", periods=4),
            "qux": pd.Categorical(["a", "b", "c", "c"]),
        },
        index=pd.Index(range(4), name="idx"),

doc/source/whatsnew/v0.18.0.rst

@@ -322,15 +322,28 @@ Tz-aware are rounded, floored and ceiled in local times
 
 Timedeltas
 
-.. ipython:: python
+.. code-block:: ipython
+
+   In [37]: t = pd.timedelta_range('1 days 2 hr 13 min 45 us', periods=3, freq='d')
 
-   t = pd.timedelta_range('1 days 2 hr 13 min 45 us', periods=3, freq='d')
-   t
-   t.round('10min')
+   In [38]: t
+   Out[38]:
+   TimedeltaIndex(['1 days 02:13:00.000045', '2 days 02:13:00.000045',
+                   '3 days 02:13:00.000045'],
+                  dtype='timedelta64[ns]', freq='D')
+
+   In [39]: t.round('10min')
+   Out[39]:
+   TimedeltaIndex(['1 days 02:10:00', '2 days 02:10:00',
+                   '3 days 02:10:00'],
+                  dtype='timedelta64[ns]', freq=None)
 
    # Timedelta scalar
-   t[0]
-   t[0].round('2h')
+   In [40]: t[0]
+   Out[40]: Timedelta('1 days 02:13:00.000045')
+
+   In [41]: t[0].round('2h')
+   Out[41]: Timedelta('1 days 02:00:00')
 
 
 In addition, ``.round()``, ``.floor()`` and ``.ceil()`` will be available through the ``.dt`` accessor of ``Series``.

doc/source/whatsnew/v0.20.0.rst

@@ -308,15 +308,26 @@ The new orient ``'table'`` for :meth:`DataFrame.to_json`
 will generate a `Table Schema`_ compatible string representation of
 the data.
 
-.. ipython:: python
+.. code-block:: ipython
 
-   df = pd.DataFrame(
-       {'A': [1, 2, 3],
-        'B': ['a', 'b', 'c'],
-        'C': pd.date_range('2016-01-01', freq='d', periods=3)},
-       index=pd.Index(range(3), name='idx'))
-   df
-   df.to_json(orient='table')
+   In [38]: df = pd.DataFrame(
+      ....: {'A': [1, 2, 3],
+      ....:  'B': ['a', 'b', 'c'],
+      ....:  'C': pd.date_range('2016-01-01', freq='d', periods=3)},
+      ....: index=pd.Index(range(3), name='idx'))
+   In [39]: df
+   Out[39]:
+        A  B          C
+   idx
+   0    1  a 2016-01-01
+   1    2  b 2016-01-02
+   2    3  c 2016-01-03
+
+   [3 rows x 3 columns]
+
+   In [40]: df.to_json(orient='table')
+   Out[40]:
+   '{"schema":{"fields":[{"name":"idx","type":"integer"},{"name":"A","type":"integer"},{"name":"B","type":"string"},{"name":"C","type":"datetime"}],"primaryKey":["idx"],"pandas_version":"1.4.0"},"data":[{"idx":0,"A":1,"B":"a","C":"2016-01-01T00:00:00.000"},{"idx":1,"A":2,"B":"b","C":"2016-01-02T00:00:00.000"},{"idx":2,"A":3,"B":"c","C":"2016-01-03T00:00:00.000"}]}'
 
 
 See :ref:`IO: Table Schema for more information <io.table_schema>`.

doc/source/whatsnew/v0.22.0.rst

@@ -157,16 +157,27 @@ sum and ``1`` for product.
 
 *pandas 0.22.0*
 
-.. ipython:: python
+.. code-block:: ipython
+
+   In [11]: s = pd.Series([1, 1, np.nan, np.nan],
+      ....:               index=pd.date_range("2017", periods=4))
 
-   s = pd.Series([1, 1, np.nan, np.nan], index=pd.date_range("2017", periods=4))
-   s.resample("2d").sum()
+   In [12]: s.resample("2d").sum()
+   Out[12]:
+   2017-01-01    2.0
+   2017-01-03    0.0
+   Freq: 2D, Length: 2, dtype: float64
 
 To restore the 0.21 behavior of returning ``NaN``, use ``min_count>=1``.
 
-.. ipython:: python
+.. code-block:: ipython
+
+   In [13]: s.resample("2d").sum(min_count=1)
+   Out[13]:
+   2017-01-01    2.0
+   2017-01-03    NaN
+   Freq: 2D, Length: 2, dtype: float64
 
-   s.resample("2d").sum(min_count=1)
 
 In particular, upsampling and taking the sum or product is affected, as
 upsampling introduces missing values even if the original series was

doc/source/whatsnew/v0.23.0.rst

@@ -50,19 +50,55 @@ JSON read/write round-trippable with ``orient='table'``
 
 A ``DataFrame`` can now be written to and subsequently read back via JSON while preserving metadata through usage of the ``orient='table'`` argument (see :issue:`18912` and :issue:`9146`). Previously, none of the available ``orient`` values guaranteed the preservation of dtypes and index names, amongst other metadata.
 
-.. ipython:: python
+.. code-block:: ipython
 
-   df = pd.DataFrame({'foo': [1, 2, 3, 4],
-                      'bar': ['a', 'b', 'c', 'd'],
-                      'baz': pd.date_range('2018-01-01', freq='d', periods=4),
-                      'qux': pd.Categorical(['a', 'b', 'c', 'c'])},
-                     index=pd.Index(range(4), name='idx'))
-   df
-   df.dtypes
-   df.to_json('test.json', orient='table')
-   new_df = pd.read_json('test.json', orient='table')
-   new_df
-   new_df.dtypes
+   In [1]: df = pd.DataFrame({'foo': [1, 2, 3, 4],
+      ...:                    'bar': ['a', 'b', 'c', 'd'],
+      ...:                    'baz': pd.date_range('2018-01-01', freq='d', periods=4),
+      ...:                    'qux': pd.Categorical(['a', 'b', 'c', 'c'])},
+      ...:                   index=pd.Index(range(4), name='idx'))
+
+   In [2]: df
+   Out[2]:
+        foo bar        baz qux
+   idx
+   0      1   a 2018-01-01   a
+   1      2   b 2018-01-02   b
+   2      3   c 2018-01-03   c
+   3      4   d 2018-01-04   c
+
+   [4 rows x 4 columns]
+
+   In [3]: df.dtypes
+   Out[3]:
+   foo             int64
+   bar            object
+   baz    datetime64[ns]
+   qux          category
+   Length: 4, dtype: object
+
+   In [4]: df.to_json('test.json', orient='table')
+
+   In [5]: new_df = pd.read_json('test.json', orient='table')
+
+   In [6]: new_df
+   Out[6]:
+        foo bar        baz qux
+   idx
+   0      1   a 2018-01-01   a
+   1      2   b 2018-01-02   b
+   2      3   c 2018-01-03   c
+   3      4   d 2018-01-04   c
+
+   [4 rows x 4 columns]
+
+   In [7]: new_df.dtypes
+   Out[7]:
+   foo             int64
+   bar            object
+   baz    datetime64[ns]
+   qux          category
+   Length: 4, dtype: object
 
 Please note that the string ``index`` is not supported with the round trip format, as it is used by default in ``write_json`` to indicate a missing index name.
 

doc/source/whatsnew/v3.0.0.rst

@@ -279,6 +279,8 @@ Other Deprecations
 - Deprecated allowing non-keyword arguments in :meth:`Series.to_markdown` except ``buf``. (:issue:`57280`)
 - Deprecated allowing non-keyword arguments in :meth:`Series.to_string` except ``buf``. (:issue:`57280`)
 - Deprecated behavior of :meth:`Series.dt.to_pytimedelta`, in a future version this will return a :class:`Series` containing python ``datetime.timedelta`` objects instead of an ``ndarray`` of timedelta; this matches the behavior of other :meth:`Series.dt` properties. (:issue:`57463`)
+- Deprecated lowercase strings ``d``, ``b`` and ``c`` denoting frequencies in :class:`Day`, :class:`BusinessDay` and :class:`CustomBusinessDay` in favour of ``D``, ``B`` and ``C`` (:issue:`58998`)
+- Deprecated lowercase strings ``w``, ``w-mon``, ``w-tue``, etc. denoting frequencies in :class:`Week` in favour of ``W``, ``W-MON``, ``W-TUE``, etc. (:issue:`58998`)
 - Deprecated parameter ``method`` in :meth:`DataFrame.reindex_like` / :meth:`Series.reindex_like` (:issue:`58667`)
 - Deprecated strings ``w``, ``d``, ``MIN``, ``MS``, ``US`` and ``NS`` denoting units in :class:`Timedelta` in favour of ``W``, ``D``, ``min``, ``ms``, ``us`` and ``ns`` (:issue:`59051`)
 - Deprecated using ``epoch`` date format in :meth:`DataFrame.to_json` and :meth:`Series.to_json`, use ``iso`` instead. (:issue:`57063`)

pandas/_libs/tslibs/dtypes.pyx

@@ -359,6 +359,16 @@ cdef dict c_DEPR_UNITS = {
 
 cdef dict c_PERIOD_AND_OFFSET_DEPR_FREQSTR = {
     "w": "W",
+    "w-mon": "W-MON",
+    "w-tue": "W-TUE",
+    "w-wed": "W-WED",
+    "w-thu": "W-THU",
+    "w-fri": "W-FRI",
+    "w-sat": "W-SAT",
+    "w-sun": "W-SUN",
+    "d": "D",
+    "b": "B",
+    "c": "C",
     "MIN": "min",
 }
 

pandas/_libs/tslibs/offsets.pyx

@@ -4890,16 +4890,16 @@ cpdef to_offset(freq, bint is_period=False):
                             )
                         name = c_PERIOD_TO_OFFSET_FREQSTR.get(name.upper())
 
-                    if name in c_PERIOD_AND_OFFSET_DEPR_FREQSTR:
-                        warnings.warn(
-                            f"\'{name}\' is deprecated and will be removed "
-                            f"in a future version, please use "
-                            f"\'{c_PERIOD_AND_OFFSET_DEPR_FREQSTR.get(name)}\' "
-                            f" instead.",
-                            FutureWarning,
-                            stacklevel=find_stack_level(),
-                            )
-                        name = c_PERIOD_AND_OFFSET_DEPR_FREQSTR.get(name)
+                if name in c_PERIOD_AND_OFFSET_DEPR_FREQSTR:
+                    warnings.warn(
+                        f"\'{name}\' is deprecated and will be removed "
+                        f"in a future version, please use "
+                        f"\'{c_PERIOD_AND_OFFSET_DEPR_FREQSTR.get(name)}\' "
+                        f" instead.",
+                        FutureWarning,
+                        stacklevel=find_stack_level(),
+                        )
+                    name = c_PERIOD_AND_OFFSET_DEPR_FREQSTR.get(name)
                 if sep != "" and not sep.isspace():
                     raise ValueError("separator must be spaces")
                 prefix = _lite_rule_alias.get(name) or name

pandas/io/json/_table_schema.py

@@ -275,7 +275,7 @@ def build_table_schema(
     >>> df = pd.DataFrame(
     ...     {'A': [1, 2, 3],
     ...      'B': ['a', 'b', 'c'],
-    ...      'C': pd.date_range('2016-01-01', freq='d', periods=3),
+    ...      'C': pd.date_range('2016-01-01', freq='D', periods=3),
     ...      }, index=pd.Index(range(3), name='idx'))
     >>> build_table_schema(df)
     {'fields': \

pandas/tests/arithmetic/test_period.py

@@ -1086,7 +1086,7 @@ def test_parr_add_timedeltalike_minute_gt1(self, three_days, box_with_array):
         with pytest.raises(TypeError, match=msg):
             other - rng
 
-    @pytest.mark.parametrize("freqstr", ["5ns", "5us", "5ms", "5s", "5min", "5h", "5d"])
+    @pytest.mark.parametrize("freqstr", ["5ns", "5us", "5ms", "5s", "5min", "5h", "5D"])
     def test_parr_add_timedeltalike_tick_gt1(self, three_days, freqstr, box_with_array):
         # GH#23031 adding a time-delta-like offset to a PeriodArray that has
         # tick-like frequency with n != 1