DEPR: Deprecate pandas/io/date_converters.py (#35741)

Author: avinashpancham

doc/source/user_guide/io.rst

@@ -930,7 +930,7 @@ take full advantage of the flexibility of the date parsing API:
 .. ipython:: python
 
  df = pd.read_csv('tmp.csv', header=None, parse_dates=date_spec,
- date_parser=pd.io.date_converters.parse_date_time)
+ date_parser=pd.to_datetime)
  df
 
 Pandas will try to call the ``date_parser`` function in three different ways. If
@@ -942,11 +942,6 @@ an exception is raised, the next one is tried:
 2. If #1 fails, ``date_parser`` is called with all the columns
  concatenated row-wise into a single array (e.g., ``date_parser(['2013 1', '2013 2'])``).
 
-3. If #2 fails, ``date_parser`` is called once for every row with one or more
- string arguments from the columns indicated with `parse_dates`
- (e.g., ``date_parser('2013', '1')`` for the first row, ``date_parser('2013', '2')``
- for the second, etc.).
-
 Note that performance-wise, you should try these methods of parsing dates in order:
 
 1. Try to infer the format using ``infer_datetime_format=True`` (see section below).
@@ -958,14 +953,6 @@ Note that performance-wise, you should try these methods of parsing dates in ord
  For optimal performance, this should be vectorized, i.e., it should accept arrays
  as arguments.
 
-You can explore the date parsing functionality in
-`date_converters.py <https://github.com/pandas-dev/pandas/blob/master/pandas/io/date_converters.py>`__
-and add your own. We would love to turn this module into a community supported
-set of date/time parsers. To get you started, ``date_converters.py`` contains
-functions to parse dual date and time columns, year/month/day columns,
-and year/month/day/hour/minute/second columns. It also contains a
-``generic_parser`` function so you can curry it with a function that deals with
-a single date rather than the entire array.
 
 .. ipython:: python
  :suppress:

doc/source/whatsnew/v1.2.0.rst

@@ -195,7 +195,7 @@ Deprecations
 ~~~~~~~~~~~~
 - Deprecated parameter ``inplace`` in :meth:`MultiIndex.set_codes` and :meth:`MultiIndex.set_levels` (:issue:`35626`)
 - Deprecated parameter ``dtype`` in :~meth:`Index.copy` on method all index classes. Use the :meth:`Index.astype` method instead for changing dtype(:issue:`35853`)
--
+- 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`)
 
 .. ---------------------------------------------------------------------------
 

pandas/io/date_converters.py

@@ -1,23 +1,71 @@
 """This module is designed for community supported date conversion functions"""
+import warnings
+
 import numpy as np
 
 from pandas._libs.tslibs import parsing
 
 
 def parse_date_time(date_col, time_col):
+ """
+ Parse columns with dates and times into a single datetime column.
+
+ .. deprecated:: 1.2
+ """
+ warnings.warn(
+ """
+ Use pd.to_datetime(date_col + " " + time_col) instead to get a Pandas Series.
+ Use pd.to_datetime(date_col + " " + time_col).to_pydatetime() instead to get a Numpy array.
+""", # noqa: E501
+ FutureWarning,
+ stacklevel=2,
+ )
  date_col = _maybe_cast(date_col)
  time_col = _maybe_cast(time_col)
  return parsing.try_parse_date_and_time(date_col, time_col)
 
 
 def parse_date_fields(year_col, month_col, day_col):
+ """
+ Parse columns with years, months and days into a single date column.
+
+ .. deprecated:: 1.2
+ """
+ warnings.warn(
+ """
+ Use pd.to_datetime({"year": year_col, "month": month_col, "day": day_col}) instead to get a Pandas Series.
+ Use ser = pd.to_datetime({"year": year_col, "month": month_col, "day": day_col}) and
+ np.array([s.to_pydatetime() for s in ser]) instead to get a Numpy array.
+""", # noqa: E501
+ FutureWarning,
+ stacklevel=2,
+ )
+
  year_col = _maybe_cast(year_col)
  month_col = _maybe_cast(month_col)
  day_col = _maybe_cast(day_col)
  return parsing.try_parse_year_month_day(year_col, month_col, day_col)
 
 
 def parse_all_fields(year_col, month_col, day_col, hour_col, minute_col, second_col):
+ """
+ Parse columns with datetime information into a single datetime column.
+
+ .. deprecated:: 1.2
+ """
+
+ warnings.warn(
+ """
+ Use pd.to_datetime({"year": year_col, "month": month_col, "day": day_col,
+ "hour": hour_col, "minute": minute_col, second": second_col}) instead to get a Pandas Series.
+ Use ser = pd.to_datetime({"year": year_col, "month": month_col, "day": day_col,
+ "hour": hour_col, "minute": minute_col, second": second_col}) and
+ np.array([s.to_pydatetime() for s in ser]) instead to get a Numpy array.
+""", # noqa: E501
+ FutureWarning,
+ stacklevel=2,
+ )
+
  year_col = _maybe_cast(year_col)
  month_col = _maybe_cast(month_col)
  day_col = _maybe_cast(day_col)
@@ -30,6 +78,20 @@ def parse_all_fields(year_col, month_col, day_col, hour_col, minute_col, second_
 
 
 def generic_parser(parse_func, *cols):
+ """
+ Use dateparser to parse columns with data information into a single datetime column.
+
+ .. deprecated:: 1.2
+ """
+
+ warnings.warn(
+ """
+ Use pd.to_datetime instead.
+""",
+ FutureWarning,
+ stacklevel=2,
+ )
+
  N = _check_columns(cols)
  results = np.empty(N, dtype=object)
 

pandas/tests/io/parser/test_parse_dates.py

@@ -370,7 +370,11 @@ def test_date_col_as_index_col(all_parsers):
  tm.assert_frame_equal(result, expected)
 
 
-def test_multiple_date_cols_int_cast(all_parsers):
+@pytest.mark.parametrize(
+ "date_parser, warning",
+ ([conv.parse_date_time, FutureWarning], [pd.to_datetime, None]),
+)
+def test_multiple_date_cols_int_cast(all_parsers, date_parser, warning):
  data = (
  "KORD,19990127, 19:00:00, 18:56:00, 0.8100\n"
  "KORD,19990127, 20:00:00, 19:56:00, 0.0100\n"
@@ -382,13 +386,15 @@ def test_multiple_date_cols_int_cast(all_parsers):
  parse_dates = {"actual": [1, 2], "nominal": [1, 3]}
  parser = all_parsers
 
- result = parser.read_csv(
- StringIO(data),
- header=None,
- date_parser=conv.parse_date_time,
- parse_dates=parse_dates,
- prefix="X",
- )
+ with tm.assert_produces_warning(warning, check_stacklevel=False):
+ result = parser.read_csv(
+ StringIO(data),
+ header=None,
+ date_parser=date_parser,
+ parse_dates=parse_dates,
+ prefix="X",
+ )
+
  expected = DataFrame(
  [
  [datetime(1999, 1, 27, 19, 0), datetime(1999, 1, 27, 18, 56), "KORD", 0.81],
@@ -808,7 +814,9 @@ def test_parse_dates_custom_euro_format(all_parsers, kwargs):
  tm.assert_frame_equal(df, expected)
  else:
  msg = "got an unexpected keyword argument 'day_first'"
- with pytest.raises(TypeError, match=msg):
+ with pytest.raises(TypeError, match=msg), tm.assert_produces_warning(
+ FutureWarning
+ ):
  parser.read_csv(
  StringIO(data),
  names=["time", "Q", "NTU"],
@@ -1166,20 +1174,25 @@ def test_parse_dates_no_convert_thousands(all_parsers, data, kwargs, expected):
  tm.assert_frame_equal(result, expected)
 
 
-def test_parse_date_time_multi_level_column_name(all_parsers):
+@pytest.mark.parametrize(
+ "date_parser, warning",
+ ([conv.parse_date_time, FutureWarning], [pd.to_datetime, None]),
+)
+def test_parse_date_time_multi_level_column_name(all_parsers, date_parser, warning):
  data = """\
 D,T,A,B
 date, time,a,b
 2001-01-05, 09:00:00, 0.0, 10.
 2001-01-06, 00:00:00, 1.0, 11.
 """
  parser = all_parsers
- result = parser.read_csv(
- StringIO(data),
- header=[0, 1],
- parse_dates={"date_time": [0, 1]},
- date_parser=conv.parse_date_time,
- )
+ with tm.assert_produces_warning(warning, check_stacklevel=False):
+ result = parser.read_csv(
+ StringIO(data),
+ header=[0, 1],
+ parse_dates={"date_time": [0, 1]},
+ date_parser=date_parser,
+ )
 
  expected_data = [
  [datetime(2001, 1, 5, 9, 0, 0), 0.0, 10.0],
@@ -1189,6 +1202,10 @@ def test_parse_date_time_multi_level_column_name(all_parsers):
  tm.assert_frame_equal(result, expected)
 
 
+@pytest.mark.parametrize(
+ "date_parser, warning",
+ ([conv.parse_date_time, FutureWarning], [pd.to_datetime, None]),
+)
 @pytest.mark.parametrize(
  "data,kwargs,expected",
  [
@@ -1261,9 +1278,10 @@ def test_parse_date_time_multi_level_column_name(all_parsers):
  ),
  ],
 )
-def test_parse_date_time(all_parsers, data, kwargs, expected):
+def test_parse_date_time(all_parsers, data, kwargs, expected, date_parser, warning):
  parser = all_parsers
- result = parser.read_csv(StringIO(data), date_parser=conv.parse_date_time, **kwargs)
+ with tm.assert_produces_warning(warning, check_stacklevel=False):
+ result = parser.read_csv(StringIO(data), date_parser=date_parser, **kwargs)
 
  # Python can sometimes be flaky about how
  # the aggregated columns are entered, so
@@ -1272,15 +1290,20 @@ def test_parse_date_time(all_parsers, data, kwargs, expected):
  tm.assert_frame_equal(result, expected)
 
 
-def test_parse_date_fields(all_parsers):
+@pytest.mark.parametrize(
+ "date_parser, warning",
+ ([conv.parse_date_fields, FutureWarning], [pd.to_datetime, None]),
+)
+def test_parse_date_fields(all_parsers, date_parser, warning):
  parser = all_parsers
  data = "year,month,day,a\n2001,01,10,10.\n2001,02,1,11."
- result = parser.read_csv(
- StringIO(data),
- header=0,
- parse_dates={"ymd": [0, 1, 2]},
- date_parser=conv.parse_date_fields,
- )
+ with tm.assert_produces_warning(warning, check_stacklevel=False):
+ result = parser.read_csv(
+ StringIO(data),
+ header=0,
+ parse_dates={"ymd": [0, 1, 2]},
+ date_parser=date_parser,
+ )
 
  expected = DataFrame(
  [[datetime(2001, 1, 10), 10.0], [datetime(2001, 2, 1), 11.0]],
@@ -1289,19 +1312,27 @@ def test_parse_date_fields(all_parsers):
  tm.assert_frame_equal(result, expected)
 
 
-def test_parse_date_all_fields(all_parsers):
+@pytest.mark.parametrize(
+ "date_parser, warning",
+ (
+ [conv.parse_all_fields, FutureWarning],
+ [lambda x: pd.to_datetime(x, format="%Y %m %d %H %M %S"), None],
+ ),
+)
+def test_parse_date_all_fields(all_parsers, date_parser, warning):
  parser = all_parsers
  data = """\
 year,month,day,hour,minute,second,a,b
 2001,01,05,10,00,0,0.0,10.
 2001,01,5,10,0,00,1.,11.
 """
- result = parser.read_csv(
- StringIO(data),
- header=0,
- date_parser=conv.parse_all_fields,
- parse_dates={"ymdHMS": [0, 1, 2, 3, 4, 5]},
- )
+ with tm.assert_produces_warning(warning, check_stacklevel=False):
+ result = parser.read_csv(
+ StringIO(data),
+ header=0,
+ date_parser=date_parser,
+ parse_dates={"ymdHMS": [0, 1, 2, 3, 4, 5]},
+ )
  expected = DataFrame(
  [
  [datetime(2001, 1, 5, 10, 0, 0), 0.0, 10.0],
@@ -1312,19 +1343,27 @@ def test_parse_date_all_fields(all_parsers):
  tm.assert_frame_equal(result, expected)
 
 
-def test_datetime_fractional_seconds(all_parsers):
+@pytest.mark.parametrize(
+ "date_parser, warning",
+ (
+ [conv.parse_all_fields, FutureWarning],
+ [lambda x: pd.to_datetime(x, format="%Y %m %d %H %M %S.%f"), None],
+ ),
+)
+def test_datetime_fractional_seconds(all_parsers, date_parser, warning):
  parser = all_parsers
  data = """\
 year,month,day,hour,minute,second,a,b
 2001,01,05,10,00,0.123456,0.0,10.
 2001,01,5,10,0,0.500000,1.,11.
 """
- result = parser.read_csv(
- StringIO(data),
- header=0,
- date_parser=conv.parse_all_fields,
- parse_dates={"ymdHMS": [0, 1, 2, 3, 4, 5]},
- )
+ with tm.assert_produces_warning(warning, check_stacklevel=False):
+ result = parser.read_csv(
+ StringIO(data),
+ header=0,
+ date_parser=date_parser,
+ parse_dates={"ymdHMS": [0, 1, 2, 3, 4, 5]},
+ )
  expected = DataFrame(
  [
  [datetime(2001, 1, 5, 10, 0, 0, microsecond=123456), 0.0, 10.0],
@@ -1339,12 +1378,13 @@ def test_generic(all_parsers):
  parser = all_parsers
  data = "year,month,day,a\n2001,01,10,10.\n2001,02,1,11."
 
- result = parser.read_csv(
- StringIO(data),
- header=0,
- parse_dates={"ym": [0, 1]},
- date_parser=lambda y, m: date(year=int(y), month=int(m), day=1),
- )
+ with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+ result = parser.read_csv(
+ StringIO(data),
+ header=0,
+ parse_dates={"ym": [0, 1]},
+ date_parser=lambda y, m: date(year=int(y), month=int(m), day=1),
+ )
  expected = DataFrame(
  [[date(2001, 1, 1), 10, 10.0], [date(2001, 2, 1), 1, 11.0]],
  columns=["ym", "day", "a"],

pandas/tests/io/test_date_converters.py

@@ -8,21 +8,23 @@
 
 
 def test_parse_date_time():
+
  dates = np.array(["2007/1/3", "2008/2/4"], dtype=object)
  times = np.array(["05:07:09", "06:08:00"], dtype=object)
  expected = np.array([datetime(2007, 1, 3, 5, 7, 9), datetime(2008, 2, 4, 6, 8, 0)])
-
- result = conv.parse_date_time(dates, times)
+ with tm.assert_produces_warning(FutureWarning):
+  result = conv.parse_date_time(dates, times)
  tm.assert_numpy_array_equal(result, expected)
 
 
 def test_parse_date_fields():
  days = np.array([3, 4])
  months = np.array([1, 2])
  years = np.array([2007, 2008])
- result = conv.parse_date_fields(years, months, days)
-
  expected = np.array([datetime(2007, 1, 3), datetime(2008, 2, 4)])
+
+ with tm.assert_produces_warning(FutureWarning):
+ result = conv.parse_date_fields(years, months, days)
  tm.assert_numpy_array_equal(result, expected)
 
 
@@ -34,7 +36,8 @@ def test_parse_all_fields():
  days = np.array([3, 4])
  years = np.array([2007, 2008])
  months = np.array([1, 2])
-
- result = conv.parse_all_fields(years, months, days, hours, minutes, seconds)
  expected = np.array([datetime(2007, 1, 3, 5, 7, 9), datetime(2008, 2, 4, 6, 8, 0)])
+
+ with tm.assert_produces_warning(FutureWarning):
+ result = conv.parse_all_fields(years, months, days, hours, minutes, seconds)
  tm.assert_numpy_array_equal(result, expected)