tdmspy 0.1.0__tar.gz

tdmspy-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto
+*.tdms binary
+*.tdms_index binary

tdmspy-0.1.0/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: "weekly"

tdmspy-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,59 @@
+# Source: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
+
+name: Build Python Package
+
+on: push
+
+jobs:
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: Install build package
+        run: >
+          python3 -m
+          pip install
+          build
+          --user
+
+      - name: Build a binary wheel and a source tarball
+        run: python3 -m build
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish package
+    # Only publish to PyPI on tag pushes
+    if: startsWith(github.ref, 'refs/tags/')
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tdmspy
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all the distribution packages
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

tdmspy-0.1.0/.github/workflows/test.yaml

@@ -0,0 +1,47 @@
+name: Run tests
+
+on:
+  - push
+
+jobs:
+  os-python-matrix:
+    strategy:
+      matrix:
+        os:
+          - name: macos
+            icon: 🍏
+          - name: ubuntu
+            icon: 🐧
+          - name: windows
+            icon: 🪟
+        python-version:
+          - "3.13"
+          - "3.14"
+
+    runs-on: ${{ matrix.os.name }}-latest
+    name: ${{ matrix.os.icon }} Python ${{ matrix.python-version }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install just
+        uses: taiki-e/install-action@just
+
+      - name: Install package
+        run: |
+          uv venv
+          uv sync
+
+      - name: Check and test code
+        run: just test

tdmspy-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Tools
+.pytest_cache/
+.ruff_cache/
+testcases-out/
+
+CLAUDE.md
+.claude
+.idea

tdmspy-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

tdmspy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moritz Breurather, Institute of Production Engineering and Photonic Technologies TU Wien  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tdmspy-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: tdmspy
+Version: 0.1.0
+Summary: Pure Python reader for National Instruments TDMS files, MIT licensed
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: numpy>=2.5.1
+Description-Content-Type: text/markdown
+
+# tdmspy
+
+A pure Python reader for National Instruments **TDMS** files, MIT licensed. Its only runtime dependency is numpy.
+
+It is written from the format specification and tested against real files and
+synthetic test cases, one for every special case of the format.
+
+## Install
+
+```sh
+uv venv --allow-existing
+uv sync --all-extras
+```
+
+## Usage
+
+```python
+import tdmspy
+
+file = tdmspy.read("measurement.tdms")  # indexes the file; no channel data is read yet
+for group in file.groups:  # in file order, not sorted
+    for channel in group.channels:
+        print(group.name, channel.name, channel.dtype, len(channel), channel.properties)
+
+values = file["rawdata"]["Channel1"].read()  # numpy array, native byte order, NI scaling applied
+raw = file["rawdata"]["Channel1"].read(scaled=False)
+part = file["rawdata"]["Channel1"].read(start=1000, stop=2000)
+```
+
+The details (what is returned for each data type, what is refused, how truncated files are treated) are in
+[`doc/design.md`](doc/design.md); every special case of the format the reader has to handle is listed with the files
+that exercise it in [`doc/special-cases.md`](doc/special-cases.md).
+
+## Tests
+
+```sh
+just test        # lint, then everything except the slow tests
+just test-all    # including large files and long fuzz runs
+just testcases      # rewrite the stored synthetic files in tests/data/synthetic
+```
+
+The tests are the specification of the reader:
+
+- `tests/catalogue.py` lists every special case of the format. Add a case there first.
+- `tests/builder.py` is a byte-level TDMS writer for the tests (interleaved, big-endian, several chunks, truncated,
+  corrupt, every property type, ...). It does not use tdmspy.
+- `tests/testcases.py` has one small file per special case, each with what it must read as (`Truth`). The files are
+  stored in `tests/data/synthetic`; the long ones are built when a test needs them.
+- `tests/data/real` are real files, with their identifying strings replaced by
+  placeholders; `tests/test_real_files.py` checks them and `tests/test_privacy.py` keeps identifiers out of the test data.
+- `tests/test_reader_*.py` are the tests of `tdmspy.read`: all test cases, the API, strict mode and scaling.
+- `tests/test_fuzz.py` and `tests/test_robust.py` damage files and read large ones.
+
+`just catalogue` regenerates `doc/special-cases.md`.
+
+## Inspired by
+
+[npTDMS](https://github.com/adamreeve/npTDMS), [pyTDMS](https://github.com/petebachant/pyTDMS) and
+[ICOschema](https://github.com/ift-tuwien/ICOschema), which tdmspy was created to aid: ICOschema reads TDMS files
+through it. No code of any of these projects is used here.
+
+TDMS, LabVIEW and NI are trademarks of National Instruments. tdmspy is not affiliated with or endorsed by NI.
+
+## Licence
+
+MIT, see [LICENSE](LICENSE).

tdmspy-0.1.0/README.md

@@ -0,0 +1,66 @@
+# tdmspy
+
+A pure Python reader for National Instruments **TDMS** files, MIT licensed. Its only runtime dependency is numpy.
+
+It is written from the format specification and tested against real files and
+synthetic test cases, one for every special case of the format.
+
+## Install
+
+```sh
+uv venv --allow-existing
+uv sync --all-extras
+```
+
+## Usage
+
+```python
+import tdmspy
+
+file = tdmspy.read("measurement.tdms")  # indexes the file; no channel data is read yet
+for group in file.groups:  # in file order, not sorted
+    for channel in group.channels:
+        print(group.name, channel.name, channel.dtype, len(channel), channel.properties)
+
+values = file["rawdata"]["Channel1"].read()  # numpy array, native byte order, NI scaling applied
+raw = file["rawdata"]["Channel1"].read(scaled=False)
+part = file["rawdata"]["Channel1"].read(start=1000, stop=2000)
+```
+
+The details (what is returned for each data type, what is refused, how truncated files are treated) are in
+[`doc/design.md`](doc/design.md); every special case of the format the reader has to handle is listed with the files
+that exercise it in [`doc/special-cases.md`](doc/special-cases.md).
+
+## Tests
+
+```sh
+just test        # lint, then everything except the slow tests
+just test-all    # including large files and long fuzz runs
+just testcases      # rewrite the stored synthetic files in tests/data/synthetic
+```
+
+The tests are the specification of the reader:
+
+- `tests/catalogue.py` lists every special case of the format. Add a case there first.
+- `tests/builder.py` is a byte-level TDMS writer for the tests (interleaved, big-endian, several chunks, truncated,
+  corrupt, every property type, ...). It does not use tdmspy.
+- `tests/testcases.py` has one small file per special case, each with what it must read as (`Truth`). The files are
+  stored in `tests/data/synthetic`; the long ones are built when a test needs them.
+- `tests/data/real` are real files, with their identifying strings replaced by
+  placeholders; `tests/test_real_files.py` checks them and `tests/test_privacy.py` keeps identifiers out of the test data.
+- `tests/test_reader_*.py` are the tests of `tdmspy.read`: all test cases, the API, strict mode and scaling.
+- `tests/test_fuzz.py` and `tests/test_robust.py` damage files and read large ones.
+
+`just catalogue` regenerates `doc/special-cases.md`.
+
+## Inspired by
+
+[npTDMS](https://github.com/adamreeve/npTDMS), [pyTDMS](https://github.com/petebachant/pyTDMS) and
+[ICOschema](https://github.com/ift-tuwien/ICOschema), which tdmspy was created to aid: ICOschema reads TDMS files
+through it. No code of any of these projects is used here.
+
+TDMS, LabVIEW and NI are trademarks of National Instruments. tdmspy is not affiliated with or endorsed by NI.
+
+## Licence
+
+MIT, see [LICENSE](LICENSE).

tdmspy-0.1.0/doc/design.md

@@ -0,0 +1,152 @@
+# Design and contract of tdmspy
+
+This is what `tdmspy.read` has to do. The tests (`tests/`) check every statement here; where this file and a test
+disagree, one of them is a bug. The list of special cases of the format is in [special-cases.md](special-cases.md).
+
+## Goals and non-goals
+
+- Read TDMS files (version 4712 and 4713) of any size, including those written by LabVIEW and other
+  libraries; correctly in every layout the format allows that real files use.
+- Pure Python and numpy, MIT licensed: no native code, no dependency beyond numpy.
+- Fast enough to open a file of a million segments and to read a 1 GB channel without copying it more than once.
+- Honest: what is not supported is an error that says so, never silently wrong data.
+- Non-goals: writing TDMS files, DAQmx raw data, `.tdms_index` files, LabVIEW `.tdx` / TDM, pandas or HDF5 export.
+
+## The API
+
+```python
+import tdmspy
+
+file = tdmspy.read(path, strict=False)  # path: str or os.PathLike
+```
+
+`read` reads the structure of the file (every segment's lead-in and metadata) and keeps no channel data in memory.
+The file is opened again for every `Channel.read`, so a `TdmsFile` holds no open file handle and can be used from
+several threads.
+
+| Object | Members |
+|---|---|
+| `TdmsFile` | `path`, `properties` (dict), `groups` (list, file order), `truncated` (bool); `file["name"]` returns the group (`KeyError` if missing), `"name" in file`, iterating gives the groups |
+| `Group` | `name`, `properties`, `channels` (list, file order); `group["name"]`, `"name" in group` |
+| `Channel` | `name`, `properties`, `dtype` (a native numpy dtype, `None` for a channel without a data type), `len(channel)`, `read(start=0, stop=None, *, scaled=True)` |
+| `Timestamp` | `seconds` since 1904-01-01 UTC, `fraction` in units of 2**-64 s; `to_datetime64(unit)`, `from_datetime64` |
+
+Order: groups and channels are in the order of their **first appearance** in the file (a channel's path appearing
+counts for its group as well), never sorted. Properties are in the order they were first written; a later segment
+that rewrites a property changes its value, not its position.
+
+Names are exactly as stored. `''` in a path is one apostrophe; `/` inside quotes is part of the name.
+
+### Property values
+
+Python values: `int` for all integer types, `float` for single, double and the with-unit variants (a single
+precision value is converted exactly), `bool`, `str`, `complex`, and `Timestamp` for timestamps (both parts kept
+exactly). The width of a property is not kept.
+
+### Channel data
+
+`read` returns a numpy array in **native byte order**, whatever the file has, and a copy the caller may change.
+
+| TDMS type | numpy |
+|---|---|
+| int8 ... int64, uint8 ... uint64 | the same |
+| single, double | float32, float64 (NaN, infinities and -0.0 as stored) |
+| boolean | bool |
+| string | object array of `str` |
+| timestamp | `datetime64[us]`, UTC, truncated to the microsecond (never rounded up) |
+| complex single, double | complex64, complex128 |
+| none (the channel never has a data type) | `dtype` is `None`, length 0, `read()` returns an empty array |
+| extended float, anything else | `UnsupportedFeatureError` when the file is opened |
+
+`start` and `stop` count values, like a numpy slice with non-negative bounds (negative bounds are a `ValueError`;
+`stop` beyond the end is cut). A slice reads only the bytes it needs.
+
+### Scaling
+
+`read(scaled=True)` is the default. If the channel (else its group, else the file) has `NI_Number_Of_Scales` > 0 and
+`NI_Scaling_Status` is not `scaled`, the NI scales are applied: **Linear** (`x * slope + intercept`) and
+**Polynomial** (coefficients from `..._Polynomial_Coefficients_Size`, default 4), each reading either the raw data
+(`..._Input_Source` = 0xFFFFFFFF, also when absent) or the output of an earlier scale; the last scale is the result.
+The arithmetic is double precision whatever the data type, and the result is float64. Without scaling, `read`
+returns the stored values with their stored dtype. `read(scaled=False)` is always the stored values.
+
+Any other scale type (RTD, thermocouple, table, strain, ...) raises `UnsupportedScalingError` on a scaled read; the
+raw read works.
+
+### Truncated files
+
+Writers append to the file while acquiring, and a crash or a copy can cut a file anywhere.
+
+- A file that ends inside its last segment is read as far as it is complete: the complete values of every channel of
+  the cut segment (for contiguous layout each channel keeps the complete values it has; for interleaved layout the
+  complete rows), and nothing of a segment whose metadata is cut. `file.truncated` is `True`.
+- Bytes at the end that are fewer than a lead-in (28 bytes) count as a cut as well.
+- A last segment with next segment offset 0xFFFFFFFFFFFFFFFF (still being written) runs to the end of the file; it
+  is truncated only if its data ends inside a chunk.
+- `read(path, strict=True)` raises `TdmsFormatError` instead of any of these.
+- Damage that is not at the end (a wrong signature in the middle, an index that does not fit its segment) is always
+  a `TdmsFormatError`.
+
+
+### Errors
+
+All errors the package raises on purpose derive from `TdmsError`:
+
+- `TdmsFormatError` (also a `ValueError`): not TDMS, or inconsistent: wrong signature, unknown version, a file shorter
+  than a lead-in (including 0 bytes), counts and lengths that do not fit the file, an index of 0 without a previous
+  index, a data type that changes between segments, interleaved channels with different counts, an invalid object
+  path, a `.tdms_index` file.
+- `UnsupportedFeatureError` (also a `NotImplementedError`): valid but not read: DAQmx raw data, extended floats.
+  `UnsupportedScalingError` is one of these.
+
+Problems of the file system (`FileNotFoundError`, `PermissionError`, ...) are not wrapped.
+
+Fuzzed and damaged files may raise only these. They must not hang or allocate memory beyond what the file's size can
+justify: every count and length in the file is checked against the bytes that remain before anything is allocated.
+
+## Semantics of segments
+
+These are the rules the implementation follows. Each has files among the test cases.
+
+1. A file is a sequence of segments. A segment is a 28 byte lead-in (`TDSm`, table of contents, version, next segment
+   offset, raw data offset), metadata, raw data. The table of contents is little-endian; the rest of the lead-in,
+   the metadata and the data use the byte order its big-endian flag says, per segment.
+2. The metadata is read only if the metadata flag is set. If the new object list flag is also set, the list replaces
+   the active object list (the order of objects the raw data follows); without it, the objects listed only **update**
+   what the previous list had (properties, raw data index) and the list stays as it was. Objects not listed keep their
+   index and still get their share of the raw data.
+3. A segment without metadata continues with the active list and indexes.
+4. The raw data of a segment starts at lead-in + 28 + raw data offset and ends at next segment offset (or the end of
+   the file when it is 0xFFFFFFFFFFFFFFFF).
+5. A raw data index is `0xFFFFFFFF` (no data in this segment), `0` (the same type and count as the object's previous
+   index), or explicit (length, type, dimension 1, number of values; strings add the total size in bytes). A channel's
+   data type cannot change.
+6. The raw data is a number of **chunks** (size of the data / size of one chunk), each holding every channel that has data,
+   in list order: contiguous (channel after channel) or interleaved (the interleaved flag: one value of each channel in
+   turn). Channels may have different counts when contiguous; interleaved needs equal counts. A string channel is its
+   offsets (`uint32` end positions) then the text, UTF-8.
+7. Object paths are `/`, `/'group'` or `/'group'/'channel'`. A group exists if any path mentions it.
+8. Property updates: the last written value wins; properties are per object and accumulate over segments.
+
+## How it is implemented
+
+- `tdmspy/_metadata.py` parses a segment's metadata (objects, raw data indexes, properties). Every count and length is
+  checked against the bytes that remain before anything is read or allocated.
+- `tdmspy/_scan.py` walks the segments and keeps, per channel, a list of *blocks*: `repeat` units of `per`
+  consecutive values, `stride` bytes apart, from byte `offset`. A segment of several chunks, or interleaved data, is
+  one block; the identical segments of an acquisition merge into one (a file of 250 000 segments of one channel set
+  is a handful of blocks). A segment whose metadata equals the previous segment's metadata is not parsed again.
+- `tdmspy/file.py` reads a slice by mapping the file and copying the wanted part of the wanted blocks into a new
+  array, so a slice costs what it returns, not what the channel holds. Byte order, booleans, complex numbers and
+  timestamps are converted while copying.
+- `tdmspy/_scaling.py` applies the NI scales.
+- No global state; no I/O at import; no handle kept open.
+
+## Development
+
+- The catalogue (`tests/catalogue.py`) lists the special cases. A new case is added there, then as a file in
+  `tests/testcases.py` with the values it must read as, and the file is stored in `tests/data/synthetic` (`just testcases`).
+- `tests/builder.py` writes any byte sequence the format can express, including broken ones.
+- Real files go into `tests/data/real`, listed in `REAL_FILES` with the cases they exercise; `just real-expected`
+  stores what they contain.
+- Test data must not identify what was measured, where, by whom or on which device: see `tests/test_privacy.py`.

tdmspy-0.1.0/doc/special-cases.md

@@ -0,0 +1,146 @@
+# Special cases of the TDMS format
+
+<!-- generated by `just catalogue` from tests/catalogue.py and tests/testcases.py: do not edit -->
+
+77 special cases, exercised by 80 synthetic files (`tests/testcases.py`), 4 real files (`tests/data/real`) and a few behaviour tests.
+
+## The file
+
+| Case | The reader must | Exercised by |
+|---|---|---|
+| `file.minimal` | A file of one segment with one group and one channel is read. | `minimal` |
+| `file.empty_is_error` | A file of 0 bytes, or shorter than a lead-in (28 bytes), is a `TdmsFormatError`. | `empty_file`, `shorter_than_lead_in` |
+| `file.wrong_signature_is_error` | A file that does not start with `TDSm` is a `TdmsFormatError` (not a crash, not a guess). | `wrong_signature` |
+| `file.index_file_is_error` | A `.tdms_index` file (signature `TDSh`) is refused with a clear message: it holds no data. | `index_file` |
+| `file.not_tdms_inside` | A segment with a wrong signature after valid ones is a `TdmsFormatError`, unless it is the cut-off end of the file. | `garbage_after_segments` |
+
+## Versions
+
+| Case | The reader must | Exercised by |
+|---|---|---|
+| `version.4712` | Segments of version 4712 (TDMS 1.0) are read. | `version_4712` |
+| `version.4713` | Segments of version 4713 (TDMS 2.0) are read. | `minimal`, real: `one_int16_channel.tdms`, real: `three_int16_channels.tdms`, real: `three_int16_channels_short.tdms`, real: `unequal_counts_untyped_channels.tdms` |
+| `version.unknown_is_error` | Any other version number is a `TdmsFormatError`. | `version_unknown` |
+
+## Segments
+
+| Case | The reader must | Exercised by |
+|---|---|---|
+| `segment.many` | Hundreds of small segments of one channel are read as one continuous channel, in order. | `many_segments`, `many_segments_5000`, real: `one_int16_channel.tdms`, real: `three_int16_channels.tdms`, real: `three_int16_channels_short.tdms`, real: `unequal_counts_untyped_channels.tdms` |
+| `segment.metadata_only` | A segment without raw data (no raw data flag) defines objects and properties and adds no values. | `metadata_only_segment` |
+| `segment.raw_only` | A segment without metadata (no metadata flag) holds more data for the previous segment's objects, layout and indexes. | `raw_only_segment` |
+| `segment.meta_without_new_list` | A segment with metadata but without the new-object-list flag updates only the objects it lists; every other object keeps its index and still receives its share of the raw data. | `meta_without_new_list`, real: `unequal_counts_untyped_channels.tdms` |
+| `segment.new_list_replaces` | A new object list replaces the active one: an object left out gets no more data in that segment, one added gets some. | `new_list_replaces` |
+| `segment.raw_offset_padding` | The raw data starts where the lead-in's raw data offset says, even if the metadata is shorter. | `raw_offset_padding` |
+| `segment.zero_values` | A channel whose index says 0 values (or a segment with an empty raw data section) adds nothing and breaks nothing. | `zero_values` |
+| `segment.next_offset_unknown` | A last segment whose next segment offset is 0xFFFFFFFFFFFFFFFF (still being written) runs to the end of the file. | `next_offset_unknown` |
+| `segment.truncated_file` | A file cut off inside its last segment gives the complete values of that segment and sets `file.truncated`; `strict=True` raises instead. | `truncated_mid_values`, `truncated_in_metadata`, `truncated_in_lead_in`, `truncated_interleaved_row`, `truncated_second_channel`, `truncated_after_whole_chunks` |
+| `segment.next_offset_beyond_end` | A last segment declaring more bytes than the file has is treated as truncated. | `next_offset_beyond_end` |
+| `segment.chunks` | A segment whose raw data is several repeats of the channel set (chunks) gives all the values, in order. | `chunks`, `truncated_after_whole_chunks`, `interleaved_chunks` |
+| `segment.partial_chunk` | Bytes after the last whole chunk of a truncated segment give the values that are complete, none that are cut. | `truncated_mid_values`, `truncated_interleaved_row`, `truncated_second_channel` |
+
+## The raw data index
+
+| Case | The reader must | Exercised by |
+|---|---|---|
+| `index.none` | An index of 0xFFFFFFFF means the object has no data in this segment (and is not an error). | `metadata_only_segment`, `index_none_then_data`, `channel_without_data` |
+| `index.same_as_previous` | An index of 0 means the previous segment's type and count for that channel. | `many_segments`, `index_same_after_change`, `mixed_endianness`, `property_update`, `many_segments_5000`, real: `one_int16_channel.tdms`, real: `three_int16_channels.tdms`, real: `three_int16_channels_short.tdms`, real: `unequal_counts_untyped_channels.tdms` |
+| `index.changed_count` | A new explicit index changes a channel's count in a later segment. | `meta_without_new_list`, `zero_values`, `index_same_after_change` |
+| `index.string` | The string index (type, dimension, count, total size) is read. | `strings` |
+| `index.type_change_is_error` | A channel whose data type changes between segments is a `TdmsFormatError`. | `index_type_change` |
+| `index.same_without_previous_is_error` | An index of 0 for a channel that never had an explicit one is a `TdmsFormatError`. | `index_same_without_previous` |
+
+## The layout of the raw data
+
+| Case | The reader must | Exercised by |
+|---|---|---|
+| `layout.contiguous_multi_channel` | Channels of one chunk are stored one after the other, each with its own count. | `truncated_second_channel`, `contiguous_three_types`, real: `one_int16_channel.tdms`, real: `three_int16_channels.tdms`, real: `three_int16_channels_short.tdms` |
+| `layout.unequal_counts` | Channels in one segment may have different counts (contiguous layout). | `unequal_counts`, real: `unequal_counts_untyped_channels.tdms` |
+| `layout.interleaved` | Interleaved data (one value of each channel after the other) is read. | `truncated_interleaved_row`, `interleaved_two_channels`, `interleaved_three_channels_floats`, `big_endian_interleaved` |
+| `layout.interleaved_chunks` | Interleaved data in several chunks is read. | `interleaved_chunks` |
+| `layout.interleaved_mixed_types` | Interleaved channels of different fixed sizes (int16 next to float64) are read. | `interleaved_mixed_types` |
+| `layout.interleaved_unequal_is_error` | Interleaved channels with different counts are a `TdmsFormatError`. | `interleaved_unequal_counts` |
+| `layout.big_endian` | A segment with the big-endian flag is read completely: lead-in, metadata and data. | `big_endian`, `big_endian_interleaved` |
+| `layout.mixed_endianness` | Segments of different byte order in one file are each read in their own. | `mixed_endianness` |
+| `layout.channel_added_later` | A channel that first appears in a later segment starts there. | `new_list_replaces` |
+| `layout.channel_dropped` | A channel that stops getting data keeps what it has. | `new_list_replaces` |
+
+## Data types
+
+| Case | The reader must | Exercised by |
+|---|---|---|
+| `type.integers` | int8 to int64 and uint8 to uint64 channels are read exactly, as native numpy arrays. | `integers`, real: `one_int16_channel.tdms`, real: `three_int16_channels.tdms`, real: `three_int16_channels_short.tdms` |
+| `type.floats` | float32 and float64 channels are read exactly, including NaN, inf and -0.0. | `floats`, real: `one_int16_channel.tdms`, real: `three_int16_channels.tdms`, real: `three_int16_channels_short.tdms`, real: `unequal_counts_untyped_channels.tdms` |
+| `type.bool` | A boolean channel is read as a numpy bool array. | `booleans` |
+| `type.string` | A string channel (offsets then text) is read, over several segments too, with empty and non-ASCII strings. | `strings` |
+| `type.timestamp` | A timestamp channel is read as `datetime64[us]` (UTC, truncated). | `timestamps`, `timestamp_fraction_extremes` |
+| `type.complex` | Complex single and double channels are read as complex64 and complex128. | `complex_numbers` |
+| `type.no_data_type` | A channel that never has data has `dtype None`, length 0 and reads as an empty array (the quality_score channels). | `channel_without_data`, real: `unequal_counts_untyped_channels.tdms` |
+| `type.unsupported_is_error` | A data type this package cannot read (extended float) is an `UnsupportedFeatureError`, not garbage. | `extended_float_channel` |
+
+## Properties
+
+| Case | The reader must | Exercised by |
+|---|---|---|
+| `prop.all_types` | Properties of every type (integers, floats, bool, string, timestamp, complex, with-unit floats) are read as Python values. | `property_types`, `property_complex`, `property_unit_types`, real: `one_int16_channel.tdms`, real: `three_int16_channels.tdms`, real: `three_int16_channels_short.tdms` |
+| `prop.root_group_channel` | Properties at the file, group and channel level are kept apart. | `minimal`, `property_types`, real: `one_int16_channel.tdms`, real: `three_int16_channels.tdms`, real: `unequal_counts_untyped_channels.tdms` |
+| `prop.update` | A property written again in a later segment has the later value; others stay. | `property_update` |
+| `prop.added_later` | A property that first appears in a later segment is there. | `property_update` |
+| `prop.unicode` | Names and values with non-ASCII characters are read (UTF-8). | `property_unicode` |
+| `prop.empty_and_odd_names` | An empty string value, a name with a trailing space and a very long value are kept as they are. | `property_odd_values`, real: `unequal_counts_untyped_channels.tdms` |
+| `prop.timestamp_exact` | A timestamp property keeps seconds and the 2**-64 fraction exactly; conversion to `datetime64` truncates. | `timestamp_fraction_extremes`, `property_types` |
+| `prop.many` | Thousands of properties on one object are read. | `many_properties` |
+| `prop.unsupported_type_is_error` | A property of a type this package cannot read is an `UnsupportedFeatureError`. | `property_extended_float` |
+
+## Objects and paths
+
+| Case | The reader must | Exercised by |
+|---|---|---|
+| `path.group_without_channels` | A group that only has properties is a group with no channels. | `group_without_channels`, real: `one_int16_channel.tdms`, real: `three_int16_channels.tdms`, real: `three_int16_channels_short.tdms`, real: `unequal_counts_untyped_channels.tdms` |
+| `path.implicit_group` | A channel whose group object is never written still has its group. | `implicit_group` |
+| `path.order` | Groups and channels are in the order of their first appearance in the file, not sorted. | `first_appearance_order` |
+| `path.quote_and_slash` | Names with `'` (written `''`), `/` and spaces are read back as written. | `quotes_and_slashes` |
+| `path.unicode` | Group and channel names with non-ASCII characters are read. | `property_unicode` |
+| `path.reserved_looking_names` | Groups or channels named `info`, `name`, `groups`, `properties`, `data` or `read` are ordinary. | `reserved_looking_names`, real: `unequal_counts_untyped_channels.tdms` |
+| `path.root_only_properties` | A file whose only object is the root has properties and no groups. | `root_only` |
+| `path.invalid_is_error` | An object path that is not `/` or `/'group'` or `/'group'/'channel'` is a `TdmsFormatError`. | `three_level_path`, `path_without_slash` |
+
+## Scaling
+
+| Case | The reader must | Exercised by |
+|---|---|---|
+| `scale.linear` | A channel with one linear NI scale reads scaled, and raw with `scaled=False`. | `scale_linear` |
+| `scale.polynomial` | A polynomial NI scale is applied. | `scale_polynomial` |
+| `scale.chain` | Scales that take another scale as their input source are applied in that order. | `scale_chain` |
+| `scale.already_scaled` | `NI_Scaling_Status` = `scaled` means the data is final and is not scaled again. | `scale_already_scaled` |
+| `scale.group_level` | Scaling declared on the group applies to its channels without their own. | `scale_group_level` |
+| `scale.file_level` | Scaling declared on the file applies to channels and groups without their own. | `scale_file_level` |
+| `scale.channel_overrides_group` | A channel's own scaling wins over its group's. | `scale_channel_overrides_group` |
+| `scale.float32_input` | Scaling single precision data is done in double precision and gives float64. | `scale_float32_input` |
+| `scale.unsupported_is_error` | A scale type that is not implemented (RTD, thermocouple, ...) raises `UnsupportedScalingError` on a scaled read; the raw read works. | `scale_unsupported_type` |
+| `scale.none` | A channel without scale properties reads the same scaled and raw. | `scale_channel_overrides_group`, `scale_none` |
+
+## Unsupported layouts
+
+| Case | The reader must | Exercised by |
+|---|---|---|
+| `daqmx.is_error` | DAQmx raw data (indexes 0x1269 and 0x126A) is an `UnsupportedFeatureError` that names DAQmx. | `daqmx_raw_data` |
+
+## Robustness
+
+| Case | The reader must | Exercised by |
+|---|---|---|
+| `robust.huge_counts` | Declared counts and lengths far beyond the file's size are a `TdmsFormatError` without allocating them. | `huge_object_count`, `huge_property_count`, `huge_string_length`, `huge_path_length`, `huge_value_count` |
+| `robust.fuzz` | Truncated and randomly damaged files raise only `TdmsError` (never another exception, never hang, never allocate wildly). | `tests/test_fuzz.py::test_damaged_files_only_raise_tdms_errors` |
+| `robust.lazy` | Opening a file reads its structure; channel data is read when asked for, and a slice reads only what it needs. | `tests/test_robust.py::test_opening_reads_the_structure_not_the_data` |
+| `robust.large` | A file of 100 MB opens quickly and a channel reads in time proportional to its size (slow test). | `tests/test_robust.py::test_a_hundred_megabyte_channel_reads_in_proportion` |
+| `robust.many_segments` | A file of tens of thousands of segments opens in a reasonable time. | `many_segments_5000` |
+
+## Real files
+
+| File | Special cases it exercises |
+|---|---|
+| `one_int16_channel.tdms` | `version.4713`, `segment.many`, `index.same_as_previous`, `type.integers`, `type.floats`, `prop.all_types`, `prop.root_group_channel`, `path.group_without_channels`, `layout.contiguous_multi_channel` |
+| `three_int16_channels.tdms` | `version.4713`, `segment.many`, `index.same_as_previous`, `type.integers`, `type.floats`, `prop.all_types`, `prop.root_group_channel`, `path.group_without_channels`, `layout.contiguous_multi_channel` |
+| `three_int16_channels_short.tdms` | `version.4713`, `segment.many`, `index.same_as_previous`, `type.integers`, `type.floats`, `prop.all_types`, `path.group_without_channels`, `layout.contiguous_multi_channel` |
+| `unequal_counts_untyped_channels.tdms` | `version.4713`, `segment.many`, `segment.meta_without_new_list`, `index.same_as_previous`, `type.floats`, `type.no_data_type`, `path.group_without_channels`, `path.reserved_looking_names`, `layout.unequal_counts`, `prop.root_group_channel`, `prop.empty_and_odd_names` |