From bbabf86c0292ed2b237f89371afba01140050592 Mon Sep 17 00:00:00 2001
From: Mike Taves <mwtoews@gmail.com>
Date: Fri, 31 May 2024 22:33:46 +1200
Subject: [PATCH] refactor: deprecate unused
 flopy.utils.binaryfile.binaryread_struct (#2201)

---
 autotest/test_binaryfile.py | 32 ++++++++++++++++++++++++++++++++
 flopy/utils/binaryfile.py   | 32 +++++++++++++++++++++++++-------
 2 files changed, 57 insertions(+), 7 deletions(-)

diff --git a/autotest/test_binaryfile.py b/autotest/test_binaryfile.py
index a4e5a400e1..1dff66332e 100644
--- a/autotest/test_binaryfile.py
+++ b/autotest/test_binaryfile.py
@@ -39,6 +39,38 @@ def zonbud_model_path(example_data_path):
     return example_data_path / "zonbud_examples"
 
 
+def test_binaryread(example_data_path):
+    # test low-level binaryread() method
+    pth = example_data_path / "freyberg" / "freyberg.githds"
+    with open(pth, "rb") as fp:
+        res = flopy.utils.binaryfile.binaryread(fp, np.int32, 2)
+        np.testing.assert_array_equal(res, np.array([1, 1], np.int32))
+        res = flopy.utils.binaryfile.binaryread(fp, np.float32, 2)
+        np.testing.assert_array_equal(res, np.array([10, 10], np.float32))
+        res = flopy.utils.binaryfile.binaryread(fp, str)
+        assert res == b"            HEAD"
+        res = flopy.utils.binaryfile.binaryread(fp, np.int32)
+        assert res == 20
+
+
+def test_deprecated_binaryread_struct(example_data_path):
+    # similar to test_binaryread(), but check the calls are deprecated
+    pth = example_data_path / "freyberg" / "freyberg.githds"
+    with open(pth, "rb") as fp:
+        with pytest.deprecated_call():
+            res = flopy.utils.binaryfile.binaryread_struct(fp, np.int32, 2)
+        np.testing.assert_array_equal(res, np.array([1, 1], np.int32))
+        with pytest.deprecated_call():
+            res = flopy.utils.binaryfile.binaryread_struct(fp, np.float32, 2)
+        np.testing.assert_array_equal(res, np.array([10, 10], np.float32))
+        with pytest.deprecated_call():
+            res = flopy.utils.binaryfile.binaryread_struct(fp, str)
+        assert res == b"            HEAD"
+        with pytest.deprecated_call():
+            res = flopy.utils.binaryfile.binaryread_struct(fp, np.int32)
+        assert res == 20
+
+
 def test_binaryfile_writeread(function_tmpdir, nwt_model_path):
     model = "Pr3_MFNWT_lower.nam"
     ml = flopy.modflow.Modflow.load(
diff --git a/flopy/utils/binaryfile.py b/flopy/utils/binaryfile.py
index 0efce1c493..fa70ad254f 100644
--- a/flopy/utils/binaryfile.py
+++ b/flopy/utils/binaryfile.py
@@ -274,10 +274,16 @@ def binaryread_struct(file, vartype, shape=(1,), charlen=16):
             cannot be returned, only multi-character strings.  Shape has no
             affect on strings.
 
+    .. deprecated:: 3.8.0
+       Use :meth:`binaryread` instead.
+
     """
     import struct
 
-    import numpy as np
+    warnings.warn(
+        "binaryread_struct() is deprecated; use binaryread() instead.",
+        DeprecationWarning,
+    )
 
     # store the mapping from type to struct format (fmt)
     typefmtd = {np.int32: "i", np.float32: "f", np.float64: "d"}
@@ -306,21 +312,33 @@ def binaryread_struct(file, vartype, shape=(1,), charlen=16):
 
 def binaryread(file, vartype, shape=(1,), charlen=16):
     """
-    Uses numpy to read from binary file.  This was found to be faster than the
-        struct approach and is used as the default.
+    Read text, a scalar value, or an array of values from a binary file.
+
+    Parameters
+    ----------
+    file : file object
+        is an open file object
+    vartype : type
+        is the return variable type: str, numpy.int32, numpy.float32,
+        or numpy.float64
+    shape : tuple, default (1,)
+        is the shape of the returned array (shape(1, ) returns a single
+        value) for example, shape = (nlay, nrow, ncol)
+    charlen : int, default 16
+        is the length of the text string.  Note that string arrays
+        cannot be returned, only multi-character strings.  Shape has no
+        affect on strings.
 
     """
 
     # read a string variable of length charlen
     if vartype == str:
-        result = file.read(charlen * 1)
+        result = file.read(charlen)
     else:
         # find the number of values
         nval = np.prod(shape)
         result = np.fromfile(file, vartype, nval)
-        if nval == 1:
-            result = result  # [0]
-        else:
+        if nval != 1:
             result = np.reshape(result, shape)
     return result