cefast 0.1.0__tar.gz

cefast-0.1.0/.clang-format

@@ -0,0 +1,26 @@
+---
+# See http://clang.llvm.org/docs/ClangFormatStyleOptions.html for a definition 
+# of the options
+Language: Cpp
+BasedOnStyle:  WebKit
+
+# Line length
+ColumnLimit: 100
+
+# Indent with 4 spaces
+IndentWidth: 4
+AccessModifierOffset: -4 # -IndentWidth
+ConstructorInitializerIndentWidth: 8 # 2 * IndentWidth
+
+BreakBeforeBraces: Allman
+
+AllowShortFunctionsOnASingleLine: Inline
+AlwaysBreakTemplateDeclarations: true
+AlwaysBreakBeforeMultilineStrings: true
+BreakBeforeBinaryOperators: true
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+IndentCaseLabels: true
+MaxEmptyLinesToKeep: 2
+Standard: Cpp11
+UseTab: Never
+

cefast-0.1.0/.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  # Actions are pinned to commit SHAs: this is what keeps them current.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

cefast-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,109 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: pip install meson ninja numpy meson-python
+      # The CSA sample corpus is not in the repository: it is downloaded from the archive and
+      # verified against tests/resources/csa_manifest.json, so the manifest is the cache key.
+      - name: Restore the CSA corpus
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+        with:
+          path: tests/resources/csa
+          key: csa-corpus-${{ hashFiles('tests/resources/csa_manifest.json') }}
+      - name: Download the CSA corpus
+        run: python -I tools/fetch_csa_corpus.py
+      - name: Configure
+        run: meson setup build
+      - name: Test
+        run: meson test -C build --print-errorlogs
+      - name: Test log
+        if: failure()
+        run: cat build/meson-logs/testlog.txt
+
+  sanitizers:
+    runs-on: ubuntu-latest
+    env:
+      UBSAN_OPTIONS: halt_on_error=1:print_stacktrace=1
+      ASAN_OPTIONS: halt_on_error=1:print_summary=1
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: pip install meson ninja
+      - name: Restore the CSA corpus
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+        with:
+          path: tests/resources/csa
+          key: csa-corpus-${{ hashFiles('tests/resources/csa_manifest.json') }}
+      - name: Download the CSA corpus
+        run: python -I tools/fetch_csa_corpus.py
+      - name: Configure
+        # No python module: the sanitised extension would need a matching interpreter.
+        run: >
+          meson setup build-asan -Db_sanitize=address,undefined -Db_lundef=false -Dpython=false
+      - name: Test
+        run: meson test -C build-asan --print-errorlogs
+      - name: Test log
+        if: failure()
+        run: cat build-asan/meson-logs/testlog.txt
+
+  fuzz:
+    runs-on: ubuntu-latest
+    env:
+      CC: clang
+      CXX: clang++
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: pip install meson ninja
+      - name: Install clang
+        run: sudo apt-get update && sudo apt-get install -y clang
+      - name: Restore the CSA corpus
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+        with:
+          path: tests/resources/csa
+          key: csa-corpus-${{ hashFiles('tests/resources/csa_manifest.json') }}
+      - name: Download the CSA corpus
+        run: python -I tools/fetch_csa_corpus.py
+      - name: Configure
+        run: meson setup build-fuzz -Dpython=false -Dwith_tests=false -Dfuzzing=true -Dbuildtype=debugoptimized
+      - name: Compile
+        run: ninja -C build-fuzz
+      - name: Seeds
+        run: python3 tools/fuzz/make_corpus.py --output "$RUNNER_TEMP/corpus"
+      # A short run keeps the job cheap: it is a regression gate for the corpus, not a
+      # campaign. One process per target so a finding fails the job with its artifact.
+      - name: Fuzz
+        run: |
+          for target in load time float lexer lexer_diff records_diff; do
+            max_len=65536
+            test "$target" = load && max_len=262144
+            mkdir -p "$RUNNER_TEMP/artifacts/$target"
+            ./build-fuzz/tools/fuzz/fuzz_$target "$RUNNER_TEMP/corpus/$target" \
+              -dict=tools/fuzz/cef.dict -max_total_time=60 -max_len=$max_len \
+              -rss_limit_mb=2048 \
+              -artifact_prefix="$RUNNER_TEMP/artifacts/$target/"
+          done
+      - name: Fuzz artifacts
+        if: failure()
+        run: find "$RUNNER_TEMP/artifacts" -type f -exec sh -c 'echo "== $1"; xxd "$1" | head -40' _ {} \;

cefast-0.1.0/.github/workflows/wheels.yml

@@ -0,0 +1,119 @@
+name: Build and test wheels on multiple platforms
+
+on:
+  release:
+    types: [published]
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build_sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - name: Build sdist
+        run: pipx run build --sdist
+      - name: Upload artifact
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: cibw-sdist
+          path: dist/*.tar.gz
+
+  build_wheels:
+    name: ${{ matrix.os }} ${{ matrix.CIBW_ARCHS }} wheels
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+      actions: write
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            CIBW_ENVIRONMENT: ''
+            CIBW_ARCHS: "x86_64"
+            CIBW_PLATFORM: "auto"
+          - os: ubuntu-latest
+            CIBW_ENVIRONMENT: ''
+            CIBW_ARCHS: "wasm32"
+            CIBW_PLATFORM: "pyodide"
+          - os: ubuntu-24.04-arm
+            CIBW_ENVIRONMENT: ''
+            CIBW_ARCHS: "aarch64"
+            CIBW_PLATFORM: "auto"
+          - os: windows-latest
+            CIBW_ENVIRONMENT: ''
+            CIBW_ARCHS: "AMD64"
+            CIBW_PLATFORM: "auto"
+          - os: windows-11-arm
+            CIBW_ENVIRONMENT: ''
+            CIBW_ARCHS: "ARM64"
+            CIBW_PLATFORM: "auto"
+          - os: macos-15-intel
+            CIBW_ENVIRONMENT: >
+              MACOSX_DEPLOYMENT_TARGET='13.0'
+            CIBW_ARCHS: "x86_64"
+            CIBW_PLATFORM: "auto"
+          - os: macos-latest # Apple Silicon
+            CIBW_ENVIRONMENT: >
+              MACOSX_DEPLOYMENT_TARGET='13.0'
+            CIBW_ARCHS: "arm64"
+            CIBW_PLATFORM: "auto"
+    env:
+      CIBW_ENVIRONMENT: ${{ matrix.CIBW_ENVIRONMENT }}
+      # Windows on ARM has native CPython builds from 3.11 only
+      CIBW_SKIP: "*-win32 *i686 cp310-win_arm64"
+      CIBW_ARCHS: ${{ matrix.CIBW_ARCHS }}
+      CIBW_PLATFORM: ${{ matrix.CIBW_PLATFORM }}
+      CIBW_ENVIRONMENT_LINUX: PATH=/usr/local/bin:/usr/lib/ccache:$PATH CCACHE_DIR=/host${{ github.workspace }}/.ccache CCACHE_CONFIGPATH=/host/home/runner/.config/ccache/ccache.conf
+      # see https://github.com/matplotlib/matplotlib/pull/28687/files#diff-504e739c530d50b780e9a09ae8fd0c3ea8258ea7553be06afb06f03f95b1ee0aR103
+      CIBW_CONFIG_SETTINGS_WINDOWS: >-
+        setup-args="--vsenv"
+        setup-args="-Db_vscrt=mt"
+        setup-args="-Dcpp_link_args=['ucrt.lib','vcruntime.lib','/nodefaultlib:libucrt.lib','/nodefaultlib:libvcruntime.lib']"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - name: ccache
+        uses: hendrikmuhs/ccache-action@5ebbd400eff9e74630f759d94ddd7b6c26299639 # v1.2
+        with:
+          key: ${{ github.job }}-${{ matrix.os }}-${{ matrix.CIBW_ARCHS }}
+          max-size: "5G"
+      # Each wheel runs tests/wheel/test_wheel.py in its own environment (see
+      # [tool.cibuildwheel] in pyproject.toml): import cefast, load a small inline CEF file from
+      # bytes, gzip bytes and a path. The CSA corpus is never needed.
+      - name: Build wheels
+        uses: pypa/cibuildwheel@f9b966cfadf4109556cadc5bb39ddb72d0ce664e # v4.3.5
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: cibw-wheels-${{ matrix.os }}-${{ matrix.CIBW_ARCHS }}
+          path: ./wheelhouse/*.whl
+
+  upload_pypi:
+    needs: [build_sdist, build_wheels]
+    runs-on: ubuntu-latest
+    # upload to PyPI only on github releases
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cefast
+    permissions:
+      # id-token is what trusted publishing uses; the two reads are all this job needs.
+      id-token: write
+      contents: read
+      actions: read
+    if: github.event_name == 'release' && github.event.action == 'published' && github.repository_owner == 'SciQLop'
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
+        with:
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
+        with:
+          skip-existing: true

cefast-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+build/
+build*/
+subprojects/*
+!subprojects/*.wrap
+!subprojects/packagefiles/
+*.kdev4
+*__pycache__*
+*.py[cod]
+.cache/
+compile_commands.json
+tests/resources/csa/
+fuzz-*.log

cefast-0.1.0/COPYING

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Laboratory of Plasma Physics, Ecole Polytechnique, CNRS, Sorbonne Université, Université Paris-Saclay
+
+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.

cefast-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.1
+Name: cefast
+Version: 0.1.0
+Summary: Fast reader for ESA's Cluster Exchange Format (CEF 2.0)
+Author-Email: Alexis Jeandet <alexis.jeandet@member.fsf.org>
+License: MIT License
+         
+         Copyright (c) 2026 Laboratory of Plasma Physics, Ecole Polytechnique, CNRS, Sorbonne Université, Université Paris-Saclay
+         
+         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.
+         
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Project-URL: homepage, https://github.com/SciQLop/CEFast
+Project-URL: repository, https://github.com/SciQLop/CEFast
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Description-Content-Type: text/markdown
+
+[![tests](https://github.com/SciQLop/CEFast/actions/workflows/tests.yml/badge.svg)](https://github.com/SciQLop/CEFast/actions/workflows/tests.yml)
+[![wheels](https://github.com/SciQLop/CEFast/actions/workflows/wheels.yml/badge.svg)](https://github.com/SciQLop/CEFast/actions/workflows/wheels.yml)
+[![PyPI](https://img.shields.io/pypi/v/cefast)](https://pypi.org/project/cefast/)
+[![Python versions](https://img.shields.io/pypi/pyversions/cefast)](https://pypi.org/project/cefast/)
+[![license](https://img.shields.io/badge/license-MIT-blue)](COPYING)
+
+<p align="center"><img src="docs/images/cefast_logo.png" alt="CEFast" width="600"></p>
+
+# CEFast
+
+A fast reader for CEF (Cluster Exchange Format), the text format of ESA's Cluster Science Archive.
+C++20 core, Python bindings, no dependencies beyond numpy.
+
+```sh
+pip install cefast
+```
+
+```python
+import cefast
+f = cefast.load("C1_CP_FGM_SPIN__20010201_000000_20010202_000000_V140305.cef.gz")
+f["B_vec_xyz_gse__C1_CP_FGM_SPIN"].values      # (records, 3) float32
+f["time_tags__C1_CP_FGM_SPIN"].values.dtype    # datetime64[ns]
+```
+
+## Why CEFast
+
+CEFLIB is the reference CEF reader, and it is hard to live with: source tarball only, no wheels,
+a global singleton, and no working byte variables. CEFast is
+installable with pip, free of global state, and readable by someone else.
+
+Correctness is checked, not claimed:
+
+- every CEF 2.0 construct the archive uses, checked against the specification, with the deviations
+  we accept listed in [docs/accepted-deviations.md](docs/accepted-deviations.md);
+- 41 real CSA files, every one CEFLIB can read compared value by value against CEFLIB 1.8.6,
+  plus hand-made files for malformed input;
+- the full suite runs under ASan and UBSan in CI, together with an allocation budget test for the
+  header path;
+- libFuzzer targets run in CI, each comparing a fast path with a slow reference: serial against
+  parallel loading, the float parser against `strtod`, the fixed-width time parser against the
+  general one, the header lexer and the record scanner against frozen copies of the simpler code
+  they replaced;
+- a malformed file raises a `ParseError` naming the file, the line and the record: it never returns
+  shifted columns or garbage.
+
+## Install
+
+```sh
+pip install cefast
+```
+
+Wheels are built for Linux (x86_64, aarch64), macOS 13+ (x86_64, arm64) and Windows (x64,
+ARM64), for CPython 3.10 and newer, including free-threaded builds. A Pyodide (wasm32) wheel is
+built too. Elsewhere, `pip install` builds from the sdist with a C++20 compiler and meson.
+
+## Loading
+
+```python
+cefast.load("file.cef")            # path or os.PathLike
+cefast.load("file.cef.gz")         # gzip, detected from the content
+cefast.load(data)                  # bytes, bytearray or memoryview
+```
+
+`threads=0` (the default) picks a thread count from the machine, `threads=1` parses serially,
+`threads=N` uses at most N. Data sections above ~48 KiB are split across threads; the result is
+identical either way.
+
+Loading releases the GIL. A path is memory-mapped, or read when the platform has no mmap, and bytes
+are borrowed: the returned arrays are views on that memory, valid as long as the `CEF` object and
+its variables live.
+
+## Variables
+
+```python
+f.keys()                           # names, in file order
+"B_vec_xyz_gse__C1_CP_FGM_SPIN" in f
+v = f["B_vec_xyz_gse__C1_CP_FGM_SPIN"]
+v.name, v.value_type               # 'B_vec_xyz_gse__C1_CP_FGM_SPIN', 'FLOAT'
+v.sizes                            # (3,), the CEF SIZES attribute
+v.is_nrv                           # True when the values are in the header (DATA), not per record
+v.attributes                       # dict of the other variable attributes
+f.attributes                       # dict of the global attributes
+```
+
+Attribute values are plain Python values: text and numbers come as one value or a list, times as
+`datetime.datetime`, time ranges as a pair of them.
+
+Values are numpy arrays. Record-varying variables get a record axis, header variables keep their
+declared shape.
+
+| CEF VALUE_TYPE | numpy dtype |
+| --- | --- |
+| FLOAT | float32 |
+| DOUBLE | float64 |
+| INT | int32 |
+| BYTE | uint8 |
+| CHAR | numpy unicode string, copied |
+| ISO_TIME | datetime64[ns] |
+| ISO_TIME_RANGE | datetime64[ns], one extra dimension of 2 |
+
+Missing data stays raw for numeric variables (the `FILLVAL` number itself) and becomes `NaT` for
+time variables.
+
+## INCLUDE
+
+`INCLUDE = "file.ceh"` is resolved, in this order, with `include_resolver` first when given:
+
+```python
+cefast.load("file.cef", include_paths=["/data/headers"])
+cefast.load("file.cef", include_resolver=lambda name: headers.get(name))  # str or None
+```
+
+then the directory of the file being read, then `include_paths`, then the `CEFPATH` environment
+variable, then the current directory (which is what CEFLIB does).
+
+## Errors
+
+Anything that would silently produce wrong numbers raises instead:
+
+```python
+try:
+    cefast.load("broken.cef")
+except cefast.ParseError as error:
+    print(error)   # broken.cef:214: expected 31 values, got 30 (record 12)
+```
+
+`ParseError` subclasses `ValueError` and names the file, the line and, inside the data section, the
+record.
+
+## C++
+
+Header-only C++20, same API shape:
+
+```cpp
+#include <cefast/cefast.hpp>
+
+auto file = cefast::load("file.cef");
+for (const auto& var : file.variables)
+    std::cout << var.name << '\n';
+```
+
+With meson: `dependency('cefast', fallback: ['cefast', 'cefast_dep'])`.
+
+## Performance
+
+On the 41-file CSA sample corpus (10.4 MB), against CEFLIB 1.8.6, loading every file from Python
+with the default threads: **11.5 ms against 35.1 ms** (3.05x overall, median 1.60x per file).
+Every file is faster, from 1.20x to 7x. Numbers from a Ryzen 7 5800X; gzipped files are limited by
+decompression. `tools/ceflib/benchmark.py` reproduces them.
+
+Speed does not cost correctness: every float is correctly rounded (the value `strtod` gives), and a
+malformed value is an error, where CEFLIB reads `12abc` as `12`.
+
+## Tests
+
+```sh
+python -I tools/fetch_csa_corpus.py    # downloads the CSA sample corpus and verifies its hashes
+meson setup build && meson test -C build
+```
+
+The corpus is not in the repository: it is fetched from the archive and checked against
+`tests/resources/csa_manifest.json`. Tests that need it skip when it is missing.
+`tools/ceflib/benchmark.py` builds CEFLIB to compare against it; the differential test skips when
+CEFLIB is not importable.
+
+Known differences from CEFLIB and from the strict CEF 2.0 document are listed in
+[docs/accepted-deviations.md](docs/accepted-deviations.md).
+
+## License
+
+MIT, see [COPYING](COPYING).

cefast-0.1.0/README.md

@@ -0,0 +1,171 @@
+[![tests](https://github.com/SciQLop/CEFast/actions/workflows/tests.yml/badge.svg)](https://github.com/SciQLop/CEFast/actions/workflows/tests.yml)
+[![wheels](https://github.com/SciQLop/CEFast/actions/workflows/wheels.yml/badge.svg)](https://github.com/SciQLop/CEFast/actions/workflows/wheels.yml)
+[![PyPI](https://img.shields.io/pypi/v/cefast)](https://pypi.org/project/cefast/)
+[![Python versions](https://img.shields.io/pypi/pyversions/cefast)](https://pypi.org/project/cefast/)
+[![license](https://img.shields.io/badge/license-MIT-blue)](COPYING)
+
+<p align="center"><img src="docs/images/cefast_logo.png" alt="CEFast" width="600"></p>
+
+# CEFast
+
+A fast reader for CEF (Cluster Exchange Format), the text format of ESA's Cluster Science Archive.
+C++20 core, Python bindings, no dependencies beyond numpy.
+
+```sh
+pip install cefast
+```
+
+```python
+import cefast
+f = cefast.load("C1_CP_FGM_SPIN__20010201_000000_20010202_000000_V140305.cef.gz")
+f["B_vec_xyz_gse__C1_CP_FGM_SPIN"].values      # (records, 3) float32
+f["time_tags__C1_CP_FGM_SPIN"].values.dtype    # datetime64[ns]
+```
+
+## Why CEFast
+
+CEFLIB is the reference CEF reader, and it is hard to live with: source tarball only, no wheels,
+a global singleton, and no working byte variables. CEFast is
+installable with pip, free of global state, and readable by someone else.
+
+Correctness is checked, not claimed:
+
+- every CEF 2.0 construct the archive uses, checked against the specification, with the deviations
+  we accept listed in [docs/accepted-deviations.md](docs/accepted-deviations.md);
+- 41 real CSA files, every one CEFLIB can read compared value by value against CEFLIB 1.8.6,
+  plus hand-made files for malformed input;
+- the full suite runs under ASan and UBSan in CI, together with an allocation budget test for the
+  header path;
+- libFuzzer targets run in CI, each comparing a fast path with a slow reference: serial against
+  parallel loading, the float parser against `strtod`, the fixed-width time parser against the
+  general one, the header lexer and the record scanner against frozen copies of the simpler code
+  they replaced;
+- a malformed file raises a `ParseError` naming the file, the line and the record: it never returns
+  shifted columns or garbage.
+
+## Install
+
+```sh
+pip install cefast
+```
+
+Wheels are built for Linux (x86_64, aarch64), macOS 13+ (x86_64, arm64) and Windows (x64,
+ARM64), for CPython 3.10 and newer, including free-threaded builds. A Pyodide (wasm32) wheel is
+built too. Elsewhere, `pip install` builds from the sdist with a C++20 compiler and meson.
+
+## Loading
+
+```python
+cefast.load("file.cef")            # path or os.PathLike
+cefast.load("file.cef.gz")         # gzip, detected from the content
+cefast.load(data)                  # bytes, bytearray or memoryview
+```
+
+`threads=0` (the default) picks a thread count from the machine, `threads=1` parses serially,
+`threads=N` uses at most N. Data sections above ~48 KiB are split across threads; the result is
+identical either way.
+
+Loading releases the GIL. A path is memory-mapped, or read when the platform has no mmap, and bytes
+are borrowed: the returned arrays are views on that memory, valid as long as the `CEF` object and
+its variables live.
+
+## Variables
+
+```python
+f.keys()                           # names, in file order
+"B_vec_xyz_gse__C1_CP_FGM_SPIN" in f
+v = f["B_vec_xyz_gse__C1_CP_FGM_SPIN"]
+v.name, v.value_type               # 'B_vec_xyz_gse__C1_CP_FGM_SPIN', 'FLOAT'
+v.sizes                            # (3,), the CEF SIZES attribute
+v.is_nrv                           # True when the values are in the header (DATA), not per record
+v.attributes                       # dict of the other variable attributes
+f.attributes                       # dict of the global attributes
+```
+
+Attribute values are plain Python values: text and numbers come as one value or a list, times as
+`datetime.datetime`, time ranges as a pair of them.
+
+Values are numpy arrays. Record-varying variables get a record axis, header variables keep their
+declared shape.
+
+| CEF VALUE_TYPE | numpy dtype |
+| --- | --- |
+| FLOAT | float32 |
+| DOUBLE | float64 |
+| INT | int32 |
+| BYTE | uint8 |
+| CHAR | numpy unicode string, copied |
+| ISO_TIME | datetime64[ns] |
+| ISO_TIME_RANGE | datetime64[ns], one extra dimension of 2 |
+
+Missing data stays raw for numeric variables (the `FILLVAL` number itself) and becomes `NaT` for
+time variables.
+
+## INCLUDE
+
+`INCLUDE = "file.ceh"` is resolved, in this order, with `include_resolver` first when given:
+
+```python
+cefast.load("file.cef", include_paths=["/data/headers"])
+cefast.load("file.cef", include_resolver=lambda name: headers.get(name))  # str or None
+```
+
+then the directory of the file being read, then `include_paths`, then the `CEFPATH` environment
+variable, then the current directory (which is what CEFLIB does).
+
+## Errors
+
+Anything that would silently produce wrong numbers raises instead:
+
+```python
+try:
+    cefast.load("broken.cef")
+except cefast.ParseError as error:
+    print(error)   # broken.cef:214: expected 31 values, got 30 (record 12)
+```
+
+`ParseError` subclasses `ValueError` and names the file, the line and, inside the data section, the
+record.
+
+## C++
+
+Header-only C++20, same API shape:
+
+```cpp
+#include <cefast/cefast.hpp>
+
+auto file = cefast::load("file.cef");
+for (const auto& var : file.variables)
+    std::cout << var.name << '\n';
+```
+
+With meson: `dependency('cefast', fallback: ['cefast', 'cefast_dep'])`.
+
+## Performance
+
+On the 41-file CSA sample corpus (10.4 MB), against CEFLIB 1.8.6, loading every file from Python
+with the default threads: **11.5 ms against 35.1 ms** (3.05x overall, median 1.60x per file).
+Every file is faster, from 1.20x to 7x. Numbers from a Ryzen 7 5800X; gzipped files are limited by
+decompression. `tools/ceflib/benchmark.py` reproduces them.
+
+Speed does not cost correctness: every float is correctly rounded (the value `strtod` gives), and a
+malformed value is an error, where CEFLIB reads `12abc` as `12`.
+
+## Tests
+
+```sh
+python -I tools/fetch_csa_corpus.py    # downloads the CSA sample corpus and verifies its hashes
+meson setup build && meson test -C build
+```
+
+The corpus is not in the repository: it is fetched from the archive and checked against
+`tests/resources/csa_manifest.json`. Tests that need it skip when it is missing.
+`tools/ceflib/benchmark.py` builds CEFLIB to compare against it; the differential test skips when
+CEFLIB is not importable.
+
+Known differences from CEFLIB and from the strict CEF 2.0 document are listed in
+[docs/accepted-deviations.md](docs/accepted-deviations.md).
+
+## License
+
+MIT, see [COPYING](COPYING).