fix(tsfile): install tsfile only in py3.14 CI and add Hub example

.github/workflows/ci.yml

@@ -121,6 +121,8 @@ jobs:
         run: pip install --upgrade uv
       - name: Install dependencies
         run: uv pip install --system "datasets[tests] @ ."
+      - name: Install tsfile (py3.14 only)
+        run: uv pip install --system "tsfile>=2.3.0"
       - name: Print dependencies
         run: uv pip list
       - name: Test with pytest

docs/source/tsfile_load.mdx

@@ -54,6 +54,34 @@ Map files to splits explicitly:
 ... )
 ```
 
+## Example dataset on the Hub
+
+A ready-to-use example is available at [`tsfile/lotsa_data`](https://huggingface.co/datasets/tsfile/lotsa_data). Because `.tsfile` files are recognized automatically, you can load it by repository id without specifying `data_files`:
+
+```py
+>>> from datasets import load_dataset
+>>> dataset = load_dataset("tsfile/lotsa_data")
+>>> dataset
+DatasetDict({
+    train: Dataset({
+        features: ['timeseries_id', 'time', 'value'],
+        num_rows: 91
+    })
+})
+```
+
+Each row is one device. The TAG column `timeseries_id` identifies the device, while `time` and `value` are `list<...>` columns holding that device's full series:
+
+```py
+>>> row = dataset["train"][0]
+>>> row["timeseries_id"]
+'Bear_assembly_Angel'
+>>> len(row["time"]), len(row["value"])
+(8760, 8760)
+>>> row["time"][:3]
+[datetime.datetime(2017, 1, 1, 0, 0), datetime.datetime(2017, 1, 1, 1, 0), datetime.datetime(2017, 1, 1, 2, 0)]
+```
+
 ## Selecting a table
 
 A TsFile can contain multiple tables. When `table_name` is omitted, the first table found in the first valid file is used. Lookups are case-insensitive.

setup.py

@@ -183,7 +183,6 @@
     "torch>=2.8.0",
     "torchdata",
     "transformers>=4.42.0",  # Pins numpy < 2
-    "tsfile>=2.3.0",
     "zstandard",
     "polars[timezone]>=0.20.0",
     "Pillow>=9.4.0",  # When PIL.Image.ExifTags was introduced

tests/packaged_modules/test_tsfile.py

@@ -8,13 +8,20 @@
 
 import pyarrow as pa
 import pytest
-from tsfile import ColumnCategory, ColumnSchema, TableSchema, Tablet, TsFileWriter
-from tsfile.constants import TSDataType
 
-from datasets import IterableDataset, load_dataset
-from datasets.builder import InvalidConfigName
-from datasets.data_files import DataFilesList
-from datasets.packaged_modules.tsfile.tsfile import TsFileConfig, _to_epoch
+
+# `tsfile` requires pyarrow<20 for python<3.14, which conflicts with datasets'
+# pyarrow>=21.0.0. It is therefore only installed in the py3.14 CI. Skip this
+# whole module (at collection time) when tsfile is not importable.
+pytest.importorskip("tsfile")
+
+from tsfile import ColumnCategory, ColumnSchema, TableSchema, Tablet, TsFileWriter  # noqa: E402
+from tsfile.constants import TSDataType  # noqa: E402
+
+from datasets import IterableDataset, load_dataset  # noqa: E402
+from datasets.builder import InvalidConfigName  # noqa: E402
+from datasets.data_files import DataFilesList  # noqa: E402
+from datasets.packaged_modules.tsfile.tsfile import TsFileConfig, _to_epoch  # noqa: E402
 
 
 # ---------------------------------------------------------------------------