MAINT: Fix typo in public API

By keeping both variants of the keyowrd parameter, we achieve backwards
compatibility. The old mispelled variant has been removed from the
documentation, the new variant does appear in the documentation and has
priority over the old variant.

Additionally, the old variant can only be used as a keyword argument,
not as a positional argument.

numpy/ma/mrecords.py

@@ -667,16 +667,17 @@ def openfile(fname):
     raise NotImplementedError("Wow, binary file")
 
 
-def fromtextfile(fname, delimitor=None, commentchar='#', missingchar='',
-                 varnames=None, vartypes=None):
+def fromtextfile(fname, delimiter=None, commentchar='#', missingchar='',
+                 varnames=None, vartypes=None,
+                 *, delimitor=None):  # mispelled for backwards compatibility
     """
     Creates a mrecarray from data stored in the file `filename`.
 
     Parameters
     ----------
     fname : {file name/handle}
         Handle of an opened file.
-    delimitor : {None, string}, optional
+    delimiter : {None, string}, optional
         Alphanumeric character used to separate columns in the file.
         If None, any (group of) white spacestring(s) will be used.
     commentchar : {'#', string}, optional
@@ -692,21 +693,30 @@ def fromtextfile(fname, delimitor=None, commentchar='#', missingchar='',
 
 
     Ultra simple: the varnames are in the header, one line"""
+    if delimitor is not None:
+        # NumPy 1.22.0, 2021-09-22
+        warnings.warn('The "delimitor" keyword argument of '
+                      'numpy.ma.mrecords.fromtextfile() is deprecated '
+                      'since NumPy 1.22.0, use "delimiter" instead.',
+                      DeprecationWarning, stacklevel=2)
+        if delimiter is None:
+            delimiter = delimitor
+
     # Try to open the file.
     ftext = openfile(fname)
 
     # Get the first non-empty line as the varnames
     while True:
         line = ftext.readline()
         firstline = line[:line.find(commentchar)].strip()
-        _varnames = firstline.split(delimitor)
+        _varnames = firstline.split(delimiter)
         if len(_varnames) > 1:
             break
     if varnames is None:
         varnames = _varnames
 
     # Get the data.
-    _variables = masked_array([line.strip().split(delimitor) for line in ftext
+    _variables = masked_array([line.strip().split(delimiter) for line in ftext
                                if line[0] != commentchar and len(line) > 1])
     (_, nfields) = _variables.shape
     ftext.close()

numpy/ma/mrecords.pyi

@@ -78,11 +78,13 @@ def fromrecords(
 
 def fromtextfile(
     fname,
-    delimitor=...,
+    delimiter=...,
     commentchar=...,
     missingchar=...,
     varnames=...,
     vartypes=...,
+    # NOTE: deprecated: NumPy 1.22.0, 2021-09-22
+    # delimitor=..., 
 ): ...
 
 def addfield(mrecord, newfield, newfieldname=...): ...

numpy/ma/tests/test_deprecations.py

@@ -2,7 +2,7 @@
 
 """
 import numpy as np
-from numpy.testing import assert_warns
+from numpy.testing import assert_warns, temppath
 from numpy.ma.testutils import assert_equal
 from numpy.ma.core import MaskedArrayFutureWarning
 
@@ -66,3 +66,23 @@ def test_axis_default(self):
         result = ma_max(data1d)
         assert_equal(result, ma_max(data1d, axis=None))
         assert_equal(result, ma_max(data1d, axis=0))
+
+
+class TestFromtextfile:
+    def test_fromtextfile_delimitor(self):
+        # NumPy 1.22.0, 2021-09-22
+
+        fcontent = (
+"""
+A,B,C,D
+'string 1';1;1.0;'mixed column'
+'string 2';2;2.0;
+'string 3';3;3.0;123
+'string 4';4;4.0;3.14
+""")
+        with temppath() as path:
+            with open(path, 'w') as f:
+                f.write(fcontent)
+            result = assert_warns(DeprecationWarning,
+                                  np.ma.mrecords.fromtextfile,
+                                  path, delimitor=';')

numpy/ma/tests/test_mrecords.py

@@ -468,7 +468,7 @@ def test_fromtextfile(self):
         with temppath() as path:
             with open(path, 'w') as f:
                 f.write(fcontent)
-            mrectxt = fromtextfile(path, delimitor=',', varnames='ABCDEFG')
+            mrectxt = fromtextfile(path, delimiter=',', varnames='ABCDEFG')
         assert_(isinstance(mrectxt, MaskedRecords))
         assert_equal(mrectxt.F, [1, 1, 1, 1])
         assert_equal(mrectxt.E._mask, [1, 1, 1, 1])