refactor(datafile): deprecate list_records() and other list_ methods (#2232)

Now that data files have a .headers data frame property (#2221), there is no need to have methods that print parts of this information to stdout (they return None). This PR deprecates the following:

* list_records(): use headers instead
* list_unique_records(): use headers[["text", "imeth"]].drop_duplicates() instead
* list_unique_packages(to=True/False): use headers.paknam.drop_duplicates() or headers.paknam2.unique() (there are a few ways)

The last two only apply to CellBudgetFile. This PR does not apply to flopy.mf6.utils.mfobservation.list_records().

Author: mwtoews

.docs/Notebooks/mf6_simple_model_example.py

@@ -20,9 +20,8 @@
 
 # ### Setup the Notebook Environment
 
-import os
-
 # +
+import os
 import sys
 from pprint import pformat
 from tempfile import TemporaryDirectory
@@ -272,8 +271,9 @@
 # read the cell budget file
 fname = os.path.join(workspace, f"{name}.cbb")
 cbb = flopy.utils.CellBudgetFile(fname, precision="double")
-cbb.list_records()
+cbb.headers.T
 
+# +
 flowja = cbb.get_data(text="FLOW-JA-FACE")[0][0, 0, :]
 chdflow = cbb.get_data(text="CHD")[0]
 # -

.docs/Notebooks/mfusg_conduit_examples.py

@@ -104,8 +104,9 @@
 # +
 cbb_file = os.path.join(mf.model_ws, "ex3.clncbb")
 cbb = flopy.utils.CellBudgetFile(cbb_file)
-# cbb.list_records()
+cbb.headers
 
+# +
 simflow = cbb.get_data(kstpkper=(0, 0), text="GWF")[0]
 for i in range(nper - 1):
     simflow = np.append(
@@ -297,8 +298,9 @@
 # +
 cbb_file = os.path.join(mf.model_ws, f"{modelname}.clncb")
 cbb = flopy.utils.CellBudgetFile(cbb_file)
-# cbb.list_records()
+cbb.headers
 
+# +
 simflow = cbb.get_data(kstpkper=(0, 0), text="GWF")[0]
 for i in range(nper - 1):
     simflow = np.append(
@@ -392,8 +394,9 @@
 # +
 cbb_file = os.path.join(mf.model_ws, f"{modelname}.clncb")
 cbb = flopy.utils.CellBudgetFile(cbb_file)
-# cbb.list_records()
+cbb.headers
 
+# +
 simflow = cbb.get_data(kstpkper=(0, 0), text="GWF")[0]
 for i in range(nper - 1):
     simflow = np.append(
@@ -490,8 +493,9 @@
 # +
 cbb_file = os.path.join(mf.model_ws, f"{modelname}.clncb")
 cbb = flopy.utils.CellBudgetFile(cbb_file)
-# cbb.list_records()
+cbb.headers
 
+# +
 simflow = cbb.get_data(kstpkper=(0, 0), text="GWF")[0]
 for i in range(nper - 1):
     simflow = np.append(
@@ -575,8 +579,9 @@
 # +
 cbb_file = os.path.join(mf.model_ws, f"{modelname}.clncb")
 cbb = flopy.utils.CellBudgetFile(cbb_file)
-# cbb.list_records()
+cbb.headers
 
+# +
 simflow = cbb.get_data(kstpkper=(0, 0), text="GWF")[0]
 for i in range(nper - 1):
     simflow = np.append(

.docs/Notebooks/sfrpackage_example.py

@@ -33,8 +33,6 @@
 import glob
 import os
 import shutil
-
-# +
 import sys
 from pprint import pformat
 from tempfile import TemporaryDirectory
@@ -237,7 +235,7 @@
 
 bpth = os.path.join(path, "test1ss.cbc")
 cbbobj = bf.CellBudgetFile(bpth)
-cbbobj.list_records()
+cbbobj.headers
 
 sfrleak = cbbobj.get_data(text="  STREAM LEAKAGE")[0]
 sfrleak[sfrleak == 0] = np.nan  # remove zero values

.docs/Notebooks/uzf_example.py

@@ -238,7 +238,6 @@
 avail = os.path.isfile(fpth)
 if avail:
     uzfbdobjct = flopy.utils.CellBudgetFile(fpth)
-    uzfbdobjct.list_records()
 else:
     print(f'"{fpth}" is not available')
 

autotest/regression/test_mf6.py

@@ -3687,7 +3687,6 @@ def test001a_tharmonic(function_tmpdir, example_data_path):
 
     # get expected results
     budget_obj = CellBudgetFile(expected_cbc_file_a, precision="auto")
-    budget_obj.list_records()
     budget_frf_valid = np.array(
         budget_obj.get_data(text="    FLOW JA FACE", full3D=True)
     )
@@ -4464,7 +4463,6 @@ def test006_2models_mvr(function_tmpdir, example_data_path):
         expected_cbc_file_a,
         precision="double",
     )
-    budget_obj.list_records()
 
     # test getting models
     model_dict = sim.model_dict

autotest/test_binaryfile.py

@@ -131,6 +131,8 @@ def test_headfile_build_index(example_data_path):
     assert hds.kstpkper == [(1, kper + 1) for kper in range(1097)]
     np.testing.assert_array_equal(hds.iposarray, np.arange(3291) * 3244 + 44)
     assert hds.iposarray.dtype == np.int64
+    with pytest.deprecated_call(match="use headers instead"):
+        assert hds.list_records() is None
     # check first and last row of data frame
     pd.testing.assert_frame_equal(
         hds.headers.iloc[[0, -1]],
@@ -186,6 +188,8 @@ def test_concentration_build_index(example_data_path):
     assert ucn.kstpkper == [(1, 1)]
     np.testing.assert_array_equal(ucn.iposarray, np.arange(8) * 1304 + 44)
     assert ucn.iposarray.dtype == np.int64
+    with pytest.deprecated_call(match="use headers instead"):
+        assert ucn.list_records() is None
     # check first and last row of data frame
     pd.testing.assert_frame_equal(
         ucn.headers.iloc[[0, -1]],

autotest/test_cbc_full3D.py

@@ -86,7 +86,7 @@ def cbc_eval_size(cbcobj, nnodes, shape3d):
 def cbc_eval_data(cbcobj, shape3d):
     cbc_pth = cbcobj.filename
     print(f"{cbc_pth}:\n")
-    cbcobj.list_unique_records()
+    print(cbcobj.headers[["text", "imeth"]].drop_duplicates())
 
     names = cbcobj.get_unique_record_names(decode=True)
     times = cbcobj.get_times()

autotest/test_cellbudgetfile.py

@@ -400,10 +400,14 @@ def test_cellbudgetfile_position(function_tmpdir, zonbud_model_path):
 
     v2 = CellBudgetFile(opth, verbose=True)
 
-    try:
-        v2.list_records()
-    except:
-        assert False, f"could not list records on {opth}"
+    with pytest.deprecated_call(match="use headers instead"):
+        assert v2.list_records() is None
+    with pytest.deprecated_call(match=r"drop_duplicates\(\) instead"):
+        assert v2.list_unique_records() is None
+    with pytest.deprecated_call(match=r"drop_duplicates\(\) instead"):
+        assert v2.list_unique_packages(True) is None
+    with pytest.deprecated_call(match=r"drop_duplicates\(\) instead"):
+        assert v2.list_unique_packages(False) is None
 
     names = v2.get_unique_record_names(decode=True)
 

autotest/test_formattedfile.py

@@ -44,6 +44,8 @@ def test_headfile_build_index(example_data_path):
     assert hds.kstpkper == [(50, 1)]
     np.testing.assert_array_equal(hds.iposarray, [98])
     assert hds.iposarray.dtype == np.int64
+    with pytest.deprecated_call(match="use headers instead"):
+        assert hds.list_records() is None
     pd.testing.assert_frame_equal(
         hds.headers,
         pd.DataFrame(

flopy/utils/binaryfile.py

@@ -631,11 +631,11 @@ class HeadFile(BinaryLayerFile):
 
     >>> import flopy.utils.binaryfile as bf
     >>> hdobj = bf.HeadFile('model.hds', precision='single')
-    >>> hdobj.list_records()
+    >>> hdobj.headers
     >>> rec = hdobj.get_data(kstpkper=(0, 49))
 
     >>> ddnobj = bf.HeadFile('model.ddn', text='drawdown', precision='single')
-    >>> ddnobj.list_records()
+    >>> ddnobj.headers
     >>> rec = ddnobj.get_data(totim=100.)
 
     """
@@ -784,7 +784,7 @@ class UcnFile(BinaryLayerFile):
 
     >>> import flopy.utils.binaryfile as bf
     >>> ucnobj = bf.UcnFile('MT3D001.UCN', precision='single')
-    >>> ucnobj.list_records()
+    >>> ucnobj.headers
     >>> rec = ucnobj.get_data(kstpkper=(0, 0))
 
     """
@@ -851,7 +851,7 @@ class HeadUFile(BinaryLayerFile):
 
     >>> import flopy.utils.binaryfile as bf
     >>> hdobj = bf.HeadUFile('model.hds')
-    >>> hdobj.list_records()
+    >>> hdobj.headers
     >>> usgheads = hdobj.get_data(kstpkper=(0, 49))
 
     """
@@ -1001,7 +1001,7 @@ class CellBudgetFile:
 
     >>> import flopy.utils.binaryfile as bf
     >>> cbb = bf.CellBudgetFile('mymodel.cbb')
-    >>> cbb.list_records()
+    >>> cbb.headers
     >>> rec = cbb.get_data(kstpkper=(0,0), text='RIVER LEAKAGE')
 
     """
@@ -1458,7 +1458,14 @@ def _find_paknam(self, paknam, to=False):
     def list_records(self):
         """
         Print a list of all of the records in the file
+
+        .. deprecated:: 3.8.0
+           Use :attr:`headers` instead.
         """
+        warnings.warn(
+            "list_records() is deprecated; use headers instead.",
+            DeprecationWarning,
+        )
         for rec in self.recordarray:
             if isinstance(rec, bytes):
                 rec = rec.decode()
@@ -1467,7 +1474,15 @@ def list_records(self):
     def list_unique_records(self):
         """
         Print a list of unique record names
+
+        .. deprecated:: 3.8.0
+           Use `headers[["text", "imeth"]].drop_duplicates()` instead.
         """
+        warnings.warn(
+            "list_unique_records() is deprecated; use "
+            'headers[["text", "imeth"]].drop_duplicates() instead.',
+            DeprecationWarning,
+        )
         print("RECORD           IMETH")
         print(22 * "-")
         for rec, imeth in zip(self.textlist, self.imethlist):
@@ -1478,7 +1493,17 @@ def list_unique_records(self):
     def list_unique_packages(self, to=False):
         """
         Print a list of unique package names
+
+        .. deprecated:: 3.8.0
+           Use `headers.paknam.drop_duplicates()` or
+           `headers.paknam2.drop_duplicates()` instead.
         """
+        warnings.warn(
+            "list_unique_packages() is deprecated; use "
+            "headers.paknam.drop_duplicates() or "
+            "headers.paknam2.drop_duplicates() instead",
+            DeprecationWarning,
+        )
         for rec in self._unique_package_names(to):
             if isinstance(rec, bytes):
                 rec = rec.decode()

flopy/utils/datafile.py

@@ -430,9 +430,14 @@ def _build_index(self):
     def list_records(self):
         """
         Print a list of all of the records in the file
-        obj.list_records()
 
+        .. deprecated:: 3.8.0
+           Use :attr:`headers` instead.
         """
+        warnings.warn(
+            "list_records() is deprecated; use headers instead.",
+            DeprecationWarning,
+        )
         for header in self.recordarray:
             print(header)
         return

flopy/utils/formattedfile.py

@@ -361,7 +361,7 @@ class FormattedHeadFile(FormattedLayerFile):
 
     >>> import flopy.utils.formattedfile as ff
     >>> hdobj = ff.FormattedHeadFile('model.fhd', precision='single')
-    >>> hdobj.list_records()
+    >>> hdobj.headers
     >>> rec = hdobj.get_data(kstpkper=(0, 49))
     >>> rec2 = ddnobj.get_data(totim=100.)