API Reference#

tecio is designed around a single entry point, tecio.open(), which opens a Tecplot file for reading, writing, or appending and returns the appropriate handler based on the file extension. In most cases you will not need to instantiate tecio.szl.Read, tecio.szl.Write, or any other class directly; tecio.open() selects and returns the correct one for you.

Importing#

For the tecio.libtecio enums and low-level functions, either of the following styles is acceptable, both are explicit enough to be readable:

# Import the module and reference through it
from tecio import libtecio
libtecio.ZoneType.ORDERED
libtecio.tec_file_writer_open(...)

# Or import specific names directly
from tecio.libtecio import ZoneType, DataType, ValueLocation
ZoneType.ORDERED

The submodules tecio.szl, tecio.plt, tecio.dat, and tecio.libtecio are all part of the public API and are documented in full below, but for typical use cases you should not need to import them directly.

`tecio.open`#

tecio.open(path, mode='r', **kwargs)#

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.

Parameters:

path (str | os.PathLike) – File path. Extension determines the format handler:
- .szplt → tecio.szl
- .plt / .bin → tecio.plt
- .dat / .tec → tecio.dat
mode (str) – Access mode — mirrors Python’s built-in 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 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.
**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'):

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 `write_ijk_zone()` or `write_fe_zone()` call. Required at open time for DAT.
`file_type`	`FileType.FULL`	One of `FULL`, `GRID`, or `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 — they are documented here for completeness.

Keyword	Default	Description
`title`	From file	Override the dataset title in the output file. Rarely needed — the existing title is preserved by default.
`variables`	From file	Do not override. The variable list is fixed by the existing file. Passing a different list will cause a mismatch between the copied zones and any new zones.
`file_type`	From file	Override the file type. Rarely needed.

Returns:

'r' → tecio.szl.Read, tecio.plt.Read, or tecio.dat.Read
'w' / 'x' → tecio.szl.Write, tecio.plt.Write, or tecio.dat.Write
'a' → AppendWrite
'a+' → AppendReadWrite

Raises:

ValueError – Unsupported file extension or unrecognised mode.
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 zones.

Examples

Read a file:

>>> with tecio.open("flow.szplt") as tec:
...     x = tec.zone[0].variable["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_ijk_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_ijk_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.zone[-1].variable["p"].values
...     tec.write_ijk_zone(data=[x2, y2, prev_p * 0.9])

Accessing Variable Data#

Every reader’s zone and variable properties return one of two format-agnostic container types rather than a plain list. Both support the same indexing, iteration, and len() you would expect from a list, plus name-based and slice-based access:

with tecio.open("flow.szplt") as r:
    r.zone[0]                       # -> ReadZone
    r.zone[1:4]                     # -> ZoneList (sub-range, same kind)
    r.zone[0].variable               # -> VariableList
    r.zone[0].variable["x"]          # -> ReadVariable, by exact name
    r.zone[0].variable[2]            # -> ReadVariable, by 0-based index

Indexing a ZoneList or VariableList always returns an element or a sub-collection of the same kind — never a raw array. To pull the underlying NumPy data for one or more variables in a single zone, use ReadZone.get_array, available on every format’s zone object:

    p = r.zone[0].get_array("p")                 # ndarray | None
    p = r.zone[0].get_array(2)                    # by 0-based index
    x, y, z = r.zone[0].get_array(["x", "y", "z"])  # tuple, for unpacking

A single key (index or name) returns one array; a list of names returns a tuple of arrays in the order given, suitable for unpacking. 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 stays in your code, and stack only when you know the shapes match:

    seq = [z.get_array("p") for z in r.zone]   # list[ndarray | None]
    stack = np.stack(seq)                       # only if every zone matches

get_array returns None for a passive or shared variable, and raises KeyError for an unknown name or IndexError for an out-of-range index.

Class	Returned by	Description
`ZoneList`	`Read.zone`	Sequence of zones; integer index, slice, or iterate
`VariableList`	`ReadZone.variable`	Sequence of variables; index by position or exact name

Append Handles#

Returned by tecio.open() when using 'a' or 'a+' mode.

Class	Mode	Description
`AppendWrite`	`'a'`	Append zones to an existing SZL file
`AppendReadWrite`	`'a+'`	Append zones and read existing zones

Submodules#

Module	Description
`tecio.szl`	Read and write Tecplot SZL (`.szplt`) files
`tecio.plt`	Read and write Tecplot PLT (`.plt`) files
`tecio.dat`	Read and write Tecplot ASCII (`.dat`) files
`tecio.libtecio`	Low-level C library bindings and enums
`tecio.utils`	Locate Tecplot installations and the TecIO library

API Reference

On this page