tecio-python 0.4.0__py3-none-any.whl → 0.4.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. tecio/__init__.py +46 -2
  2. tecio/_constants.py +2 -2
  3. tecio/_dat_read.py +268 -17
  4. tecio/_dat_write.py +347 -10
  5. tecio/_elements.py +1311 -0
  6. tecio/_io.py +108 -31
  7. tecio/_meta.py +47 -20
  8. tecio/_plt_legacy.py +9 -1
  9. tecio/_plt_read.py +285 -89
  10. tecio/_plt_write.py +286 -9
  11. tecio/_reader.py +460 -19
  12. tecio/_szl_read.py +155 -17
  13. tecio/_szl_write.py +322 -11
  14. tecio/_utils.py +78 -15
  15. tecio/_writer.py +963 -102
  16. tecio/cli/tec2mat.py +69 -30
  17. tecio/cli/tecaux.py +24 -30
  18. tecio/cli/tecdump.py +67 -5
  19. tecio/cli/tecelretyp.py +1096 -0
  20. tecio/cli/tecextract.py +57 -14
  21. tecio/cli/tecfix.py +32 -14
  22. tecio/cli/tecmerge.py +289 -45
  23. tecio/cli/teconvert.py +29 -16
  24. tecio/cli/tecscale.py +40 -13
  25. tecio/cli/tecslice.py +158 -69
  26. tecio/cli/tecstats.py +6 -2
  27. tecio/libtecio.py +192 -67
  28. {tecio_python-0.4.0.data/data/share → tecio_python-0.4.2.data/data/share/tecio}/plugins/matlab/tecmat2struct.m +18 -18
  29. {tecio_python-0.4.0.data/data/share → tecio_python-0.4.2.data/data/share/tecio}/plugins/paraview/TecplotTecioReader.py +463 -38
  30. {tecio_python-0.4.0.data/data/share → tecio_python-0.4.2.data/data/share/tecio}/plugins/paraview/TecplotTecioWriter.py +459 -84
  31. {tecio_python-0.4.0.dist-info → tecio_python-0.4.2.dist-info}/METADATA +33 -17
  32. tecio_python-0.4.2.dist-info/RECORD +40 -0
  33. {tecio_python-0.4.0.dist-info → tecio_python-0.4.2.dist-info}/WHEEL +1 -1
  34. {tecio_python-0.4.0.dist-info → tecio_python-0.4.2.dist-info}/entry_points.txt +1 -0
  35. tecio_python-0.4.0.dist-info/RECORD +0 -38
  36. {tecio_python-0.4.0.data/data/share → tecio_python-0.4.2.data/data/share/tecio}/plugins/matlab/contourfe.m +0 -0
  37. {tecio_python-0.4.0.dist-info → tecio_python-0.4.2.dist-info}/licenses/LICENSE +0 -0
  38. {tecio_python-0.4.0.dist-info → tecio_python-0.4.2.dist-info}/licenses/NOTICE +0 -0
  39. {tecio_python-0.4.0.dist-info → tecio_python-0.4.2.dist-info}/top_level.txt +0 -0
tecio/_szl_write.py CHANGED
@@ -18,6 +18,7 @@ from ._constants import (
18
18
  DataPacking,
19
19
  DataType,
20
20
  FaceNeighborMode,
21
+ FeCellShape,
21
22
  FileType,
22
23
  ValueLocation,
23
24
  ZoneType,
@@ -25,12 +26,14 @@ from ._constants import (
25
26
  from ._meta import ZoneMeta
26
27
  from ._writer import (
27
28
  PassiveVarsSpec,
29
+ PreparedFEMixedZone,
28
30
  PreparedFEZone,
29
31
  PreparedOrderedZone,
30
32
  TecplotWriter,
31
33
  VarSharingSpec,
32
34
  normalize_precision,
33
35
  prepare_fe_zone,
36
+ prepare_femixed_zone,
34
37
  prepare_ordered_zone,
35
38
  var_sharing_for_libtecio,
36
39
  zone_for_libtecio,
@@ -56,7 +59,11 @@ _FE_SIMPLE: frozenset[ZoneType] = frozenset({
56
59
 
57
60
 
58
61
  def _infer_data_type(dt: DataType | np.dtype) -> DataType:
59
- """Return the closest C-supported DataType for a DataType or NumPy dtype."""
62
+ """Return the closest C-supported DataType for a DataType or NumPy dtype.
63
+
64
+ Raises:
65
+ ValueError: If the dtype is not supported.
66
+ """
60
67
  # Mapping of NumPy type categories to closest DataType
61
68
  closest_dtype_map = {
62
69
  np.dtype(np.float64): DataType.DOUBLE,
@@ -142,6 +149,9 @@ def _write_data(
142
149
  2. Defaults to double precision for array-like (list, tuple, etc)
143
150
  3. Optionally casts to input DataType or numpy dtype.
144
151
  4. Assumes data is in the correct shape and order (column major / Fortran order)
152
+
153
+ Raises:
154
+ ValueError: If the resolved data type is not supported.
145
155
  """
146
156
  # Mappings between C-supported data types and numpy dtypes
147
157
  dtype_to_datatype: dict[np.dtype, DataType] = {
@@ -229,6 +239,38 @@ def _write_connectivity(
229
239
  )
230
240
 
231
241
 
242
+ def _write_femixed_connectivity(
243
+ handle: ctypes.c_void_p,
244
+ zone_num: int,
245
+ node_maps: Sequence[npt.NDArray],
246
+ num_nodes: int,
247
+ ) -> None:
248
+ """Write the section node maps of a FEMIXED zone, in section order.
249
+
250
+ All sections of a zone share one integer width, 64 bit only when *num_nodes* does
251
+ not fit 32 bits. Each section is converted to 1-based indices of that width in a
252
+ single pass, so at most one section is copied at a time.
253
+
254
+ Args:
255
+ handle (ctypes.c_void_p): C library file handle.
256
+ zone_num (int): 1-based zone index.
257
+ node_maps (Sequence[npt.NDArray]): 0-based ``(num_cells, nodes_per_cell)`` array
258
+ of each section.
259
+ num_nodes (int): Zone node count.
260
+ """
261
+ wide = num_nodes > np.iinfo(np.int32).max
262
+ dtype = np.int64 if wide else np.int32
263
+ write = (
264
+ libtecio.tec_zone_node_map_write64
265
+ if wide
266
+ else libtecio.tec_zone_node_map_write32
267
+ )
268
+ for node_map in node_maps:
269
+ if node_map.size:
270
+ one_based = np.add(node_map, 1, dtype=dtype, casting="unsafe")
271
+ write(handle, zone_num, one_based.ravel(order="C"))
272
+
273
+
232
274
  def _write_zone_aux_data(
233
275
  handle: ctypes.c_void_p, aux: dict[int, dict[str, Any]]
234
276
  ) -> None:
@@ -398,8 +440,11 @@ class TecplotSzlWriter(TecplotWriter):
398
440
  def _check_handle(self) -> ctypes.c_void_p:
399
441
  """Return file handle catching errors if the writer has already been closed.
400
442
 
401
- This ensures the that each libtecio call will execute or return an appropriate
402
- ValueError.
443
+ This ensures the that each libtecio call will execute or raise an appropriate
444
+ RuntimeError.
445
+
446
+ Raises:
447
+ RuntimeError: If the writer has been closed.
403
448
  """
404
449
  if self.handle is None:
405
450
  raise RuntimeError(f"I/O operation on closed file: '{self.path}'")
@@ -512,14 +557,15 @@ class TecplotSzlWriter(TecplotWriter):
512
557
  final output file when :meth:`close` is called.
513
558
 
514
559
  Raises:
515
- NotImplementedError:
560
+ NotImplementedError:
516
561
  If *datapacking* is :attr:`~tecio.libtecio.DataPacking.POINT`.
517
562
  TypeError:
518
563
  If *passive_vars*/*var_sharing* isn't a list/tuple/set/mapping as
519
564
  appropriate, or mixes variable names and indices.
520
565
  ValueError:
521
- If I/O operation attempted on closed or None file handle, or a variable
522
- is named in both *passive_vars* and *var_sharing*.
566
+ If I/O operation attempted on closed or empty file handle, a variable is
567
+ named in both *passive_vars* and *var_sharing*, or *datapacking* is not a
568
+ recognised value.
523
569
  RuntimeError:
524
570
  If attempting to write variable aux before variables are defined.
525
571
  KeyError:
@@ -771,13 +817,14 @@ class TecplotSzlWriter(TecplotWriter):
771
817
 
772
818
  Raises:
773
819
  NotImplementedError:
774
- For FEPOLYGON, FEPOLYHEDRON, or if *datapacking* is
775
- :attr:`~tecio.libtecio.DataPacking.POINT`.
820
+ If *datapacking* is :attr:`~tecio.libtecio.DataPacking.POINT`.
776
821
  TypeError:
777
822
  If *passive_vars*/*var_sharing* isn't a list/tuple/set/mapping as
778
823
  appropriate, or mixes variable names and indices.
779
824
  ValueError:
780
- On variable count or array length mismatch; if ``node_map`` is omitted
825
+ For FEPOLYGON or FEPOLYHEDRON (not supported in SZPLT files, see
826
+ :meth:`write_poly_zone`); on variable count or array length mismatch;
827
+ if ``node_map`` is omitted
781
828
  without ``con_sharing``; if ``var_sharing``/``con_sharing`` reference a
782
829
  zone with no recorded node/cell count, or one whose count disagrees with
783
830
  this zone's; or a variable named in both *passive_vars* and
@@ -811,10 +858,14 @@ class TecplotSzlWriter(TecplotWriter):
811
858
  "by the SZL binary format. Use DataPacking.BLOCK (the default) "
812
859
  "or write to a .dat file instead."
813
860
  )
861
+ if zone_type in (ZoneType.FEPOLYGON, ZoneType.FEPOLYHEDRON):
862
+ raise ValueError(
863
+ f"{zone_type.name} zones are face-based, use write_poly_zone "
864
+ "(which SZPLT files do not support)."
865
+ )
814
866
  if zone_type not in _FE_SIMPLE:
815
867
  raise NotImplementedError(
816
- f"Zone type {zone_type.name!r} is not supported by szl file formats. "
817
- "Polygon and polyhedral zones require the low-level API."
868
+ f"Zone type {zone_type.name!r} is not supported by szl file formats."
818
869
  )
819
870
 
820
871
  # Convert input data to NumPy arrays
@@ -958,3 +1009,263 @@ class TecplotSzlWriter(TecplotWriter):
958
1009
  num_face_connections=num_face_cons or None,
959
1010
  )
960
1011
  )
1012
+
1013
+ # -- FEMIXED zone writer -----------------------------------------------------------
1014
+
1015
+ def write_femixed_zone(
1016
+ self,
1017
+ data: Sequence[npt.ArrayLike],
1018
+ cell_shapes: Sequence[FeCellShape | int | str] | None = None,
1019
+ node_maps: Sequence[npt.ArrayLike] | None = None,
1020
+ *,
1021
+ title: str | None = None,
1022
+ variables: list[str] | None = None,
1023
+ value_locations: Sequence[ValueLocation] | None = None,
1024
+ passive_vars: PassiveVarsSpec | None = None,
1025
+ var_sharing: VarSharingSpec | None = None,
1026
+ con_sharing: int | None = None,
1027
+ solution_time: float = 0.0,
1028
+ strand_id: int = 0,
1029
+ aux: dict[str, Any] | None = None,
1030
+ datapacking: DataPacking | str = DataPacking.BLOCK,
1031
+ flush: bool = False,
1032
+ ) -> None:
1033
+ """Write a complete FEMIXED (mixed finite-element) zone.
1034
+
1035
+ A FEMIXED zone holds 1 to 16 sections, each with one cell shape. A typical use
1036
+ is a CFD volume mesh of tetrahedra, pyramids, prisms and hexahedra in one zone
1037
+ rather than every cell padded to a brick. All sections must have the same
1038
+ spatial dimension (all line, all surface or all volume cells). Cells are
1039
+ numbered through the sections in order, so a CELL_CENTERED array lists the cells
1040
+ of the first section first. Only linear (grid order 1) cells are supported.
1041
+
1042
+ Node and cell counts are inferred from *node_maps*, or from the zone referenced
1043
+ by *con_sharing*. The 32- or 64-bit write path is chosen from the node count.
1044
+ This writer does not write face-neighbor connections.
1045
+
1046
+ Args:
1047
+ data (Sequence[npt.ArrayLike]):
1048
+ Sequence of 1-D arrays, one per active (non-passive, non-shared) dataset
1049
+ variable, in dataset order. NODAL arrays must have length ``num_nodes``,
1050
+ CELL_CENTERED arrays the total cell count over all sections.
1051
+ cell_shapes (Sequence[FeCellShape]):
1052
+ Cell shape of each section. A shape name or value is also accepted.
1053
+ Required unless ``con_sharing`` is set, in which case it must be omitted.
1054
+ node_maps (Sequence[npt.ArrayLike]):
1055
+ One integer array per section, of shape ``(num_cells, nodes_per_cell)``
1056
+ with 0-based node indices. A flat array is reshaped. A section may have
1057
+ no cells. Required unless ``con_sharing`` is set, in which case it must
1058
+ be omitted.
1059
+ title (str):
1060
+ Zone title string. Defaults to ``"FEMixed_Zone_{index}"``, this zone's
1061
+ 0-based index.
1062
+ variables (list[str]):
1063
+ Variable name list. Required only when the file has not been opened yet
1064
+ (lazy-open path). Defaults to ``[V1, V2, V3, ...]``.
1065
+ value_locations (Sequence[ValueLocation]):
1066
+ Per-active-variable :class:`~tecio.ValueLocation`. Defaults to all
1067
+ ``NODAL``.
1068
+ passive_vars (list | tuple | set | None):
1069
+ Variables to mark passive: a list, tuple, or set of variable names, or
1070
+ of 0-based indices. Defaults to all active.
1071
+ var_sharing (Mapping[int | str, int]):
1072
+ Variables to share from another zone: a ``{variable: source zone}``
1073
+ mapping, name or 0-based index to 0-based zone index.
1074
+ con_sharing (int):
1075
+ Optional index of a FEMIXED zone to share the connectivity of. The first
1076
+ zone in a dataset must own its connectivity.
1077
+ solution_time (float):
1078
+ Solution time for transient data. Defaults to ``0.0``.
1079
+ strand_id (int):
1080
+ Strand ID for transient data, ``0`` for static zones.
1081
+ aux (dict[str, str | float | int]):
1082
+ Zone-level auxiliary data as ``{name: value}`` pairs.
1083
+ datapacking (DataPacking | str):
1084
+ Only :attr:`~tecio.DataPacking.BLOCK` (the default) is supported.
1085
+ flush:
1086
+ If ``True``, flush this zone and all previous data to a temporary
1087
+ intermediate file after writing, releasing data from memory.
1088
+
1089
+ Raises:
1090
+ NotImplementedError:
1091
+ If *datapacking* is :attr:`~tecio.DataPacking.POINT`.
1092
+ ValueError:
1093
+ On a bad section layout or array shape, sections of different spatial
1094
+ dimension, fewer dataset variables than the cell dimension, a variable
1095
+ count or array length mismatch, or a bad ``con_sharing`` or
1096
+ ``var_sharing`` source zone. See
1097
+ :func:`~tecio._writer.prepare_femixed_zone`.
1098
+ TypeError:
1099
+ If *passive_vars*/*var_sharing* isn't a list/tuple/set/mapping as
1100
+ appropriate, or mixes variable names and indices.
1101
+ KeyError:
1102
+ A *passive_vars*/*var_sharing* name doesn't match any dataset variable.
1103
+ IndexError:
1104
+ A *passive_vars*/*var_sharing* index is out of range.
1105
+ RuntimeError:
1106
+ If the writer has been closed.
1107
+
1108
+ Note:
1109
+ SZPLT reorders cells and nodes internally for storage, so the arrays read
1110
+ back may be a permutation of the arrays written, consistently across all
1111
+ variables and the node maps.
1112
+ """
1113
+ # Validate input
1114
+ if isinstance(datapacking, str):
1115
+ try:
1116
+ datapacking = DataPacking[datapacking.upper()]
1117
+ except KeyError:
1118
+ raise ValueError(
1119
+ f"datapacking={datapacking!r} is not a recognised value; "
1120
+ "use DataPacking.BLOCK or the string 'BLOCK'."
1121
+ ) from None
1122
+ if datapacking != DataPacking.BLOCK:
1123
+ raise NotImplementedError(
1124
+ "DATAPACKING=POINT is an ASCII-only layout and is not supported "
1125
+ "by the SZL binary format. Use DataPacking.BLOCK (the default) "
1126
+ "or write to a .dat file instead."
1127
+ )
1128
+
1129
+ arrays: list[npt.NDArray] = [np.asarray(arr) for arr in data]
1130
+ if title is None:
1131
+ title = f"FEMixed_Zone_{self.current_zone + 1}"
1132
+ if variables is None:
1133
+ variables = [f"V{i}" for i in range(1, len(data) + 1)]
1134
+
1135
+ # Open the file if lazily loaded and flush buffered aux data
1136
+ if self.handle is None:
1137
+ self._open(variables)
1138
+ if self.current_zone == -1:
1139
+ self.flush_aux()
1140
+
1141
+ variable_types = [
1142
+ _resolve_written_type(_infer_data_type(arr.dtype), self.precision)
1143
+ for arr in arrays
1144
+ ]
1145
+ prepared: PreparedFEMixedZone | None = prepare_femixed_zone(
1146
+ arrays,
1147
+ variable_types,
1148
+ cell_shapes=cell_shapes,
1149
+ node_maps=node_maps,
1150
+ value_locations=value_locations,
1151
+ passive_vars=passive_vars,
1152
+ var_sharing=var_sharing,
1153
+ con_sharing=con_sharing,
1154
+ dataset_variables=self._check_variables(),
1155
+ meta=self._meta,
1156
+ )
1157
+ if prepared is None:
1158
+ return
1159
+ share_idx = prepared.var_sharing
1160
+
1161
+ # Write zone header. The C library assigns and returns a 1-based zone
1162
+ # number; converted to 0-based for the public current_zone attribute.
1163
+ self.current_zone = (
1164
+ libtecio.tec_zone_create_fe_mixed(
1165
+ self._check_handle(),
1166
+ title,
1167
+ prepared.num_nodes,
1168
+ prepared.section_shapes,
1169
+ prepared.section_num_elements,
1170
+ var_types=prepared.variable_types_global,
1171
+ var_sharing=var_sharing_for_libtecio(share_idx),
1172
+ value_locations=prepared.value_locations_global,
1173
+ pas_vars=prepared.passive_vars,
1174
+ con_sharing=zone_for_libtecio(prepared.con_sharing),
1175
+ )
1176
+ - 1
1177
+ )
1178
+ zone_num = self.current_zone + 1
1179
+
1180
+ # Unsteady options
1181
+ if strand_id != 0 or solution_time != 0.0:
1182
+ libtecio.tec_zone_set_unsteady_options(
1183
+ handle=self._check_handle(),
1184
+ zone=zone_num,
1185
+ strand=strand_id,
1186
+ solution_time=solution_time,
1187
+ )
1188
+
1189
+ # Write zone-level aux data
1190
+ if aux is not None:
1191
+ _write_zone_aux_data(self._check_handle(), {zone_num: aux})
1192
+
1193
+ # Write active data only
1194
+ for var_idx, arr, dtype in zip(
1195
+ prepared.active_var_idx, arrays, variable_types, strict=True
1196
+ ):
1197
+ self.current_var = var_idx
1198
+ _write_data(
1199
+ self._check_handle(),
1200
+ zone_num=zone_num,
1201
+ var_num=var_idx + 1,
1202
+ data=arr,
1203
+ dt=dtype,
1204
+ )
1205
+
1206
+ # Write connectivity (if not shared)
1207
+ if prepared.con_sharing is None:
1208
+ _write_femixed_connectivity(
1209
+ self._check_handle(),
1210
+ zone_num,
1211
+ prepared.section_node_maps,
1212
+ prepared.num_nodes,
1213
+ )
1214
+
1215
+ # Flush zone data, releasing memory
1216
+ if flush:
1217
+ libtecio.tec_file_writer_flush(self._check_handle())
1218
+
1219
+ # Finally set zone metadata after successfully completing TecIO calls
1220
+ self._meta.record_zone(
1221
+ ZoneMeta(
1222
+ index=self.current_zone,
1223
+ title=title,
1224
+ zone_type=ZoneType.FEMIXED,
1225
+ solution_time=solution_time,
1226
+ strand_id=strand_id,
1227
+ num_aux_items=len(aux) if aux else 0,
1228
+ num_nodes=prepared.num_nodes,
1229
+ num_elements=prepared.num_cells,
1230
+ section_shapes=prepared.section_shapes,
1231
+ section_num_elements=prepared.section_num_elements,
1232
+ value_locations=tuple(prepared.value_locations_global),
1233
+ passive_vars=tuple(bool(p) for p in prepared.passive_vars),
1234
+ shared_vars=tuple(share_idx),
1235
+ data_types=tuple(prepared.variable_types_global),
1236
+ )
1237
+ )
1238
+
1239
+ def write_poly_zone(
1240
+ self,
1241
+ data: Sequence[npt.ArrayLike],
1242
+ zone_type: ZoneType,
1243
+ *,
1244
+ face_nodes: npt.ArrayLike | None = None,
1245
+ face_node_counts: npt.ArrayLike | None = None,
1246
+ face_left_elements: npt.ArrayLike | None = None,
1247
+ face_right_elements: npt.ArrayLike | None = None,
1248
+ boundary_connection_counts: npt.ArrayLike | None = None,
1249
+ boundary_connection_elements: npt.ArrayLike | None = None,
1250
+ boundary_connection_zones: npt.ArrayLike | None = None,
1251
+ title: str | None = None,
1252
+ variables: list[str] | None = None,
1253
+ value_locations: Sequence[ValueLocation] | None = None,
1254
+ passive_vars: PassiveVarsSpec | None = None,
1255
+ var_sharing: VarSharingSpec | None = None,
1256
+ con_sharing: int | None = None,
1257
+ solution_time: float = 0.0,
1258
+ strand_id: int = 0,
1259
+ aux: dict[str, Any] | None = None,
1260
+ datapacking: DataPacking | str = DataPacking.BLOCK,
1261
+ ) -> None:
1262
+ """Not supported: SZPLT files cannot hold polygon or polyhedron zones.
1263
+
1264
+ Raises:
1265
+ NotImplementedError: Always. Write to a ``.plt`` or ``.dat`` file instead,
1266
+ see :meth:`TecplotPltWriter.write_poly_zone`.
1267
+ """
1268
+ raise NotImplementedError(
1269
+ "Polygon and polyhedron zones are not yet supported in SZPLT files by the "
1270
+ "TecIO library. Write a .plt or .dat file instead."
1271
+ )
tecio/_utils.py CHANGED
@@ -33,8 +33,25 @@ _TEC_EXECUTABLE_ALIASES = (
33
33
  _VERSION_REGEX = re.compile(r"(20\d{2})\s*[Rr]\s*(\d+)")
34
34
 
35
35
 
36
- def _run_which(cmd: str) -> str | None:
37
- """Run `which cmd` explicitly as a fallback."""
36
+ def public_dir(obj: object) -> list[str]: # pragma: no cover
37
+ """Return ``dir(obj)`` without single underscore (private) names.
38
+
39
+ Dunder names are kept so that introspection tools keep working. Attribute access
40
+ is unaffected, the private names are only hidden from listings.
41
+ """
42
+ return [
43
+ name
44
+ for name in object.__dir__(obj)
45
+ if not name.startswith("_") or name.startswith("__")
46
+ ]
47
+
48
+
49
+ def _run_which(cmd: str) -> str | None: # pragma: no cover - environment-dependent
50
+ """Run `which cmd` explicitly as a fallback.
51
+
52
+ Returns:
53
+ str: Path of the executable, or ``None`` if it is not found.
54
+ """
38
55
  try:
39
56
  proc = subprocess.run(
40
57
  ["which", cmd],
@@ -50,8 +67,15 @@ def _run_which(cmd: str) -> str | None:
50
67
  return path if path else None
51
68
 
52
69
 
53
- def _find_tec_executable() -> str:
54
- """Locate Tecplot executable using multiple strategies."""
70
+ def _find_tec_executable() -> str: # pragma: no cover - environment-dependent
71
+ """Locate Tecplot executable using multiple strategies.
72
+
73
+ Returns:
74
+ str: Resolved path of the Tecplot executable.
75
+
76
+ Raises:
77
+ TecplotNotFoundError: If no Tecplot executable is found.
78
+ """
55
79
  # 1. shutil.which
56
80
  for name in _TEC_EXECUTABLE_ALIASES:
57
81
  exe = shutil.which(name)
@@ -104,8 +128,12 @@ def _find_tec_executable() -> str:
104
128
  )
105
129
 
106
130
 
107
- def _extract_version_from_path(path: str) -> str | None:
108
- """Extract Tecplot version YYYYR# from a filesystem path."""
131
+ def _extract_version_from_path(path: str) -> str | None: # pragma: no cover
132
+ """Extract Tecplot version YYYYR# from a filesystem path.
133
+
134
+ Returns:
135
+ str: Tecplot install version string, or ``None`` if the path has no version.
136
+ """
109
137
  match = _VERSION_REGEX.search(path)
110
138
  if match:
111
139
  year, release = match.groups()
@@ -113,8 +141,12 @@ def _extract_version_from_path(path: str) -> str | None:
113
141
  return None
114
142
 
115
143
 
116
- def _extract_version_from_executable(exe_path: str) -> str | None:
117
- """Ask Tecplot executable for its version."""
144
+ def _extract_version_from_executable(exe_path: str) -> str | None: # pragma: no cover
145
+ """Ask Tecplot executable for its version.
146
+
147
+ Returns:
148
+ str: Tecplot install version string, or ``None`` if it cannot be determined.
149
+ """
118
150
  try:
119
151
  proc = subprocess.run(
120
152
  [exe_path, "-v"],
@@ -134,16 +166,22 @@ def _extract_version_from_executable(exe_path: str) -> str | None:
134
166
  return None
135
167
 
136
168
 
137
- def get_tec_exe() -> str:
169
+ def get_tec_exe() -> str: # pragma: no cover - environment-dependent
138
170
  """Return absolute path to Tecplot executable."""
139
171
  return _find_tec_executable()
140
172
 
141
173
 
142
- def get_tec_bin() -> str:
174
+ def get_tec_bin() -> str: # pragma: no cover - environment-dependent
143
175
  """Return Tecplot bin directory.
144
176
 
145
177
  - macOS: Contents/Frameworks
146
178
  - Linux: directory containing the executable
179
+
180
+ Returns:
181
+ str: Path of the bin directory.
182
+
183
+ Raises:
184
+ TecplotNotFoundError: If the application or its directories are not found.
147
185
  """
148
186
  exe = get_tec_exe()
149
187
 
@@ -176,13 +214,19 @@ def get_tec_bin() -> str:
176
214
  return bin_dir
177
215
 
178
216
 
179
- def get_tecio_lib() -> str:
217
+ def get_tecio_lib() -> str: # pragma: no cover - environment-dependent
180
218
  """Return full path to the TecIO shared library.
181
219
 
182
220
  Search order:
183
221
  1. TECIO_LIB environment variable
184
222
  2. Local project build directories (CI/dev)
185
223
  3. Installed Tecplot distribution
224
+
225
+ Returns:
226
+ str: Path of the shared library.
227
+
228
+ Raises:
229
+ TecplotNotFoundError: If the library cannot be found.
186
230
  """
187
231
  libname = "libtecio.dylib" if platform.system() == "Darwin" else "libtecio.so"
188
232
 
@@ -301,6 +345,9 @@ def requires_symbol(
301
345
  here directly, so this stays free of any dependency
302
346
  on the module defining that exception (e.g.
303
347
  :mod:`tecio.libtecio`, which imports this function).
348
+
349
+ Returns:
350
+ Callable: Decorator function.
304
351
  """
305
352
 
306
353
  def decorator(func: _F) -> _F:
@@ -327,13 +374,20 @@ def requires_symbol(
327
374
  "this symbol."
328
375
  )
329
376
 
330
- return unavailable_func # ty: ignore[invalid-return-type]
377
+ return unavailable_func # ty: ignore[invalid-explicit-return]
331
378
 
332
379
  return decorator
333
380
 
334
381
 
335
382
  def get_tec_version() -> str:
336
- """Return Tecplot version formatted as YYYYR#."""
383
+ """Return Tecplot version formatted as YYYYR#.
384
+
385
+ Returns:
386
+ str: Tecplot install version string, for example ``"2025R1"``.
387
+
388
+ Raises:
389
+ TecplotNotFoundError: If the version cannot be determined.
390
+ """
337
391
  exe = get_tec_exe()
338
392
 
339
393
  # 1. From executable path
@@ -362,8 +416,17 @@ def get_tec_version() -> str:
362
416
  def convert_to_szl(
363
417
  input_path: str | os.PathLike,
364
418
  output_path: str | os.PathLike | None = None,
365
- ) -> Path:
366
- """Convert a Tecplot data file to SZL (``.szplt``) format from the command line."""
419
+ ) -> Path: # pragma: no cover
420
+ """Convert a Tecplot data file to SZL (``.szplt``) format from the command line.
421
+
422
+ Returns:
423
+ Path of the converted file.
424
+
425
+ Raises:
426
+ FileNotFoundError: If *input_path* does not exist.
427
+ TecplotConversionError: If Tecplot fails to launch, fails, or does not create
428
+ the file.
429
+ """
367
430
  input_path = Path(input_path).resolve()
368
431
  if not input_path.is_file():
369
432
  raise FileNotFoundError(f"Input file not found: {input_path}")