DEPR: favour sep over delimiter in pd.read_csv

doc/source/whatsnew/v0.24.0.txt

@@ -911,6 +911,7 @@ Deprecations
 - :meth:`FrozenNDArray.searchsorted` has deprecated the ``v`` parameter in favor of ``value`` (:issue:`14645`)
 - :func:`DatetimeIndex.shift` and :func:`PeriodIndex.shift` now accept ``periods`` argument instead of ``n`` for consistency with :func:`Index.shift` and :func:`Series.shift`. Using ``n`` throws a deprecation warning (:issue:`22458`, :issue:`22912`)
 - The ``fastpath`` keyword of the different Index constructors is deprecated (:issue:`23110`).
+- :meth:`pandas.read_csv` has deprecated the redundant ``delimiter`` argument, please use ``sep`` (:issue:`21996`)
 
 .. _whatsnew_0240.prior_deprecations:
 

pandas/io/parsers.py

@@ -322,7 +322,10 @@
     will also force the use of the Python parsing engine. Note that regex
     delimiters are prone to ignoring quoted data. Regex example: ``'\r\t'``
 delimiter : str, default ``None``
-    Alternative argument name for sep."""
+    Alternative argument name for sep.
+    .. deprecated:: 0.24.0
+       Use sep argument instead.
+    """
 
 _read_csv_doc = """
 Read CSV (comma-separated) file into DataFrame
@@ -635,6 +638,10 @@ def parser_f(filepath_or_buffer,
         # Alias sep -> delimiter.
         if delimiter is None:
             delimiter = sep
+        else:
+            # GH 21996
+            warnings.warn("delimiter is deprecated, use sep instead.",
+                          FutureWarning, stacklevel=4)
 
         if delim_whitespace and delimiter != default_sep:
             raise ValueError("Specified a delimiter with both sep and"

pandas/tests/io/parser/c_parser_only.py

@@ -410,6 +410,7 @@ def test_data_after_quote(self):
         tm.assert_frame_equal(result, expected)
 
     @tm.capture_stderr
+    @pytest.mark.filterwarnings('ignore::FutureWarning')
     def test_comment_whitespace_delimited(self):
         test_input = """\
 1 2

pandas/tests/io/parser/common.py

@@ -1604,3 +1604,9 @@ def test_buffer_rd_bytes_bad_unicode(self):
             t = TextIOWrapper(t, encoding='ascii', errors='surrogateescape')
         with pytest.raises(UnicodeError):
             pd.read_csv(t, encoding='UTF-8')
+
+    def test_read_csv_depr_delimiter(self):
+        # GH 21996
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            self.read_csv(self.csv2, delimiter=',')

pandas/tests/io/parser/dialect.py

@@ -70,9 +70,9 @@ def test_dialect_conflict(self):
         exp = DataFrame({'a': [1], 'b': [2]})
 
         with tm.assert_produces_warning(None):
-            df = self.read_csv(StringIO(data), delimiter=',', dialect=dialect)
+            df = self.read_csv(StringIO(data), sep=',', dialect=dialect)
             tm.assert_frame_equal(df, exp)
 
         with tm.assert_produces_warning(ParserWarning):
-            df = self.read_csv(StringIO(data), delimiter='.', dialect=dialect)
+            df = self.read_csv(StringIO(data), sep='.', dialect=dialect)
             tm.assert_frame_equal(df, exp)

pandas/tests/io/parser/python_parser_only.py

@@ -47,6 +47,7 @@ def test_invalid_skipfooter(self):
         with tm.assert_raises_regex(ValueError, msg):
             self.read_csv(StringIO(text), skipfooter=-1)
 
+    @pytest.mark.filterwarnings('ignore::FutureWarning')
     def test_sniff_delimiter(self):
         text = """index|A|B|C
 foo|1|2|3