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

tecio/__init__.py

@@ -9,9 +9,22 @@ from importlib import metadata
 try:
     __version__ = metadata.version("tecio")
 except metadata.PackageNotFoundError:
-    __version__ = "0.3.0"
+    __version__ = "0.3.2"
 
 from . import cli, libtecio
+from ._constants import (
+    Boolean,
+    DataPacking,
+    DataType,
+    Debug,
+    FaceNeighborMode,
+    FeCellShape,
+    FileFormat,
+    FileType,
+    ValueLocation,
+    VarStatus,
+    ZoneType,
+)
 from ._containers import VariableList, ZoneList
 from ._dat_read import TecplotDatReader
 from ._dat_write import TecplotDatWriter
@@ -33,11 +46,11 @@ from ._writer import TecplotWriter
 # Ensure these display as their canonical public name in docs and help(),
 # rather than the private module they're actually defined in.
 open.__module__ = "tecio"
-AppendWrite.__module__ = "tecio"
-AppendReadWrite.__module__ = "tecio"
-ZoneList.__module__ = "tecio"
-VariableList.__module__ = "tecio"
 for _cls in (
+    AppendWrite,
+    AppendReadWrite,
+    ZoneList,
+    VariableList,
     TecplotReader,
     TecplotZoneReader,
     TecplotOrderedZoneReader,
@@ -51,6 +64,17 @@ for _cls in (
     TecplotSzlWriter,
     TecplotPltWriter,
     TecplotDatWriter,
+    Boolean,
+    DataPacking,
+    DataType,
+    Debug,
+    FaceNeighborMode,
+    FeCellShape,
+    FileFormat,
+    FileType,
+    ValueLocation,
+    VarStatus,
+    ZoneType,
 ):
     _cls.__module__ = "tecio"
 del _cls
@@ -76,5 +100,32 @@ __all__ = [
     "TecplotSzlWriter",
     "TecplotPltWriter",
     "TecplotDatWriter",
-    "__version__",
+    "Boolean",
+    "DataPacking",
+    "DataType",
+    "Debug",
+    "FaceNeighborMode",
+    "FeCellShape",
+    "FileFormat",
+    "FileType",
+    "ValueLocation",
+    "VarStatus",
+    "ZoneType",
 ]
+
+_STANDARD_MODULE_ATTRIBUTES = (
+    "__name__",
+    "__file__",
+    "__path__",
+    "__doc__",
+    "__all__",
+    "__package__",
+    "__version__",
+    "__cached__",
+    "__spec__",
+)
+
+
+# Only public API visible to user
+def __dir__() -> list:
+    return sorted((*_STANDARD_MODULE_ATTRIBUTES, *__all__))

tecio/_constants.py

@@ -0,0 +1,345 @@
+"""Tecplot meaningful integers.
+
+The TecIO library often uses integers with special meanings (zone types, data types,
+data locations). The same values are used both for writing (``tec*142`` functions) and
+for SZL reading and writing (``tec_*`` functions). Where available, the equivalent
+keyword used in Tecplot ASCII files is exposed as a class property, returning the
+corresponding int value.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+__all__ = [
+    "Boolean",
+    "DataPacking",
+    "DataType",
+    "Debug",
+    "FaceNeighborMode",
+    "FeCellShape",
+    "FileFormat",
+    "FileType",
+    "ValueLocation",
+    "VarStatus",
+    "ZoneType",
+]
+
+
+class FileFormat(Enum):
+    """Binary data format selector.
+
+    .. list-table::
+       :header-rows: 1
+       :widths: 25 10 65
+
+       * - Attribute
+         - Value
+         - Description
+       * - ``PLT``
+         - ``0``
+         - Classic PLT binary format.
+       * - ``SZPLT``
+         - ``1``
+         - SZL subzone-loadable format.
+    """
+
+    PLT = 0
+    SZPLT = 1
+
+
+class FileType(Enum):
+    """Tecplot file type.
+
+    .. list-table::
+       :header-rows: 1
+       :widths: 25 10 65
+
+       * - Attribute
+         - Value
+         - Description
+       * - ``FULL``
+         - ``0``
+         - Contains both grid and solution data.
+       * - ``GRID``
+         - ``1``
+         - Grid coordinates only.
+       * - ``SOLUTION``
+         - ``2``
+         - Solution variables only.
+    """
+
+    FULL = 0
+    GRID = 1
+    SOLUTION = 2
+
+
+class ZoneType(Enum):
+    """Tecplot zone type.
+
+    .. list-table::
+       :header-rows: 1
+       :widths: 25 10 65
+
+       * - Attribute
+         - Value
+         - Description
+       * - ``ORDERED``
+         - ``0``
+         - Structured IJK grid.
+       * - ``FELINESEG``
+         - ``1``
+         - Finite-element line segments.
+       * - ``FETRIANGLE``
+         - ``2``
+         - Finite-element triangles.
+       * - ``FEQUADRILATERAL``
+         - ``3``
+         - Finite-element quadrilaterals.
+       * - ``FETETRAHEDRON``
+         - ``4``
+         - Finite-element tetrahedra.
+       * - ``FEBRICK``
+         - ``5``
+         - Finite-element hexahedra.
+       * - ``FEPOLYGON``
+         - ``6``
+         - Finite-element polygons (face-based).
+       * - ``FEPOLYHEDRON``
+         - ``7``
+         - Finite-element polyhedra (face-based).
+       * - ``FEMIXED``
+         - ``8``
+         - Mixed finite-element types.
+    """
+
+    ORDERED = 0
+    FELINESEG = 1
+    FETRIANGLE = 2
+    FEQUADRILATERAL = 3
+    FETETRAHEDRON = 4
+    FEBRICK = 5
+    FEPOLYGON = 6
+    FEPOLYHEDRON = 7
+    FEMIXED = 8
+
+
+class FeCellShape(Enum):
+    """Unstructured cell shape category.
+
+    .. list-table::
+       :header-rows: 1
+       :widths: 25 10 65
+
+       * - Attribute
+         - Value
+         - Description
+       * - ``BAR``
+         - ``0``
+         - 2D two-node element.
+       * - ``TRIANGLE``
+         - ``1``
+         - 2D three-node element.
+       * - ``QUADRILATERAL``
+         - ``2``
+         - 2D four-node element.
+       * - ``TETRAHEDRON``
+         - ``3``
+         - 3D four-node element.
+       * - ``HEXAHEDRON``
+         - ``4``
+         - 3D six-node element.
+       * - ``PYRAMID``
+         - ``5``
+         - 3D five-node element.
+       * - ``PRISM``
+         - ``6``
+         - 3D eight-node element.
+    """
+
+    BAR = 0
+    TRIANGLE = 1
+    QUADRILATERAL = 2
+    TETRAHEDRON = 3
+    HEXAHEDRON = 4
+    PYRAMID = 5
+    PRISM = 6
+
+
+class FaceNeighborMode(Enum):
+    """Boundary face-sharing mode between zones.
+
+    .. list-table::
+       :header-rows: 1
+       :widths: 35 10 55
+
+       * - Attribute
+         - Value
+         - Description
+       * - ``LOCAL_ONE_TO_ONE``
+         - ``0``
+         - Each face has at most one local neighbor.
+       * - ``LOCAL_ONE_TO_MANY``
+         - ``1``
+         - Each face may have multiple local neighbors (hanging nodes).
+       * - ``GLOBAL_ONE_TO_ONE``
+         - ``2``
+         - Each face has at most one neighbor in any zone.
+       * - ``GLOBAL_ONE_TO_MANY``
+         - ``3``
+         - Each face may have multiple neighbors in any zone (hanging nodes).
+    """
+
+    LOCAL_ONE_TO_ONE = 0
+    LOCAL_ONE_TO_MANY = 1
+    GLOBAL_ONE_TO_ONE = 2
+    GLOBAL_ONE_TO_MANY = 3
+
+
+class ValueLocation(Enum):
+    """Data value location within a cell.
+
+    .. list-table::
+       :header-rows: 1
+       :widths: 25 10 65
+
+       * - Attribute
+         - Value
+         - Description
+       * - ``CELL_CENTERED``
+         - ``0``
+         - Values stored at cell centres.
+       * - ``NODAL``
+         - ``1``
+         - Values stored at grid nodes.
+    """
+
+    CELL_CENTERED = 0
+    NODAL = 1
+
+
+class DataPacking(Enum):
+    """Zone data packing order for ASCII (``.dat``) files.
+
+    Controls whether data is laid out variable-by-variable or point-by-point
+    in the ASCII file. The ``DATAPACKING`` keyword in a zone header takes one
+    of these two values.
+
+    .. list-table::
+       :header-rows: 1
+       :widths: 25 10 65
+
+       * - Attribute
+         - Value
+         - Description
+       * - ``POINT``
+         - ``0``
+         - One row per node/cell containing all variable values.
+       * - ``BLOCK``
+         - ``1``
+         - One contiguous block per variable containing all node/cell values.
+           Tecplot default; faster for variable-at-a-time access patterns.
+    """
+
+    POINT = 0
+    BLOCK = 1
+
+
+class DataType(Enum):
+    """On-disk storage type for variable data.
+
+    .. list-table::
+       :header-rows: 1
+       :widths: 25 10 65
+
+       * - Attribute
+         - Value
+         - Description
+       * - ``FLOAT``
+         - ``1``
+         - 32-bit IEEE floating point.
+       * - ``DOUBLE``
+         - ``2``
+         - 64-bit IEEE floating point.
+       * - ``INT32``
+         - ``3``
+         - 32-bit signed integer.
+       * - ``INT16``
+         - ``4``
+         - 16-bit signed integer.
+       * - ``BYTE``
+         - ``5``
+         - 8-bit unsigned integer.
+    """
+
+    FLOAT = 1
+    DOUBLE = 2
+    INT32 = 3
+    INT16 = 4
+    BYTE = 5
+
+
+class VarStatus(Enum):
+    """Variable active/passive flag.
+
+    .. list-table::
+       :header-rows: 1
+       :widths: 25 10 65
+
+       * - Attribute
+         - Value
+         - Description
+       * - ``ACTIVE``
+         - ``0``
+         - Variable has data in this zone.
+       * - ``PASSIVE``
+         - ``1``
+         - Variable has no data in this zone.
+    """
+
+    ACTIVE = 0
+    PASSIVE = 1
+
+
+class Boolean(Enum):
+    """Boolean flag for C function arguments.
+
+    .. list-table::
+       :header-rows: 1
+       :widths: 25 10 65
+
+       * - Attribute
+         - Value
+         - Description
+       * - ``FALSE``
+         - ``0``
+         - Logical false.
+       * - ``TRUE``
+         - ``1``
+         - Logical true.
+    """
+
+    FALSE = 0
+    TRUE = 1
+
+
+class Debug(Enum):
+    """Debug flag for C function arguments.
+
+    .. list-table::
+       :header-rows: 1
+       :widths: 25 10 65
+
+       * - Attribute
+         - Value
+         - Description
+       * - ``FALSE``
+         - ``0``
+         - Debug output disabled.
+       * - ``TRUE``
+         - ``1``
+         - Debug output enabled.
+    """
+
+    FALSE = 0
+    TRUE = 1

tecio/_containers.py

@@ -1,35 +1,35 @@
 """Index- and name-based container types for Tecplot data collections.
 
-These containers are shared by the ``tecio`` readers: ``Read.zone`` returns a
-:class:`ZoneList` of ``ReadZone`` and ``ReadZone.variable`` returns a
+These containers are shared by the ``tecio`` readers: ``Read.zones`` returns a
+:class:`ZoneList` of ``ReadZone`` and ``ReadZone.variables`` returns a
 :class:`VariableList` of ``ReadVariable`` for every supported format (SZL, PLT, DAT).
-They depend only on small structural protocols (``.name`` for variables, ``.variable``
+They depend only on small structural protocols (``.name`` for variables, ``.variables``
 for zones) so they import nothing from either hierarchy and cannot introduce a circular
 dependency.
 
 Access model:
 
-    reader.zone                  # ZoneList
-    reader.zone[0]               # ReadZone            (element)
-    reader.zone[1:4]             # ZoneList            (sub-collection, same kind)
-    reader.zone[0].variable      # VariableList
-    reader.zone[0].variable["x"] # ReadVariable        (object: .values, .is_passive)
-    reader.zone[0].variable[2]   # ReadVariable        (0-based index)
+    reader.zones                  # ZoneList
+    reader.zones[0]               # ReadZone            (element)
+    reader.zones[1:4]             # ZoneList            (sub-collection, same kind)
+    reader.zones[0].variables      # VariableList
+    reader.zones[0].variables["x"] # ReadVariable        (object: .values, .is_passive)
+    reader.zones[0].variables[2]   # ReadVariable        (0-based index)
 
 Subscripting always returns an element or a sub-collection *of the same kind* (never a
 raw array). The underlying NumPy data is pulled with ``get_array`` on a single zone,
 which mirrors the pandas ``df[...]`` split: a scalar key returns one array, a list of
 names returns a tuple of arrays (for unpacking)::
 
-    p = reader.zone[0].get_array("p")  # ndarray | None
-    p = reader.zone[0].get_array(2)  # ndarray | None  (0-based index)
-    x, y, z = reader.zone[0].get_array(["x", "y", "z"])  # tuple, one per name
+    p = reader.zones[0].get_array("p")  # ndarray | None
+    p = reader.zones[0].get_array(2)  # ndarray | None  (0-based index)
+    x, y, z = reader.zones[0].get_array(["x", "y", "z"])  # tuple, one per name
 
 There is deliberately **no** cross-zone array accessor. To pull one variable across
 many zones (e.g. a transient sequence), iterate explicitly so the outer axis is owned by
 your code, and stack only when you know the result is rectangular::
 
-    seq = [z.get_array("p") for z in reader.zone]  # list[ndarray | None]
+    seq = [z.get_array("p") for z in reader.zones]  # list[ndarray | None]
     stack = np.stack(seq)  # only if shapes all match
 
 Name lookup is exact and case-sensitive throughout, so distinct variables such
@@ -78,7 +78,7 @@ class _HasVariableList(Protocol):
     """A zone element exposing a name/index-addressable variable container."""
 
     @property
-    def variable(self) -> VariableList[Any]: ...
+    def variables(self) -> VariableList[Any]: ...
 
 
 _VarT = TypeVar("_VarT", bound=_HasName)
@@ -137,7 +137,7 @@ def select_variable_arrays(
 class VariableList(Generic[_VarT]):
     """Read-only sequence of variables with positional *and* named access.
 
-    Drop-in for the ``list`` previously returned by ``ReadZone.variable``:
+    Drop-in for the ``list`` previously returned by ``ReadZone.variables``:
     iteration, ``len()``, and integer indexing are unchanged. A string key
     resolves a variable by its exact, case-sensitive name.
 
@@ -208,7 +208,7 @@ class VariableList(Generic[_VarT]):
         """Return the variable names in dataset order."""
         return [var.name for var in self._items]
 
-    def __repr__(self) -> str:
+    def __repr__(self) -> str:  # pragma: no cover
         n = len(self._items)
         if n == 0:
             return "VariableList([])"
@@ -229,16 +229,16 @@ class VariableList(Generic[_VarT]):
 class ZoneList(Generic[_ZoneT]):
     """Read-only sequence of zones: positional access and slicing only.
 
-    Drop-in for the ``list`` previously returned by ``Read.zone``: iteration, ``len()``,
-    and integer indexing are unchanged. Slicing returns another :class:`ZoneList` (not a
-    plain ``list``) so navigation composes.
+    Drop-in for the ``list`` previously returned by ``Read.zones``: iteration,
+    ``len()``, and integer indexing are unchanged. Slicing returns another
+    :class:`ZoneList` (not a plain ``list``) so navigation composes.
 
     This container deliberately exposes **no** data-extraction method. Pulling one
     variable across many zones is an explicit loop over the zones, keeping the outer
     (zone) axis owned by the caller (see the module docs).
 
     Args:
-        zones: Ordered list of zone elements (each exposing ``.variable``).
+        zones: Ordered list of zone elements (each exposing ``.variables``).
     """
 
     __slots__ = ("_items",)
@@ -277,7 +277,7 @@ class ZoneList(Generic[_ZoneT]):
             return ZoneList(self._items[key])
         return self._items[key]
 
-    def __repr__(self) -> str:
+    def __repr__(self) -> str:  # pragma: no cover
         n = len(self._items)
         if n == 0:
             return "ZoneList([])"