Source code for tecio._io

"""Entry point for tecio such that IO capability can be called from a single function.

Supported modes mirror Python's built-in :func:`open`:

    ======  ============================================================================
    Mode    Behaviour
    ======  ============================================================================
    ``r``   Open existing file for reading. Raises :exc:`FileNotFoundError` if the file
            does not exist.
    ``w``   Open file for writing. Overwrites any existing file.
    ``x``   Exclusive creation — open for writing only if the file does **not** already
            exist. Raises :exc:`FileExistsError` otherwise.
    ``a``   Append — stream all zones from the existing file into a new temporary file,
            then continue writing new zones into that same file. On
            :meth:`~AppendWrite.close` the temporary file atomically replaces the
            original path. Returns an :class:`AppendWrite` object whose write API is
            identical to the format's ``Write`` class.
    ``a+``  Append-read — same streaming copy as ``a``, but the returned
            :class:`AppendReadWrite` object also exposes the full ``Read`` API populated
            from the *original* file so that existing zone data can be inspected while
            new zones are written.
    ======  ============================================================================

Note:
    ``"a"`` and ``"a+"`` work by reading the source file in full and re-writing it
    zone-by-zone into a temporary sibling file, then leaving the ``Write`` handle open
    for the caller to add further zones. On close the temporary file is atomically
    renamed over the original path (POSIX) or replaced (Windows). This is the only safe
    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.
"""

# ruff: noqa: A001 N806

from __future__ import annotations

import os
import tempfile
from pathlib import Path
from typing import Any, Literal, NamedTuple, overload

import numpy.typing as npt

from ._constants import FileType, ValueLocation, ZoneType
from ._containers import ZoneList
from ._dat_read import TecplotDatReader, _peek_dat_metadata
from ._dat_write import TecplotDatWriter
from ._plt_read import TecplotPltReader, _is_legacy_plt
from ._plt_write import TecplotPltWriter
from ._reader import (
    TecplotAuxDataReader,
    TecplotFEMixedZoneReader,
    TecplotFEZoneReader,
    TecplotOrderedZoneReader,
    TecplotPolyZoneReader,
    TecplotReader,
    TecplotZoneReader,
)
from ._szl_read import TecplotSzlReader
from ._szl_write import TecplotSzlWriter
from ._writer import TecplotWriter, poly_face_kwargs

# --------------------------------------------------------------------------------------
# Dispatch table
# --------------------------------------------------------------------------------------

_HANDLERS: dict[str, dict[str, Any]] = {
    ".szplt": {
        "r": TecplotSzlReader,
        "w": TecplotSzlWriter,
        "x": None,  # filled below after class definitions
        "a": None,
        "a+": None,
    },
    ".plt": {
        "r": TecplotPltReader,
        "w": TecplotPltWriter,
        "x": None,
        "a": None,
        "a+": None,
    },
    ".bin": {
        "r": TecplotPltReader,
        "w": TecplotPltWriter,
        "x": None,
        "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,
        "x": None,
        "a": None,
        "a+": None,
    },
    ".tec": {
        "r": TecplotDatReader,
        "w": TecplotDatWriter,
        "x": None,
        "a": None,
        "a+": None,
    },
}

# 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,
    ZoneType.FETRIANGLE,
    ZoneType.FEQUADRILATERAL,
    ZoneType.FETETRAHEDRON,
    ZoneType.FEBRICK,
})


# --------------------------------------------------------------------------------------
# Internal helpers
# --------------------------------------------------------------------------------------


def _reader_for_ext(ext: str) -> type[TecplotReader]:
    """Return the Read class for *ext*."""
    return _HANDLERS[ext]["r"]


def _writer_for_ext(ext: str) -> type:
    """Return the Write class for *ext*."""
    return _HANDLERS[ext]["w"]


def _copy_zones(reader: TecplotReader, writer: TecplotWriter) -> None:
    """Stream all zones from *reader* into the open *writer*.

    Each zone is copied variable-by-variable at its original data type and value
    location. Both variable sharing (``var_sharing``) and FE connectivity sharing
    (``con_sharing``) are preserved: a zone that shares its connectivity is
    re-emitted as a share rather than a duplicated node map.

    Args:
        reader: An already-opened ``Read`` instance.
        writer: An already-opened ``Write`` instance (file handle live).

    Raises:
        NotImplementedError: If a zone is neither ordered, finite-element, FEMIXED, nor
            poly, or if the writer's format cannot hold a FEMIXED zone (PLT and DAT).

    """
    for zone in reader.zones:
        # Collect per-variable metadata and data arrays
        data: list[npt.NDArray] = []
        value_locations: list[ValueLocation] = []
        passive_vars: set[str] = set()
        var_sharing: dict[str, int] = {}

        for var in zone.variables:
            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]
                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=data, **common_kw)
        elif isinstance(zone, TecplotPolyZoneReader):
            con_sharing = zone.shared_connectivity
            writer.write_poly_zone(
                zone_type=zone.zone_type,
                data=data,
                con_sharing=con_sharing,
                **({} if con_sharing is not None else poly_face_kwargs(zone)),
                **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.
            con_sharing = zone.shared_connectivity  # None, or 0-based source-zone index
            writer.write_fe_zone(
                zone_type=zone.zone_type,
                data=data,
                node_map=None if con_sharing is not None else zone.node_map,
                con_sharing=con_sharing,
                **common_kw,
            )
        elif isinstance(zone, TecplotFEMixedZoneReader):
            con_sharing = zone.shared_connectivity
            writer.write_femixed_zone(
                data=data,
                cell_shapes=None if con_sharing is not None else zone.section_shapes,
                node_maps=None if con_sharing is not None else zone.node_maps,
                con_sharing=con_sharing,
                **common_kw,
            )
        else:
            raise NotImplementedError(
                f"Zone '{zone.title}' is neither an ordered, classic FE, FEMIXED, nor "
                "poly zone, copying it is not supported by the Write API yet."
            )


# --------------------------------------------------------------------------------------
# AppendWrite — returned by open(..., "a")
# --------------------------------------------------------------------------------------


class AppendWrite:
    """Write handle returned by :func:`tecio.open` with ``mode='a'``.

    Appends new zones to an existing Tecplot file. Internally the existing file is
    stream-copied zone-by-zone into a temporary sibling file, and the write handle is
    left open past all copied zones so new zones can be appended. On :meth:`close` (or
    context-manager exit) the temporary file is atomically renamed over the original
    path — a POSIX rename on Unix, :func:`Path.replace` on Windows.

    The copy step preserves the original title, variable list, file type, all zone data,
    all zone metadata (strand, solution time, aux data), and variable sharing.
    Connectivity is copied for FE and poly zones.

    Do not instantiate this class directly — use :func:`tecio.open`.

    Example:
        >>> with tecio.open("flow.szplt", "a") as tec:
        ...     print(tec.variables)  # variable list from the existing file
        ...     print(tec.current_zone)  # number of zones already copied
        ...     tec.write_ordered_zone(
        ...         data=[x_new, y_new, p_new],
        ...         solution_time=10.0,
        ...         strand_id=1,
        ...     )
        >>> # flow.szplt now contains the original zones plus the new one

    """

    def __init__(
        self,
        original_path: str | os.PathLike,
        tmp_path: str | os.PathLike,
        writer: TecplotWriter,
    ) -> None:
        self._original = Path(original_path)
        self._tmp = Path(tmp_path)
        self._writer = writer
        self._closed = False

    # -- Context manager ---------------------------------------------------------------

    def __enter__(self) -> AppendWrite:
        return self

    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
        try:
            self.close()
        except Exception:
            if exc_type is None:
                raise

    # -- Write delegation --------------------------------------------------------------

[docs] def write_ordered_zone(self, *args: Any, **kwargs: Any) -> None: # noqa: D417 """Append a structured IJK-ordered zone. Delegates to the underlying format writer's ``write_ordered_zone`` (e.g. :meth:`tecio.TecplotWriter.write_ordered_zone`). All parameters from that method are accepted here with one exception: ``variables`` is not meaningful because the variable list is fixed at open time from the existing file. Args: data (Sequence[ndarray]): One NumPy array per **active** variable (non-passive, non-shared). Shape ``(imax[, jmax[, kmax]])`` is inferred automatically. Fortran (column-major) order is assumed. title (str | None): Zone title. Defaults to ``"IJK_Zone_{n}"``. value_locations (Sequence[ValueLocation] | None): Per-variable :class:`~tecio.libtecio.ValueLocation` for active variables. Defaults to all :attr:`~tecio.libtecio.ValueLocation.NODAL`. 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 strand ID animate together in Tecplot 360. Defaults to ``0`` (static). aux (dict[str, str] | None): Zone-level auxiliary data as ``{name: value}`` pairs. Defaults to ``None``. Example: Append a time step, sharing the grid from zone 0: >>> tec.write_ordered_zone( ... data=[p_new], # only the non-shared variable ... var_sharing={"x": 0, "y": 0}, ... solution_time=5.0, ... strand_id=1, ... ) """ self._writer.write_ordered_zone(*args, **kwargs)
[docs] def write_fe_zone(self, *args: Any, **kwargs: Any) -> None: # noqa: D417 """Append an unstructured finite-element zone. Delegates to the underlying format writer's ``write_fe_zone`` (e.g. :meth:`tecio.TecplotWriter.write_fe_zone`). The ``variables`` parameter is not meaningful here — the variable list is fixed from the existing file. FEPOLYGON and FEPOLYHEDRON are face-based, use :meth:`write_poly_zone`. Args: zone_type (ZoneType): Element topology. One of: :attr:`~tecio.libtecio.ZoneType.FELINESEG`, :attr:`~tecio.libtecio.ZoneType.FETRIANGLE`, :attr:`~tecio.libtecio.ZoneType.FEQUADRILATERAL`, :attr:`~tecio.libtecio.ZoneType.FETETRAHEDRON`, or :attr:`~tecio.libtecio.ZoneType.FEBRICK`. data (Sequence[ndarray]): One 1-D array per active variable. NODAL arrays 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 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 (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 :attr:`~tecio.libtecio.FaceNeighborMode.LOCAL_ONE_TO_ONE`. Ignored when ``face_neighbors`` is ``None``. solution_time (float): Solution time. Defaults to ``0.0``. strand_id (int): Strand ID. Defaults to ``0``. aux (dict[str, str] | None): Zone-level auxiliary data. Raises: ValueError: If ``zone_type`` is FEPOLYGON or FEPOLYHEDRON. """ self._writer.write_fe_zone(*args, **kwargs)
[docs] def write_femixed_zone(self, *args: Any, **kwargs: Any) -> None: # noqa: D417 """Append a FEMIXED (mixed finite-element) zone. Delegates to the underlying format writer's ``write_femixed_zone`` (e.g. :meth:`tecio.TecplotSzlWriter.write_femixed_zone`). The ``variables`` parameter is not meaningful here, the variable list is fixed from the existing file. All indices are 0-based. Args: data (Sequence[ndarray]): One 1-D array per active variable. NODAL arrays need ``num_nodes`` values, CELL_CENTERED arrays the total cell count over all sections, both inferred from the node maps. cell_shapes (Sequence[FeCellShape] | None): Cell shape of each section (1 to 16), all of one spatial dimension. node_maps (Sequence[array-like] | None): One ``(num_cells, nodes_per_cell)`` 0-based integer array per section. title (str | None): Zone title. Defaults to ``"FEMixed_Zone_{n}"``. value_locations (Sequence[ValueLocation] | None): Per-variable value location for active variables. Defaults to all NODAL. passive_vars (list | tuple | set | None): Variables to mark passive. var_sharing (dict[str | int, int] | None): ``{variable: source zone}``. con_sharing (int | None): FEMIXED zone to share connectivity from (0-based), in which case ``cell_shapes`` and ``node_maps`` must be omitted. solution_time (float): Solution time. Defaults to ``0.0``. strand_id (int): Strand ID. Defaults to ``0``. aux (dict[str, str] | None): Zone-level auxiliary data. Raises: NotImplementedError: For PLT and DAT files, which cannot hold FEMIXED zones. ValueError: On an inconsistent section layout. """ self._writer.write_femixed_zone(*args, **kwargs)
[docs] def write_poly_zone(self, *args: Any, **kwargs: Any) -> None: # noqa: D417 """Append a polygon or polyhedron (face-based) zone. Delegates to the underlying format writer's ``write_poly_zone`` (e.g. :meth:`tecio.TecplotPltWriter.write_poly_zone`). The ``variables`` parameter is not meaningful here, the variable list is fixed from the existing file. All indices are 0-based. Args: zone_type (ZoneType): :attr:`~tecio.libtecio.ZoneType.FEPOLYGON` or :attr:`~tecio.libtecio.ZoneType.FEPOLYHEDRON`. data (Sequence[ndarray]): One 1-D array per active variable. NODAL arrays need ``num_nodes`` values, CELL_CENTERED arrays ``num_elements``, both inferred from the face map. face_nodes (array-like | None): Flat node indices of all faces. face_node_counts (array-like | None): Nodes per face. Required for polyhedra, optional for polygons (always 2). face_left_elements (array-like | None): Element left of each face, ``-1`` for none, ``-(b + 2)`` for boundary face ``b``. face_right_elements (array-like | None): Element right of each face. boundary_connection_counts (array-like | None): Connections per boundary face. boundary_connection_elements (array-like | None): Flat neighbor elements. boundary_connection_zones (array-like | None): Flat zone of each neighbor. title (str | None): Zone title. Defaults to ``"Poly_Zone_{n}"``. value_locations (Sequence[ValueLocation] | None): Per-variable value location for active variables. Defaults to all NODAL. passive_vars (list | tuple | set | None): Variables to mark passive. var_sharing (dict[str | int, int] | None): ``{variable: source zone}``. con_sharing (int | None): Zone to share the face map from (0-based). solution_time (float): Solution time. Defaults to ``0.0``. strand_id (int): Strand ID. Defaults to ``0``. aux (dict[str, str] | None): Zone-level auxiliary data. Raises: NotImplementedError: For SZPLT files, which cannot hold poly zones. ValueError: On an inconsistent or out of range face map. """ self._writer.write_poly_zone(*args, **kwargs)
[docs] def add_auxdataset_dict(self, auxdict: dict[str, Any]) -> None: """Buffer dataset-level auxiliary data.""" self._writer.add_auxdataset_dict(auxdict)
[docs] def add_auxvar_dict(self, auxdict: dict[int, dict[str, Any]]) -> None: """Buffer variable-level auxiliary data.""" self._writer.add_auxvar_dict(auxdict)
[docs] def flush_aux(self) -> None: """Flush buffered auxiliary data to disk.""" self._writer.flush_aux()
# Expose title / variables / current_zone so callers can inspect state. @property def title(self) -> str: """Dataset title of the output file.""" return self._writer.title @property def variables(self) -> list[str] | None: """Variable name list of the output file.""" return self._writer.variables @property def current_zone(self) -> int: """0-based index of the most recently written zone, -1 before any write.""" return self._writer.current_zone # -- Close and finalise ------------------------------------------------------------
[docs] def close(self) -> None: """Finalise the temporary file and replace the original. Safe to call more than once. """ if self._closed: return self._closed = True self._writer.close() # Atomic replace: on POSIX this is a rename; on Windows replace() also works # across drives by falling back to copy+delete. self._tmp.replace(self._original)
# -------------------------------------------------------------------------------------- # AppendReadWrite — returned by open(..., "a+") # -------------------------------------------------------------------------------------- class AppendReadWrite(AppendWrite): """Read + write handle returned by :func:`tecio.open` with ``mode='a+'``. Inherits all write methods from :class:`AppendWrite` and additionally exposes the full read interface populated from the **original** file. The read data reflects the file as it existed before any new zones were appended — zones written during the current session are not visible via :attr:`zone` until the file is closed and re-opened. Useful when new zones depend on existing zone data — for example, computing a time-average over all previous time steps and writing it as an additional zone. Do not instantiate this class directly — use :func:`tecio.open`. Example: >>> with tecio.open("flow.szplt", "a+") as tec: ... # Read from all zones present before this session ... times = [tec.zones[i].solution_time for i in range(tec.num_zones)] ... p_avg = ( ... sum( ... tec.zones[i].variables["p"].values for i in range(tec.num_zones) ... ) ... / tec.num_zones ... ) ... ... # Append a new zone using the computed average ... x = tec.zones[0].variables["x"].values ... y = tec.zones[0].variables["y"].values ... tec.write_ordered_zone( ... data=[x, y, p_avg], ... title="Time-average", ... solution_time=max(times) + 1.0, ... strand_id=2, ... ) """ def __init__( self, original_path: str | os.PathLike, tmp_path: str | os.PathLike, writer: TecplotWriter, reader: TecplotReader, ) -> None: super().__init__(original_path, tmp_path, writer) self._reader = reader # -- Read delegation --------------------------------------------------------------- @property def file_type(self) -> FileType: """File type of the *original* file (FULL / GRID / SOLUTION).""" return self._reader.file_type @property def num_vars(self) -> int: """Number of variables in the *original* file.""" return self._reader.num_vars @property def num_zones(self) -> int: """Number of zones in the *original* file (before appending).""" return self._reader.num_zones @property def zones(self) -> ZoneList[TecplotZoneReader]: """Zone list from the *original* file.""" return self._reader.zones @property def auxdata(self) -> TecplotAuxDataReader: """Dataset-level auxiliary data from the *original* file.""" return self._reader.auxdata @property def num_auxdata_items(self) -> int: """Number of dataset-level aux data items in the *original* file.""" return self._reader.num_auxdata_items @property def var_auxdata(self) -> list[TecplotAuxDataReader]: """Per-variable auxiliary data list from the *original* file.""" return self._reader.var_auxdata
[docs] def get_var_auxdata(self, var_index: int) -> TecplotAuxDataReader: """Return variable aux data for *var_index* (0-based).""" return self._reader.get_var_auxdata(var_index)
[docs] def get_zone_auxdata(self, zone_index: int) -> TecplotAuxDataReader: """Return zone aux data for *zone_index* (0-based).""" return self._reader.get_zone_auxdata(zone_index)
# -------------------------------------------------------------------------------------- # _open_append — shared implementation for "a" and "a+" # -------------------------------------------------------------------------------------- def _open_append( path: str | os.PathLike, ext: str, read_write: bool, **writer_kwargs: Any, ) -> AppendWrite | AppendReadWrite: """Stream-copy *path* into a temp file and return an open write handle. Args: path: Original file path. ext: Lowercase file extension (e.g. ``".szplt"``). read_write: If ``True`` return :class:`AppendReadWrite`; otherwise :class:`AppendWrite`. **writer_kwargs: Extra keyword arguments forwarded to the ``Write`` constructor (e.g. ``title``, ``file_type``). Returns: An :class:`AppendWrite` or :class:`AppendReadWrite` instance with the ``Write`` handle already past all original zones and ready for new zones to be written. 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(): raise FileNotFoundError( 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) # Open the original file for reading. reader: TecplotReader = ReadCls(str(src)) # Resolve writer kwargs from the source file when not explicitly supplied. title: str = writer_kwargs.pop("title", reader.title) file_type: FileType = writer_kwargs.pop("file_type", reader.file_type) variables: list[str] = writer_kwargs.pop("variables", reader.variables) # Create a sibling temporary file so the rename at close stays on the same # filesystem (required for an atomic os.rename on most OSes). tmp_fd, tmp_path_str = tempfile.mkstemp( dir=src.parent, prefix=f".{src.stem}_append_", suffix=src.suffix, ) os.close(tmp_fd) # WriteCls will open it independently tmp_path = Path(tmp_path_str) try: writer = WriteCls( str(tmp_path), title=title, variables=variables, file_type=file_type, **writer_kwargs, ) # Replay all existing zones into the new file. _copy_zones(reader, writer) except Exception: # Close writer and clean up the temp file if anything goes wrong during the # copy. if writer is not None: try: writer.close() except Exception: pass tmp_path.unlink(missing_ok=True) raise if read_write: return AppendReadWrite( original_path=src, tmp_path=tmp_path, writer=writer, reader=reader, ) return AppendWrite( original_path=src, tmp_path=tmp_path, writer=writer, ) # -------------------------------------------------------------------------------------- # _open_exclusive — implementation for "x" # -------------------------------------------------------------------------------------- def _open_exclusive( path: str | os.PathLike, ext: str, **writer_kwargs: Any, ) -> TecplotWriter: """Open *path* for writing only if it does not already exist. Args: path: Target file path. ext: Lowercase file extension. **writer_kwargs: Forwarded to the ``Write`` constructor. Returns: A ``Write`` instance, identical to ``open(path, 'w')``. Raises: FileExistsError: If *path* already exists. """ target = Path(path) if target.exists(): raise FileExistsError( f"Cannot create '{target}': file already exists. " "Use mode='w' to overwrite or mode='a' to append." ) WriteCls = _writer_for_ext(ext) return WriteCls(str(target), **writer_kwargs) # ====================================================================================== # Public open() # ====================================================================================== # fmt: off @overload def open( path: str | os.PathLike, mode: Literal["r"], **kwargs: Any, ) -> TecplotReader: ... @overload def open( path: str | os.PathLike, mode: Literal["w"] | Literal["x"], **kwargs: Any, ) -> TecplotWriter: ... @overload def open( path: str | os.PathLike, mode: Literal["a"], **kwargs: Any, ) -> AppendWrite: ... @overload def open( path: str | os.PathLike, mode: Literal["a+"], **kwargs: Any, ) -> AppendReadWrite: ... # fmt: on def open( path: str | os.PathLike, mode: str = "r", **kwargs: Any, ) -> TecplotReader | TecplotWriter | AppendWrite | AppendReadWrite: """Open a Tecplot file for reading, writing, or appending. Selects the correct format handler from the file extension and returns the appropriate reader or writer. All handles are context managers. Args: path (str | os.PathLike): File path. Extension determines the format handler: - ``.szplt`` → :mod:`tecio.szl` - ``.plt`` / ``.bin`` / ``.bbin`` / ``.bbin8`` → :mod:`tecio.plt` - ``.dat`` / ``.tec`` → :mod:`tecio.dat` mode (str): Access mode — mirrors Python's built-in :func:`open`: - ``'r'`` -- Open Tecplot file for reading. - ``'w'`` -- Open Tecplot file for writing, truncating the file first. - ``'x'`` -- Open Tecplot file for exclusive creation, failing if the file already exists. - ``'a'`` -- Append new zones to an existing file. The file is stream-copied to a temporary file; on close the temporary atomically replaces the original. Raises :exc:`FileNotFoundError` if the file does not exist (use ``'w'`` to create a new file). - ``'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. Keyword Args (modes ``'r'``, ``'w'``, ``'x'``): Forwarded directly to the format's ``Read`` or ``Write`` constructor. For **reading** — no keyword arguments are accepted; all metadata is read from the file. For **writing** (``'w'`` and ``'x'``): .. list-table:: :header-rows: 1 :widths: 20 15 65 * - Keyword - Default - Description * - ``title`` - ``""`` - Dataset title string embedded in the file header. * - ``variables`` - ``None`` - Variable name list. For SZL and PLT this may be deferred to the first :meth:`~tecio.TecplotWriter.write_ordered_zone`, :meth:`~tecio.TecplotWriter.write_fe_zone`, :meth:`~tecio.TecplotWriter.write_femixed_zone`, or :meth:`~tecio.TecplotWriter.write_poly_zone` call. Required at open time for DAT. * - ``file_type`` - ``FileType.FULL`` - One of :attr:`~tecio.libtecio.FileType.FULL`, :attr:`~tecio.libtecio.FileType.GRID`, or :attr:`~tecio.libtecio.FileType.SOLUTION`. Keyword Args (modes ``'a'``, ``'a+'``): ``title``, ``variables``, and ``file_type`` default to the values read from the existing file. In most cases you should **not** pass these. Providing them will override the source file when written out. Returns: - ``'r'`` → :class:`~tecio.TecplotSzlReader`, :class:`~tecio.TecplotPltReader`, or :class:`~tecio.TecplotDatReader` (all share the :class:`~tecio.TecplotReader` interface) - ``'w'`` / ``'x'`` → :class:`~tecio.TecplotSzlWriter`, :class:`~tecio.TecplotPltWriter`, or :class:`~tecio.TecplotDatWriter` (all share the :class:`~tecio.TecplotWriter` interface) - ``'a'`` → :class:`~tecio.AppendWrite` - ``'a+'`` → :class:`~tecio.AppendReadWrite` Raises: 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. Examples: Read a file: >>> with tecio.open("flow.szplt") as tec: ... x = tec.zones[0].variables["x"].values Write a new file, deferring variable names to the first zone: >>> with tecio.open("out.szplt", "w", title="Run 1") as tec: ... tec.write_ordered_zone(data=[x, y, p], variables=["x", "y", "p"]) Append a new zone to an existing file: >>> with tecio.open("out.szplt", "a") as tec: ... tec.write_ordered_zone(data=[x2, y2, p2], solution_time=2.0) Append and read in the same session: >>> with tecio.open("out.szplt", "a+") as tec: ... prev_p = tec.zones[-1].variables["p"].values ... tec.write_ordered_zone(data=[x2, y2, prev_p * 0.9]) """ ext = Path(path).suffix.lower() if ext not in _HANDLERS: raise ValueError( f"Unsupported file extension: '{ext}'. Supported: {sorted(_HANDLERS)}" ) if mode == "r": ReadCls = _HANDLERS[ext]["r"] return ReadCls(str(path), **kwargs) elif mode == "w": WriteCls = _HANDLERS[ext]["w"] return WriteCls(str(path), **kwargs) elif mode == "x": return _open_exclusive(path, ext, **kwargs) elif mode == "a": return _open_append(path, ext, read_write=False, **kwargs) elif mode == "a+": return _open_append(path, ext, read_write=True, **kwargs) else: 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. Raises: ValueError: If the extension is not supported. 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)