DEPR: Deprecate pandas/io/date_converters.py

doc/source/user_guide/io.rst

@@ -927,7 +927,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
@@ -939,11 +939,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).
@@ -955,14 +950,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:

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

@@ -23,8 +23,6 @@
 import pandas._testing as tm
 from pandas.core.indexes.datetimes import date_range
 
-import pandas.io.date_converters as conv
-
 # constant
 _DEFAULT_DATETIME = datetime(1, 1, 1)
 
@@ -383,11 +381,7 @@ def test_multiple_date_cols_int_cast(all_parsers):
     parser = all_parsers
 
     result = parser.read_csv(
-        StringIO(data),
-        header=None,
-        date_parser=conv.parse_date_time,
-        parse_dates=parse_dates,
-        prefix="X",
+        StringIO(data), header=None, parse_dates=parse_dates, prefix="X",
     )
     expected = DataFrame(
         [
@@ -808,7 +802,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"],
@@ -1175,10 +1171,7 @@ def test_parse_date_time_multi_level_column_name(all_parsers):
 """
     parser = all_parsers
     result = parser.read_csv(
-        StringIO(data),
-        header=[0, 1],
-        parse_dates={"date_time": [0, 1]},
-        date_parser=conv.parse_date_time,
+        StringIO(data), header=[0, 1], parse_dates={"date_time": [0, 1]},
     )
 
     expected_data = [
@@ -1263,7 +1256,7 @@ def test_parse_date_time_multi_level_column_name(all_parsers):
 )
 def test_parse_date_time(all_parsers, data, kwargs, expected):
     parser = all_parsers
-    result = parser.read_csv(StringIO(data), date_parser=conv.parse_date_time, **kwargs)
+    result = parser.read_csv(StringIO(data), **kwargs)
 
     # Python can sometimes be flaky about how
     # the aggregated columns are entered, so
@@ -1275,12 +1268,7 @@ def test_parse_date_time(all_parsers, data, kwargs, expected):
 def test_parse_date_fields(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={"ymd": [0, 1, 2]},
-        date_parser=conv.parse_date_fields,
-    )
+    result = parser.read_csv(StringIO(data), header=0, parse_dates={"ymd": [0, 1, 2]},)
 
     expected = DataFrame(
         [[datetime(2001, 1, 10), 10.0], [datetime(2001, 2, 1), 11.0]],
@@ -1290,6 +1278,7 @@ def test_parse_date_fields(all_parsers):
 
 
 def test_parse_date_all_fields(all_parsers):
+
     parser = all_parsers
     data = """\
 year,month,day,hour,minute,second,a,b
@@ -1299,7 +1288,7 @@ def test_parse_date_all_fields(all_parsers):
     result = parser.read_csv(
         StringIO(data),
         header=0,
-        date_parser=conv.parse_all_fields,
+        date_parser=lambda x: pd.to_datetime(x, format="%Y %m %d %H %M %S"),
         parse_dates={"ymdHMS": [0, 1, 2, 3, 4, 5]},
     )
     expected = DataFrame(
@@ -1322,7 +1311,8 @@ def test_datetime_fractional_seconds(all_parsers):
     result = parser.read_csv(
         StringIO(data),
         header=0,
-        date_parser=conv.parse_all_fields,
+        # date_parser=conv.parse_all_fields,
+        date_parser=lambda x: pd.to_datetime(x, format="%Y %m %d %H %M %S.%f"),
         parse_dates={"ymdHMS": [0, 1, 2, 3, 4, 5]},
     )
     expected = DataFrame(
@@ -1339,12 +1329,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,22 +8,24 @@
 
 
 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)
-    tm.assert_numpy_array_equal(result, expected)
+    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)])
-    tm.assert_numpy_array_equal(result, expected)
+
+    with tm.assert_produces_warning(FutureWarning):
+        result = conv.parse_date_fields(years, months, days)
+        tm.assert_numpy_array_equal(result, expected)
 
 
 def test_parse_all_fields():
@@ -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)])
-    tm.assert_numpy_array_equal(result, expected)
+
+    with tm.assert_produces_warning(FutureWarning):
+        result = conv.parse_all_fields(years, months, days, hours, minutes, seconds)
+        tm.assert_numpy_array_equal(result, expected)