restore kstpkper to 1-based, fix usage examples

flopy/utils/binaryfile.py

@@ -475,14 +475,12 @@ def _build_index(self):
                 continue
             if ipos == 0:
                 self.times.append(header["totim"])
-                self.kstpkper.append((header["kstp"] - 1, header["kper"] - 1))
+                self.kstpkper.append((header["kstp"], header["kper"]))
             else:
                 totim = header["totim"]
                 if totim != self.times[-1]:
                     self.times.append(totim)
-                    self.kstpkper.append(
-                        (header["kstp"] - 1, header["kper"] - 1)
-                    )
+                    self.kstpkper.append((header["kstp"], header["kper"]))
             ipos = self.file.tell()
             self.iposarray.append(ipos)
             databytes = self.get_databytes(header)
@@ -611,7 +609,7 @@ class HeadFile(BinaryLayerFile):
     >>> import flopy.utils.binaryfile as bf
     >>> hdobj = bf.HeadFile('model.hds', precision='single')
     >>> hdobj.list_records()
-    >>> rec = hdobj.get_data(kstpkper=(0, 50))
+    >>> rec = hdobj.get_data(kstpkper=(0, 49))
 
     >>> ddnobj = bf.HeadFile('model.ddn', text='drawdown', precision='single')
     >>> ddnobj.list_records()
@@ -1202,7 +1200,7 @@ def _build_index(self):
                 header["totim"] = totim
             if totim >= 0 and totim not in self.times:
                 self.times.append(totim)
-            kstpkper = (header["kstp"] - 1, header["kper"] - 1)
+            kstpkper = (header["kstp"], header["kper"])
             if kstpkper not in self.kstpkper:
                 self.kstpkper.append(kstpkper)
             if header["text"] not in self.textlist:
@@ -1507,15 +1505,16 @@ def _unique_package_names(self):
 
     def get_kstpkper(self):
         """
-        Get stress period and time step tuples.
+        Get a list of tuples (stress period, time step).
+        Indices are 0-based, use `kstpkper` attribute for 1-based.
 
         Returns
         -------
         list of (kstp, kper) tuples
             List of unique combinations of stress period &
             time step indices (0-based) in the binary file
         """
-        return self.kstpkper
+        return [(kstp - 1, kper - 1) for kstp, kper in self.kstpkper]
 
     def get_indices(self, text=None):
         """
@@ -1763,23 +1762,23 @@ def get_ts(self, idx, text=None, times=None):
         result = self._init_result(nstation)
 
         timesint = self.get_times()
+        kstpkper = self.get_kstpkper()
+        nsteps = len(kstpkper)
         if len(timesint) < 1:
             if times is None:
-                timesint = [x + 1 for x in range(len(self.kstpkper))]
+                timesint = [x + 1 for x in range(nsteps)]
             else:
                 if isinstance(times, np.ndarray):
                     times = times.tolist()
-                if len(times) != len(self.kstpkper):
-                    raise Exception(
-                        "times passed to CellBudgetFile get_ts() "
-                        "method must be equal to {} "
-                        "not {}".format(len(self.kstpkper), len(times))
+                if len(times) != nsteps:
+                    raise ValueError(
+                        f"number of times provided ({len(times)}) must equal number of time steps in cell budget file ({nsteps})"
                     )
                 timesint = times
         for idx, t in enumerate(timesint):
             result[idx, 0] = t
 
-        for itim, k in enumerate(self.kstpkper):
+        for itim, k in enumerate(kstpkper):
             try:
                 v = self.get_data(kstpkper=k, text=text, full3D=True)
                 # skip missing data - required for storage

flopy/utils/datafile.py

@@ -477,15 +477,16 @@ def get_times(self):
 
     def get_kstpkper(self):
         """
-        Get stress period and time step tuples.
+        Get a list of tuples (stress period, time step).
+        Indices are 0-based, use `kstpkper` attribute for 1-based.
 
         Returns
         -------
         list of (kstp, kper) tuples
             List of unique combinations of stress period &
             time step indices (0-based) in the binary file
         """
-        return self.kstpkper
+        return [(kstp - 1, kper - 1) for kstp, kper in self.kstpkper]
 
     def get_data(self, kstpkper=None, idx=None, totim=None, mflay=None):
         """

flopy/utils/formattedfile.py

@@ -117,7 +117,7 @@ def _build_index(self):
         Build the recordarray and iposarray, which maps the header information
         to the position in the formatted file.
         """
-        self.kstpkper  # 0-based array of time step/stress periods
+        self.kstpkper  # 1-based array of time step/stress periods
         self.recordarray  # array of data headers
         self.iposarray  # array of seek positions for each record
         self.nlay  # Number of model layers
@@ -155,7 +155,6 @@ def _build_index(self):
         self.recordarray = np.array(self.recordarray, self.header.get_dtype())
         self.iposarray = np.array(self.iposarray)
         self.nlay = np.max(self.recordarray["ilay"])
-        return
 
     def _store_record(self, header, ipos):
         """
@@ -167,7 +166,7 @@ def _store_record(self, header, ipos):
         totim = header["totim"]
         if totim > 0 and totim not in self.times:
             self.times.append(totim)
-        kstpkper = (header["kstp"] - 1, header["kper"] - 1)
+        kstpkper = (header["kstp"], header["kper"])
         if kstpkper not in self.kstpkper:
             self.kstpkper.append(kstpkper)
 
@@ -356,7 +355,7 @@ class FormattedHeadFile(FormattedLayerFile):
     >>> import flopy.utils.formattedfile as ff
     >>> hdobj = ff.FormattedHeadFile('model.fhd', precision='single')
     >>> hdobj.list_records()
-    >>> rec = hdobj.get_data(kstpkper=(0, 50))
+    >>> rec = hdobj.get_data(kstpkper=(0, 49))
     >>> rec2 = ddnobj.get_data(totim=100.)
 
     """
@@ -371,7 +370,6 @@ def __init__(
     ):
         self.text = text
         super().__init__(filename, precision, verbose, kwargs)
-        return
 
     def _get_text_header(self):
         """