add a check for hashable custom_info, link to new doc section

Author: bpinsard

docs/heuristics.rst

@@ -119,6 +119,19 @@ or::
         ...
         return seqinfos  # ordered dict containing seqinfo objects: list of DICOMs
 
+---------------------------------------------------------------
+``custom_seqinfo(series_files, wrapper)``
+---------------------------------------------------------------
+If present this function will be called on eacg group of dicoms with
+a sample nibabel dicom wrapper to extract additional information
+to be used in ``infotodict``.
+
+Importantly the return value of that function needs to be hashable.
+For instance the following non-hashable types can be converted to an alternative
+hashable type:
+- list > tuple
+- dict > frozendict
+- arrays > bytes (tobytes(), or pickle.dumps), str or tuple of tuples.
 
 -------------------------------
 ``POPULATE_INTENDED_FOR_OPTS``

heudiconv/dicoms.py

@@ -90,6 +90,15 @@ def create_seqinfo(
     global total_files
     total_files += len(series_files)
 
+    custom_seqinfo_data = custom_seqinfo(wrapper=mw, series_files=series_files) \
+        if custom_seqinfo else None
+    try:
+        hash(custom_seqinfo_data)
+    except TypeError:
+        raise RuntimeError("Data returned by the heuristics custom_seqinfo is not hashable. "
+                           "See https://heudiconv.readthedocs.io/en/latest/heuristics.html#custom_seqinfo for more "
+                           "details.")
+
     return SeqInfo(
         total_files_till_now=total_files,
         example_dcm_file=op.basename(series_files[0]),
@@ -119,9 +128,7 @@ def create_seqinfo(
         date=dcminfo.get("AcquisitionDate"),
         series_uid=dcminfo.get("SeriesInstanceUID"),
         time=dcminfo.get("AcquisitionTime"),
-        custom =
-            custom_seqinfo(wrapper=mw, series_files=series_files)
-            if custom_seqinfo else None,
+        custom=custom_seqinfo_data,
     )