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

tecio/_io.py

@@ -29,27 +29,32 @@ Note:
     approach because PLT and SZL are sequential binary formats with no in-place editing
     capability.
 
+Note:
+    Legacy PLT files (v75, v107, v111) are read-only, so ``"a"`` and ``"a+"`` raise
+    :exc:`ValueError` for them.
+
 Note:
     FEPOLYGON and FEPOLYHEDRON zones are not copied during append operations because the
     ``Write`` API does not yet expose a poly-zone writer. A :exc:`NotImplementedError`
     is raised if such zones are encountered in the source file.
 """
 
+# ruff: noqa: A001 N806
+
 from __future__ import annotations
 
 import os
 import tempfile
 from pathlib import Path
-from typing import Any, Literal, overload
+from typing import Any, Literal, NamedTuple, overload
 
-import numpy as np
 import numpy.typing as npt
 
 from ._constants import FileType, ValueLocation, ZoneType
 from ._containers import ZoneList
-from ._dat_read import TecplotDatReader
+from ._dat_read import TecplotDatReader, _peek_dat_metadata
 from ._dat_write import TecplotDatWriter
-from ._plt_read import TecplotPltReader
+from ._plt_read import TecplotPltReader, _is_legacy_plt
 from ._plt_write import TecplotPltWriter
 from ._reader import (
     TecplotAuxDataReader,
@@ -88,6 +93,20 @@ _HANDLERS: dict[str, dict[str, Any]] = {
         "a": None,
         "a+": None,
     },
+    ".bbin": {
+        "r": TecplotPltReader,
+        "w": TecplotPltWriter,
+        "x": None,
+        "a": None,
+        "a+": None,
+    },
+    ".bbin8": {
+        "r": TecplotPltReader,
+        "w": TecplotPltWriter,
+        "x": None,
+        "a": None,
+        "a+": None,
+    },
     ".dat": {
         "r": TecplotDatReader,
         "w": TecplotDatWriter,
@@ -104,6 +123,9 @@ _HANDLERS: dict[str, dict[str, Any]] = {
     },
 }
 
+# Extensions handled by the PLT reader, which may hold a legacy (read-only) version.
+_PLT_EXTS: frozenset[str] = frozenset({".plt", ".bin", ".bbin", ".bbin8"})
+
 # FE zone types that the Write API supports for zone copying.
 _FE_SIMPLE: frozenset[ZoneType] = frozenset({
     ZoneType.FELINESEG,
@@ -156,62 +178,43 @@ def _copy_zones(reader: TecplotReader, writer: TecplotWriter) -> None:
                 "copying is not supported by the Write API yet."
             )
 
-        # Collect per-variable metadata and data arrays.
+        # Collect per-variable metadata and data arrays
         data: list[npt.NDArray] = []
         value_locations: list[ValueLocation] = []
-        passive_vars: list[bool] = []
-        var_sharing: list[int] = []
+        passive_vars: set[str] = set()
+        var_sharing: dict[str, int] = {}
 
         for var in zone.variables:
-            passive_vars.append(var.is_passive())
-            sv = var.shared_zone  # None, or the 1-based source-zone index shared from
-            # Write API expects 0 = no sharing, positive = 1-based zone source.
-            var_sharing.append((sv) if sv is not None else 0)
-            value_locations.append(var.value_location)
-
-            if var.is_passive() or sv is not None:
-                # No array needed; append a placeholder so indices stay aligned.
-                data.append(np.array([], dtype=np.float32))
+            sv = var.shared_zone  # None, or the 0-based source-zone index shared from
+            if var.is_passive():
+                passive_vars.add(var.name)
+            elif sv is not None:
+                var_sharing[var.name] = sv
             else:
                 data.append(var.values)  # ty: ignore[invalid-argument-type]
-
-        # Strip placeholder arrays — Write infers active variables from passive_vars /
-        # var_sharing.
-        active_data = [
-            arr
-            for arr, is_p, sv in zip(data, passive_vars, var_sharing, strict=False)
-            if not is_p and sv == 0
-        ]
-        active_locs = [
-            loc
-            for loc, is_p, sv in zip(
-                value_locations, passive_vars, var_sharing, strict=False
-            )
-            if not is_p and sv == 0
-        ]
-
-        common_kw: dict[str, Any] = dict(
-            title=zone.title,
-            value_locations=active_locs,
-            passive_vars=passive_vars,
-            var_sharing=var_sharing,
-            solution_time=zone.solution_time,
-            strand_id=zone.strand_id,
-            aux=dict(zone.auxdata.items()) or None,
-        )
+                value_locations.append(var.value_location)
+
+        common_kw: dict[str, Any] = {
+            "title": zone.title,
+            "value_locations": value_locations,
+            "passive_vars": passive_vars,
+            "var_sharing": var_sharing,
+            "solution_time": zone.solution_time,
+            "strand_id": zone.strand_id,
+            "aux": dict(zone.auxdata.items()) or None,
+        }
 
         if isinstance(zone, TecplotOrderedZoneReader):
-            writer.write_ordered_zone(data=active_data, **common_kw)
+            writer.write_ordered_zone(data=data, **common_kw)
         elif isinstance(zone, TecplotFEZoneReader):
             # Forward connectivity sharing: when shared, pass ``con_sharing`` and omit
             # the node map so the writer derives the node/cell counts from the source
             # zone; otherwise write this zone's own node map.
-            cv = zone.shared_connectivity  # None, or 1-based source-zone index
-            con_sharing = cv if cv is not None else 0
+            con_sharing = zone.shared_connectivity  # None, or 0-based source-zone index
             writer.write_fe_zone(
                 zone_type=zone.zone_type,
-                data=active_data,
-                node_map=None if con_sharing else zone.node_map,
+                data=data,
+                node_map=None if con_sharing is not None else zone.node_map,
                 con_sharing=con_sharing,
                 **common_kw,
             )
@@ -301,14 +304,15 @@ class AppendWrite:
             value_locations (Sequence[ValueLocation] | None): Per-variable
                 :class:`~tecio.libtecio.ValueLocation` for active variables. Defaults
                 to all :attr:`~tecio.libtecio.ValueLocation.NODAL`.
-            passive_vars (Sequence[bool | int] | None): Per-variable passive flag for
-                the **full** variable list (length = total variables in the file, not
-                just active ones). Defaults to all ``False``.
-            var_sharing (Sequence[int] | None): Per-variable share-from zone index
-                (1-based, counting all zones including those copied from the original
-                file).  ``0`` = no sharing. Defaults to all ``0``. Sharing grid
-                coordinates from zone 1 is a common pattern for transient data to avoid
-                duplicating large arrays.
+            passive_vars (list | tuple | set | None): Variables to mark passive: a list,
+                tuple, or set of variable names, or of 0-based indices. Defaults to all
+                active.
+            var_sharing (dict[str | int, int] | None): Variables to share from another
+                zone: a ``{variable: source zone}`` mapping (name or 0-based index to
+                0-based zone index, counting all zones including those copied from the
+                original file). Defaults to no sharing. Sharing grid coordinates from
+                zone 0 is a common pattern for transient data to avoid duplicating large
+                arrays.
             solution_time (float): Solution time for transient data. Defaults to
                 ``0.0``.
             strand_id (int): Strand ID grouping related time steps. Zones with the same
@@ -317,13 +321,11 @@ class AppendWrite:
                 pairs. Defaults to ``None``.
 
         Example:
-            Append a time step, sharing the grid from zone 1:
+            Append a time step, sharing the grid from zone 0:
 
-            >>> n = len(tec.variables)  # e.g. ["x", "y", "pressure"]
             >>> tec.write_ordered_zone(
             ...     data=[p_new],  # only the non-shared variable
-            ...     passive_vars=[False] * n,
-            ...     var_sharing=[1, 1, 0],  # x and y shared from zone 1
+            ...     var_sharing={"x": 0, "y": 0},
             ...     solution_time=5.0,
             ...     strand_id=1,
             ... )
@@ -350,19 +352,22 @@ class AppendWrite:
                 must have length ``num_nodes``; CELL_CENTERED arrays must have length
                 ``num_cells``. Both are inferred from ``node_map``.
             node_map (array-like | None): Integer array of shape ``(num_cells,
-                nodes_per_cell)`` with **1-based** node indices. ``num_nodes =
-                node_map.max()``. The 32- or 64-bit write path is chosen automatically.
+                nodes_per_cell)`` with 0-based node indices. ``num_nodes =
+                node_map.max() + 1``. The 32- or 64-bit write path is chosen
+                automatically.
             title (str | None): Zone title. Defaults to ``"FE_Zone_{n}"``.
             value_locations (Sequence[ValueLocation] | None): Per-variable value
                 location for active variables. Defaults to all
                 :attr:`~tecio.libtecio.ValueLocation.NODAL`.
-            passive_vars (Sequence[bool | int] | None): Per-variable passive flags for
-                the full variable list. Defaults to all ``False``.
-            var_sharing (Sequence[int] | None): Per-variable share-from zone index
-                (1-based).  ``0`` = no sharing. Defaults to all ``0``.
-            con_sharing (int): Zone index to share connectivity from (1-based).  ``0`` =
-                write connectivity directly. Cannot be used with GLOBAL face-neighbor
-                modes. Defaults to ``0``.
+            passive_vars (list | tuple | set | None): Variables to mark passive: a list,
+                tuple, or set of variable names, or of 0-based indices. Defaults to all
+                active.
+            var_sharing (dict[str | int, int] | None): Variables to share from another
+                zone: a ``{variable: source zone}`` mapping (name or 0-based index to
+                0-based zone index). Defaults to no sharing.
+            con_sharing (int | None): Zone index to share connectivity from (0-based).
+                ``None`` = write connectivity directly. Cannot be used with GLOBAL
+                face-neighbor modes. Defaults to ``None``.
             face_neighbors (array-like | None): Face-neighbor connectivity. When
                 provided, ``num_face_cons`` is set automatically.
             face_nbr_mode (FaceNeighborMode | None): Face-neighbor mode. Defaults to
@@ -402,7 +407,7 @@ class AppendWrite:
 
     @property
     def current_zone(self) -> int:
-        """Index of the most recently written zone (1-based)."""
+        """0-based index of the most recently written zone, -1 before any write."""
         return self._writer.current_zone
 
     # -- Close and finalise ------------------------------------------------------------
@@ -506,16 +511,16 @@ class AppendReadWrite(AppendWrite):
         return self._reader.num_auxdata_items
 
     @property
-    def var_auxdata(self) -> list[TecplotAuxDataReader | None]:
+    def var_auxdata(self) -> list[TecplotAuxDataReader]:
         """Per-variable auxiliary data list from the *original* file."""
         return self._reader.var_auxdata
 
     def get_var_auxdata(self, var_index: int) -> TecplotAuxDataReader:
-        """Return variable aux data for *var_index* (1-based)."""
+        """Return variable aux data for *var_index* (0-based)."""
         return self._reader.get_var_auxdata(var_index)
 
     def get_zone_auxdata(self, zone_index: int) -> TecplotAuxDataReader:
-        """Return zone aux data for *zone_index* (1-based)."""
+        """Return zone aux data for *zone_index* (0-based)."""
         return self._reader.get_zone_auxdata(zone_index)
 
 
@@ -546,6 +551,8 @@ def _open_append(
 
     Raises:
         FileNotFoundError: If *path* does not exist (nothing to append to).
+        ValueError: If *path* is a legacy PLT file (v75, v107, or v111), which is
+            read-only.
     """
     src = Path(path)
     if not src.exists():
@@ -553,6 +560,11 @@ def _open_append(
             f"Cannot append to '{src}': file does not exist.  "
             "Use mode='w' to create a new file."
         )
+    if ext in _PLT_EXTS and _is_legacy_plt(src):
+        raise ValueError(
+            f"Cannot append to '{src}': legacy PLT versions (v75, v107, v111) are "
+            "read-only. Open with mode='r', or convert to a current format first."
+        )
 
     ReadCls = _reader_for_ext(ext)
     WriteCls = _writer_for_ext(ext)
@@ -690,7 +702,7 @@ def open(
         path (str | os.PathLike): File path. Extension determines the format handler:
 
             - ``.szplt`` → :mod:`tecio.szl`
-            - ``.plt`` / ``.bin`` → :mod:`tecio.plt`
+            - ``.plt`` / ``.bin`` / ``.bbin`` / ``.bbin8`` → :mod:`tecio.plt`
             - ``.dat`` / ``.tec`` → :mod:`tecio.dat`
 
         mode (str): Access mode — mirrors Python's built-in :func:`open`:
@@ -706,6 +718,9 @@ def open(
             - ``'a+'`` -- Same as ``'a'`` but the returned handle also exposes the full
               read API populated from the original file.
 
+            Legacy PLT files (v75, v107, v111) can only be opened with ``'r'``;
+            ``'a'`` and ``'a+'`` raise :exc:`ValueError` for them.
+
         **kwargs: Forwarded to the underlying handler constructor. The accepted keyword
             arguments differ by mode — see the tables below.
 
@@ -755,7 +770,8 @@ def open(
         - ``'a+'`` → :class:`~tecio.AppendReadWrite`
 
     Raises:
-        ValueError: Unsupported file extension or unrecognised mode.
+        ValueError: Unsupported file extension, unrecognised mode, or ``'a'``/``'a+'``
+            on a legacy PLT file (v75, v107, v111).
         FileNotFoundError: ``'r'``, ``'a'``, or ``'a+'`` on a missing file.
         FileExistsError: ``'x'`` on an existing file.
         NotImplementedError: Append mode on a file containing FEPOLYGON or FEPOLYHEDRON
@@ -811,3 +827,252 @@ def open(
         raise ValueError(
             f"Unrecognised mode '{mode}'. Supported modes: 'r', 'w', 'x', 'a', 'a+'"
         )
+
+
+# --------------------------------------------------------------------------------------
+# Lightweight metadata queries
+# --------------------------------------------------------------------------------------
+
+
+def _validated_ext(path: str | os.PathLike) -> str:
+    """Return *path*'s lowercased extension, or raise if unsupported.
+
+    Example:
+        >>> _validated_ext("flow.szplt")
+        '.szplt'
+    """
+    ext = Path(path).suffix.lower()
+    if ext not in _HANDLERS:
+        raise ValueError(
+            f"Unsupported file extension: '{ext}'. Supported: {sorted(_HANDLERS)}"
+        )
+    return ext
+
+
+class ZoneSummary(NamedTuple):
+    """Per-zone metadata from a lightweight :func:`peek` query.
+
+    ``num_nodes``/``num_elements`` are ``None`` only for a DAT ordered zone whose header
+    omits I/J/K entirely (rare; relies on the reader inferring the point count from the
+    data itself, which a lightweight query never does). Every other case, and every
+    SZL/PLT zone, always has both.
+    """
+
+    title: str
+    zone_type: ZoneType
+    num_nodes: int | None
+    num_elements: int | None
+
+
+class FileSummary(NamedTuple):
+    """Whole-file metadata from :func:`peek`, with no variable data touched."""
+
+    title: str
+    file_type: FileType
+    variable_names: list[str]
+    zones: list[ZoneSummary]
+
+
+def get_variable_list(path: str | os.PathLike) -> list[str]:
+    """Return a file's variable names without reading any variable data.
+
+    For SZL and PLT this is already what a normal :func:`open` does, both formats
+    resolve dataset-level metadata (including variable names) up front without touching
+    data arrays, so this is a thin convenience wrapper for those two. DAT is different:
+    opening it normally always reads and numerically converts every value in the file,
+    so this function instead scans just the file's header text, several orders of
+    magnitude cheaper for a file with large data blocks.
+
+    Args:
+        path: Path to a ``.szplt``, ``.plt``/``.bin``, or ``.dat``/``.tec`` file.
+
+    Returns:
+        Variable names, in file order.
+
+    Raises:
+        FileNotFoundError: If *path* does not exist.
+        ValueError: If the file extension is not recognized.
+
+    Example:
+        >>> get_variable_list("flow.szplt")
+        ['x', 'y', 'z', 'pressure']
+    """
+    ext = _validated_ext(path)
+    if ext in (".dat", ".tec"):
+        return _peek_dat_metadata(path).variable_names
+    with _HANDLERS[ext]["r"](str(path)) as r:
+        return list(r.variables)
+
+
+def get_zone_list(path: str | os.PathLike) -> list[str]:
+    """Return a file's zone titles without reading any variable data.
+
+    Same rationale as :func:`get_variable_list`: already cheap for SZL and PLT
+    (constructing a zone reader only resolves scalar metadata, never variable data),
+    so this is a thin wrapper for those; for DAT, uses a dedicated scan that skips
+    every data and connectivity block entirely.
+
+    Args:
+        path: Path to a ``.szplt``, ``.plt``/``.bin``, or ``.dat``/``.tec`` file.
+
+    Returns:
+        Zone titles, in file order. An unnamed zone contributes an empty string, not
+        a placeholder like ``"Zone 1"``.
+
+    Raises:
+        FileNotFoundError: If *path* does not exist.
+        ValueError: If the file extension is not recognized.
+
+    Example:
+        >>> get_zone_list("flow.szplt")
+        ['FluidVolume', 'WingSurface']
+    """
+    ext = _validated_ext(path)
+    if ext in (".dat", ".tec"):
+        return [z.title for z in _peek_dat_metadata(path).zones]
+    with _HANDLERS[ext]["r"](str(path)) as r:
+        return [zone.title for zone in r.zones]
+
+
+def get_num_zones(path: str | os.PathLike) -> int:
+    """Return a file's zone count without reading any variable data.
+
+    Cheaper still than :func:`get_zone_list`: for SZL, a single scalar C-library
+    call with no zone objects constructed at all; for PLT and DAT, a count against
+    already-parsed/scanned header metadata.
+
+    Args:
+        path: Path to a ``.szplt``, ``.plt``/``.bin``, or ``.dat``/``.tec`` file.
+
+    Returns:
+        Number of zones in the file.
+
+    Raises:
+        FileNotFoundError: If *path* does not exist.
+        ValueError: If the file extension is not recognized.
+
+    Example:
+        >>> get_num_zones("flow.szplt")
+        2
+    """
+    ext = _validated_ext(path)
+    if ext in (".dat", ".tec"):
+        return len(_peek_dat_metadata(path).zones)
+    with _HANDLERS[ext]["r"](str(path)) as r:
+        return r.num_zones
+
+
+def get_num_variables(path: str | os.PathLike) -> int:
+    """Return a file's variable count without reading any variable data.
+
+    Cheaper still than :func:`get_variable_list`: for SZL, a single scalar
+    C-library call.
+
+    Args:
+        path: Path to a ``.szplt``, ``.plt``/``.bin``, or ``.dat``/``.tec`` file.
+
+    Returns:
+        Number of variables in the dataset.
+
+    Raises:
+        FileNotFoundError: If *path* does not exist.
+        ValueError: If the file extension is not recognized.
+
+    Example:
+        >>> get_num_variables("flow.szplt")
+        4
+    """
+    ext = _validated_ext(path)
+    if ext in (".dat", ".tec"):
+        return len(_peek_dat_metadata(path).variable_names)
+    with _HANDLERS[ext]["r"](str(path)) as r:
+        return r.num_vars
+
+
+def get_title(path: str | os.PathLike) -> str:
+    """Return a file's dataset title without reading any variable data.
+
+    Args:
+        path: Path to a ``.szplt``, ``.plt``/``.bin``, or ``.dat``/``.tec`` file.
+
+    Returns:
+        Dataset title string.
+
+    Raises:
+        FileNotFoundError: If *path* does not exist.
+        ValueError: If the file extension is not recognized.
+
+    Example:
+        >>> get_title("flow.szplt")
+        'Onera M6 wing'
+    """
+    ext = _validated_ext(path)
+    if ext in (".dat", ".tec"):
+        return _peek_dat_metadata(path).title
+    with _HANDLERS[ext]["r"](str(path)) as r:
+        return r.title
+
+
+def get_file_type(path: str | os.PathLike) -> FileType:
+    """Return a file's :class:`~tecio.FileType` without reading any variable data.
+
+    Args:
+        path: Path to a ``.szplt``, ``.plt``/``.bin``, or ``.dat``/``.tec`` file.
+
+    Returns:
+        The file type (``FULL``, ``GRID``, or ``SOLUTION``).
+
+    Raises:
+        FileNotFoundError: If *path* does not exist.
+        ValueError: If the file extension is not recognized.
+
+    Example:
+        >>> get_file_type("flow.szplt")
+        <FileType.FULL: 0>
+    """
+    ext = _validated_ext(path)
+    if ext in (".dat", ".tec"):
+        return _peek_dat_metadata(path).file_type
+    with _HANDLERS[ext]["r"](str(path)) as r:
+        return r.file_type
+
+
+def peek(path: str | os.PathLike) -> FileSummary:
+    """Return a file's title, file type, variable names, and per-zone summaries.
+
+    A single combined query covering everything :func:`get_variable_list`,
+    :func:`get_zone_list`, :func:`get_title`, and :func:`get_file_type` return, plus
+    each zone's type and size. For DAT, calling several of those functions
+    separately on the same file means scanning it that many times over, this
+    function scans once no matter how much of the summary is needed.
+
+    Args:
+        path: Path to a ``.szplt``, ``.plt``/``.bin``, or ``.dat``/``.tec`` file.
+
+    Returns:
+        Whole-file and per-zone metadata. See :class:`FileSummary` and
+        :class:`ZoneSummary`.
+
+    Raises:
+        FileNotFoundError: If *path* does not exist.
+        ValueError: If the file extension is not recognized.
+
+    Example:
+        >>> summary = peek("flow.szplt")
+        >>> [z.title for z in summary.zones]
+        ['FluidVolume', 'WingSurface']
+    """
+    ext = _validated_ext(path)
+    if ext in (".dat", ".tec"):
+        meta = _peek_dat_metadata(path)
+        zones = [
+            ZoneSummary(z.title, z.zone_type, z.num_nodes, z.num_elements)
+            for z in meta.zones
+        ]
+        return FileSummary(meta.title, meta.file_type, meta.variable_names, zones)
+    with _HANDLERS[ext]["r"](str(path)) as r:
+        zones = [
+            ZoneSummary(zone.title, zone.zone_type, zone.num_nodes, zone.num_elements)
+            for zone in r.zones
+        ]
+        return FileSummary(r.title, r.file_type, list(r.variables), zones)

tecio/_meta.py

@@ -56,7 +56,7 @@ class ZoneMeta:
     variable-type arrays of a ``TECZNE142`` zone header.
 
     Attributes:
-        index:                1-based zone index returned by the C library.
+        index:                0-based index of this zone within the dataset.
         title:                Zone title.
         zone_type:            The zone's :class:`~tecio.libtecio.ZoneType`.
         solution_time:        Solution time (``0.0`` for static zones).
@@ -72,8 +72,8 @@ class ZoneMeta:
                               else ``None`` if it has none.
         value_locations:      Per-variable value location, full dataset length.
         passive_vars:         Per-variable passive flags, full dataset length.
-        shared_vars:          Per-variable share-from zone index (1-based; ``0`` for not
-                              shared), full dataset length.
+        shared_vars:          Per-variable share-from zone index, or ``None`` for not
+                              shared, full dataset length.
         data_types:           Per-variable data type, full dataset length.
 
     """
@@ -93,7 +93,7 @@ class ZoneMeta:
     # Per-variable descriptors (length == dataset variable count).
     value_locations: tuple[ValueLocation, ...] = ()
     passive_vars: tuple[bool, ...] = ()
-    shared_vars: tuple[int, ...] = ()
+    shared_vars: tuple[int | None, ...] = ()
     data_types: tuple[DataType, ...] = ()
 
     @property
@@ -133,7 +133,7 @@ class WriterMeta:
                                header has been written (lazy-open).
         num_dataset_aux_items: Count of dataset-level aux items written.
         num_var_aux_items:     Total variable-level aux items written.
-        zones:                 Mapping of 1-based zone index to :class:`ZoneMeta`,
+        zones:                 Mapping of 0-based zone index to :class:`ZoneMeta`,
                                in write order.
     """
 
@@ -173,7 +173,7 @@ class WriterMeta:
         self.num_var_aux_items += count
 
     def record_zone(self, zone: ZoneMeta) -> None:
-        """Register a fully written zone by its 1-based index."""
+        """Register a fully written zone by its 0-based index."""
         self.zones[zone.index] = zone
 
     # -- Retrieval helpers ------------------------------------------------------------