Add reusable validators (is_ndarray, is_iso8601) and update porting guide

Create ndi.validators.is_ndarray and ndi.validators.is_iso8601 as
reusable validation functions following the MATLAB +ndi/+validators/
pattern. Update PYTHON_PORTING_GUIDE Section 4 with new subsection 4a
documenting the requirement to centralise custom validators in
ndi/validators/ rather than writing inline checks.

https://claude.ai/code/session_016oPH9EoxCLcsUSTpgN9iZp

Author: claude

PYTHON_PORTING_GUIDE.md

@@ -31,6 +31,23 @@ To replicate the robustness of the MATLAB `arguments` block, use Pydantic for al
   - MATLAB `char` or `string` → Python `str`
   - MATLAB `{member1, member2}` → Python `Literal["member1", "member2"]`
 - **Coercion:** Allow Pydantic's default behavior of casting (e.g., allowing a string `"1"` or integer `1` to satisfy a `bool` type).
+- **Arbitrary Types:** When a function accepts types that Pydantic cannot serialise natively (e.g. `numpy.ndarray`, file-like `IO[bytes]`), pass `config=ConfigDict(arbitrary_types_allowed=True)` to the decorator.
+- **Constraints:** Use `Annotated[type, pydantic.Field(...)]` to express MATLAB `arguments`-block constraints such as `mustBePositive` (`gt=0`), `mustBeNonnegative` (`ge=0`), and `mustBeInteger`.
+
+### 4a. Reusable Validators in `ndi.validators`
+
+MATLAB centralises custom validation functions in the `+ndi/+validators/` namespace.  Python must do the same in the `ndi/validators/` package.
+
+- **When to create a validator:** Any type check, format check, or constraint that appears (or is likely to appear) in more than one function should be extracted into its own module under `ndi/validators/` instead of being written inline.
+- **Naming convention:** MATLAB-originated validators keep their exact MATLAB name (e.g. `mustBeID`).  Python-specific validators that have no MATLAB counterpart use `snake_case` prefixed with a descriptive verb (e.g. `is_ndarray`, `is_iso8601`).
+- **Signature pattern:** Each validator takes a single value, raises `ValueError` on failure, and returns the validated value unchanged:
+  ```python
+  def is_ndarray(val: object) -> np.ndarray:
+      if not isinstance(val, np.ndarray):
+          raise ValueError("Input must be a numpy.ndarray")
+      return val
+  ```
+- **Registration:** Every new validator must be imported and listed in `ndi/validators/__init__.py` so it is accessible as `ndi.validators.<name>`.
 
 ## 5. Error Handling
 
@@ -85,12 +102,19 @@ Verified coverage of each MATLAB namespace against the Python port. See
 
 | MATLAB | Python | Coverage |
 |--------|--------|:--------:|
-| 11 functions | 11 functions | **100 %** |
+| 11 functions | 11 + 2 | **100 %** |
 
 All 11 MATLAB `arguments`-block validators ported 1:1 with matching
 function names.  Python equivalents accept Python types (``list`` for
 cell array, ``dict`` for struct, ``pd.DataFrame`` for table).
 
+Python adds two reusable validators with no direct MATLAB counterpart:
+
+| Python | Purpose |
+|--------|---------|
+| `is_ndarray` | Validates value is a `numpy.ndarray` |
+| `is_iso8601` | Validates string is parseable ISO 8601 |
+
 ### `ndi.util` — Fully Ported
 
 **Verified:** 2026-03-11 against `VH-Lab/NDI-matlab` branch `main`.

src/ndi/validators/__init__.py

@@ -8,6 +8,8 @@
 or via ``@pydantic.validate_call``.
 """
 
+from .is_iso8601 import is_iso8601
+from .is_ndarray import is_ndarray
 from .mustBeCellArrayOfClass import mustBeCellArrayOfClass
 from .mustBeCellArrayOfNdiSessions import mustBeCellArrayOfNdiSessions
 from .mustBeCellArrayOfNonEmptyCharacterArrays import (
@@ -23,6 +25,8 @@
 from .mustMatchRegex import mustMatchRegex
 
 __all__ = [
+    "is_iso8601",
+    "is_ndarray",
     "mustBeCellArrayOfClass",
     "mustBeCellArrayOfNdiSessions",
     "mustBeCellArrayOfNonEmptyCharacterArrays",

src/ndi/validators/is_iso8601.py

@@ -0,0 +1,43 @@
+"""
+ndi.validators.is_iso8601
+
+MATLAB equivalent: +ndi/+validators/ (custom; mirrors the ``arguments``
+block format check in ``datestamp2datetime.m``)
+
+Validates that a string is a parseable ISO 8601 datestamp.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+
+def is_iso8601(val: object) -> str:
+    """Validate that *val* is a parseable ISO 8601 datestamp string.
+
+    MATLAB equivalent: format validation in the ``arguments`` block of
+    ``ndi.util.datestamp2datetime`` (input format
+    ``'yyyy-MM-dd''T''HH:mm:ss.SSSXXX'``).
+
+    Parameters
+    ----------
+    val : object
+        The value to check.
+
+    Returns
+    -------
+    str
+        The validated string (unchanged).
+
+    Raises
+    ------
+    ValueError
+        If *val* is not a string or cannot be parsed as ISO 8601.
+    """
+    if not isinstance(val, str):
+        raise ValueError("Input must be a string.")
+    try:
+        datetime.fromisoformat(val)
+    except (ValueError, TypeError) as exc:
+        raise ValueError(f"String is not valid ISO 8601: {val!r}") from exc
+    return val

src/ndi/validators/is_ndarray.py

@@ -0,0 +1,37 @@
+"""
+ndi.validators.is_ndarray
+
+MATLAB equivalent: +ndi/+validators/ (custom; mirrors ``mustBeA(val, 'numeric')``)
+
+Validates that an input is a numpy ndarray.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def is_ndarray(val: object) -> np.ndarray:
+    """Validate that *val* is a :class:`numpy.ndarray`.
+
+    MATLAB equivalent: type checking inside ``arguments`` blocks
+    (e.g. ``mustBeA(val, 'numeric')``).
+
+    Parameters
+    ----------
+    val : object
+        The value to check.
+
+    Returns
+    -------
+    numpy.ndarray
+        The validated array (unchanged).
+
+    Raises
+    ------
+    ValueError
+        If *val* is not a ``numpy.ndarray``.
+    """
+    if not isinstance(val, np.ndarray):
+        raise ValueError("Input must be a numpy.ndarray")
+    return val