feat(torch): add torch extra and update config files

.github/workflows/ci-tests.yml

@@ -14,6 +14,7 @@ on:
       - dev/xarray
       - bugfix
       - "release/*"
+      - "dev/*"
 
 env:
   DEFAULT_PYTHON: 3.11

asv_bench/benchmarks/dataframe_schema.py

@@ -1,21 +1,9 @@
 # Airspeed Velocity Benchmarks for pandera
 import pandas as pd
 
-from pandera.pandas import (
-    Column,
-    DataFrameSchema,
-    Bool,
-    Category,
-    Check,
-    DateTime,
-    Float,
-    Int,
-    Object,
-    String,
-    Timedelta,
-    check_input,
-    check_output,
-)
+from pandera.pandas import (Bool, Category, Check, Column, DataFrameSchema,
+                            DateTime, Float, Int, Object, String, Timedelta,
+                            check_input, check_output)
 
 
 class Validate:

asv_bench/benchmarks/series_schema.py

@@ -1,21 +1,9 @@
 # Airspeed Velocity Benchmarks for pandera
 import pandas as pd
 
-from pandera.pandas import (
-    Column,
-    DataFrameSchema,
-    SeriesSchema,
-    Bool,
-    Category,
-    Check,
-    DateTime,
-    Float,
-    Int,
-    Object,
-    String,
-    Timedelta,
-    String,
-)
+from pandera.pandas import (Bool, Category, Check, Column, DataFrameSchema,
+                            DateTime, Float, Int, Object, SeriesSchema, String,
+                            Timedelta)
 
 
 class Validate:

docs/source/ibis.md

@@ -204,7 +204,11 @@ invalid_t = ibis.memtable({
     "b": ["d", "e", "f"],
     "c": [0.0, 1.1, -0.1],
 })
-ModelWithChecks.validate(invalid_t, lazy=True)
+
+try:
+    ModelWithChecks.validate(invalid_t, lazy=True)
+except pa.errors.SchemaErrors as exc:
+    print(exc)
 ```
 
 (supported-ibis-dtypes)=

docs/source/index.md

@@ -464,6 +464,7 @@ configuration
 
 supported_libraries
 xarray_guide/index
+pytorch_guide/index
 integrations
 ```
 

docs/source/pytorch_guide/error_reporting.md

@@ -0,0 +1,64 @@
+---
+file_format: mystnb
+---
+
+(pytorch-error-reporting)=
+
+# Error Reporting
+
+Pandera raises {class}`~pandera.errors.SchemaError` for individual validation failures
+and {class}`~pandera.errors.SchemaErrors` when `lazy=True`.
+
+## Non-lazy validation (fail-fast)
+
+By default, validation stops on the first error:
+
+```{code-cell} python
+import torch
+from tensordict import TensorDict
+import pandera.tensordict as pa
+
+schema = pa.TensorDictSchema(
+    keys={"x": pa.Tensor(dtype=torch.float32, shape=(None, 10))},
+    batch_size=(32,),
+)
+
+td = TensorDict({"x": torch.randn(16, 10)}, batch_size=[16])
+
+try:
+    schema.validate(td)
+except pa.errors.SchemaError as exc:
+    print(f"Error: {exc}")
+    print(f"Reason: {exc.reason_code}")
+```
+
+## Lazy validation
+
+Set `lazy=True` to collect all errors:
+
+```{code-cell} python
+td_invalid = TensorDict(
+    {"x": torch.randn(16, 10), "y": torch.randn(16, 10)},
+    batch_size=[16],
+)
+
+try:
+    schema.validate(td_invalid, lazy=True)
+except pa.errors.SchemaErrors as exc:
+    print(f"Found {len(exc.schema_errors)} errors")
+    for err in exc.schema_errors:
+        print(f"  - {str(err)}")
+    print(f"\nError counts: {exc.error_counts}")
+```
+
+## Error reason codes
+
+- `WRONG_DATATYPE` — tensor dtype mismatch
+- `COLUMN_NOT_IN_DATAFRAME` — missing key
+- `CHECK_ERROR` — value check failure
+
+## See also
+
+- {ref}`checks` — Check API
+- {ref}`pytorch-tensordict-schema` — TensorDictSchema
+- {ref}`lazy-validation` — general lazy validation guide

docs/source/pytorch_guide/index.md

@@ -0,0 +1,94 @@
+---
+file_format: mystnb
+---
+
+(pytorch-guide)=
+
+# PyTorch Tensor Data Validation
+
+[PyTorch](https://pytorch.org/) provides {class}`~torch.Tensor` objects and
+[{class}`~tensordict.TensorDict` for managing collections of tensors],
+and [{class}`~tensordict.tensorclass`][tensorclass] for typed tensor
+collections.
+
+Pandera validates them with the same patterns as the other dataframe backends:
+schema objects, optional {class}`~pandera.api.checks.Check` instances, and
+global {ref}`configuration <configuration>`.
+
+## Installation
+
+```bash
+pip install 'pandera[torch]'
+pip install tensordict
+```
+
+## Quick start
+
+```{code-cell} python
+import torch
+from tensordict import TensorDict
+import pandera.tensordict as pa
+
+schema = pa.TensorDictSchema(
+    keys={
+        "observation": pa.Tensor(dtype=torch.float32, shape=(None, 10)),
+        "action": pa.Tensor(dtype=torch.float32, shape=(None, 5)),
+    },
+    batch_size=(32,),
+)
+
+td = TensorDict(
+    {"observation": torch.randn(32, 10), "action": torch.randn(32, 5)},
+    batch_size=[32],
+)
+schema.validate(td)
+```
+
+## Define a schema with a class-based model
+
+```{code-cell} python
+class RL(pa.TensorDictModel):
+    """Schema for reinforcement learning data."""
+
+    # Use PyTorch dtypes in type annotations
+    observation: torch.float32 = pa.Field(shape=(None, 10))
+    action: torch.int64 = pa.Field(shape=(None,))
+    reward: torch.float32 = pa.Field()
+
+    class Config:
+        batch_size = (32,)
+
+# Validate using the model - schema is built automatically
+td = TensorDict(
+    {"observation": torch.randn(32, 10), "action": torch.randint(0, 4, (32,)), "reward": torch.randn(32)},
+    batch_size=[32],
+)
+RL.validate(td)
+```
+
+**Note:** Type annotations specify the dtype (e.g., `torch.float32`, `torch.int64`).
+Use {func}`~pandera.tensordict.Field` to define additional constraints like shape and checks.
+
+## Guide contents
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+tensordict_schema
+tensordict_model
+tensordict_checks
+error_reporting
+```
+
+- {ref}`pytorch-tensordict-schema` — validating a {class}`~tensordict.TensorDict` with `Tensor` components
+- {ref}`pytorch-tensordict-model` — class-based `TensorDictModel`
+- {ref}`pytorch-checks` — checks, parsers, and lazy validation
+- {ref}`pytorch-error-reporting` — `SchemaError` / `SchemaErrors`, lazy validation, and failure cases
+
+## See also
+
+- {ref}`supported-dataframe-libraries` — other backends
+- {ref}`checks` — general `Check` behaviour
+- {ref}`lazy-validation` — `lazy=True` and `SchemaErrors`
+- {ref}`configuration` — `ValidationDepth` and environment variables

docs/source/pytorch_guide/tensordict_checks.md

@@ -0,0 +1,73 @@
+---
+file_format: mystnb
+---
+
+(pytorch-checks)=
+
+# Checks and Lazy Validation
+
+Use {class}`~pandera.api.checks.Check` to validate tensor values.
+
+## Apply checks to Tensor components
+
+```{code-cell} python
+import torch
+from tensordict import TensorDict
+from pandera import Check
+import pandera.tensordict as pa
+
+schema = pa.TensorDictSchema(
+    keys={
+        "values": pa.Tensor(
+            dtype=torch.float32,
+            shape=(None,),
+            checks=[Check.greater_than(0.0), Check.less_than(1.0)],
+        ),
+    },
+    batch_size=(10,),
+)
+
+td = TensorDict(
+    {"values": torch.tensor([0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.95])},
+    batch_size=[10],
+)
+validated = schema.validate(td)
+```
+
+## Lazy validation
+
+Set `lazy=True` to collect all errors:
+
+```{code-cell} python
+td_invalid = TensorDict(
+    {"values": torch.tensor([-0.1, 0.2, 0.3, 10.0, 0.5])},
+    batch_size=[5],
+)
+
+try:
+    schema.validate(td_invalid, lazy=True)
+except pa.errors.SchemaErrors as exc:
+    print(f"Found {len(exc.schema_errors)} errors")
+    print(exc)
+```
+
+## Available checks
+
+Standard pandera checks work with tensor data:
+
+- {func}`~pandera.api.checks.Check.greater_than`
+- {func}`~pandera.api.checks.Check.less_than`
+- {func}`~pandera.api.checks.Check.greater_than_or_equal_to`
+- {func}`~pandera.api.checks.Check.less_than_or_equal_to`
+- {func}`~pandera.api.checks.Check.in_range`
+- {func}`~pandera.api.checks.Check.isin`
+- {func}`~pandera.api.checks.Check.notin`
+- {func}`~pandera.api.checks.Check.str_matches`
+- {func}`~pandera.api.checks.Check.str_contains`
+- {func}`~pandera.api.checks.Check.str_startswith`
+- {func}`~pandera.api.checks.Check.str_endswith`
+
+## See also
+
+- {ref}`checks` — full Check API reference
+- {ref}`pytorch-error-reporting` — error handling