Add return type hints to read_raw_*(), read_epochs(), `read_annot…

…ations()` (mne-tools#12296)

Co-authored-by: Eric Larson <[email protected]>

doc/conf.py

@@ -269,6 +269,27 @@
     "EOGRegression": "mne.preprocessing.EOGRegression",
     "Spectrum": "mne.time_frequency.Spectrum",
     "EpochsSpectrum": "mne.time_frequency.EpochsSpectrum",
+    "EpochsFIF": "mne.Epochs",
+    "RawBOXY": "mne.io.Raw",
+    "RawBrainVision": "mne.io.Raw",
+    "RawBTi": "mne.io.Raw",
+    "RawCTF": "mne.io.Raw",
+    "RawCurry": "mne.io.Raw",
+    "RawEDF": "mne.io.Raw",
+    "RawEEGLAB": "mne.io.Raw",
+    "RawEGI": "mne.io.Raw",
+    "RawEximia": "mne.io.Raw",
+    "RawEyelink": "mne.io.Raw",
+    "RawFIL": "mne.io.Raw",
+    "RawGDF": "mne.io.Raw",
+    "RawHitachi": "mne.io.Raw",
+    "RawKIT": "mne.io.Raw",
+    "RawNedf": "mne.io.Raw",
+    "RawNeuralynx": "mne.io.Raw",
+    "RawNihon": "mne.io.Raw",
+    "RawNIRX": "mne.io.Raw",
+    "RawPersyst": "mne.io.Raw",
+    "RawSNIRF": "mne.io.Raw",
     # dipy
     "dipy.align.AffineMap": "dipy.align.imaffine.AffineMap",
     "dipy.align.DiffeomorphicMap": "dipy.align.imwarp.DiffeomorphicMap",
@@ -367,34 +388,12 @@
     "n_moments",
     "n_patterns",
     "n_new_events",
-    # Undocumented (on purpose)
-    "RawKIT",
-    "RawEximia",
-    "RawEGI",
-    "RawEEGLAB",
-    "RawEDF",
-    "RawCTF",
-    "RawBTi",
-    "RawBrainVision",
-    "RawCurry",
-    "RawNIRX",
-    "RawNeuralynx",
-    "RawGDF",
-    "RawSNIRF",
-    "RawBOXY",
-    "RawPersyst",
-    "RawNihon",
-    "RawNedf",
-    "RawHitachi",
-    "RawFIL",
-    "RawEyelink",
     # sklearn subclasses
     "mapping",
     "to",
     "any",
     # unlinkable
     "CoregistrationUI",
-    "IntracranialElectrodeLocator",
     "mne_qt_browser.figure.MNEQtBrowser",
     # pooch, since its website is unreliable and users will rarely need the links
     "pooch.Unzip",
@@ -779,8 +778,12 @@ def append_attr_meth_examples(app, what, name, obj, options, lines):
     ("py:class", "None.  Remove all items from od."),
 ]
 nitpick_ignore_regex = [
-    ("py:.*", r"mne\.io\.BaseRaw.*"),
-    ("py:.*", r"mne\.BaseEpochs.*"),
+    # Classes whose methods we purposefully do not document
+    ("py:.*", r"mne\.io\.BaseRaw.*"),  # use mne.io.Raw
+    ("py:.*", r"mne\.BaseEpochs.*"),  # use mne.Epochs
+    # Type hints for undocumented types
+    ("py:.*", r"mne\.io\..*\.Raw.*"),  # RawEDF etc.
+    ("py:.*", r"mne\.epochs\.EpochsFIF.*"),
     (
         "py:obj",
         "(filename|metadata|proj|times|tmax|tmin|annotations|ch_names|compensation_grade|filenames|first_samp|first_time|last_samp|n_times|proj|times|tmax|tmin)",

mne/annotations.py

@@ -1150,7 +1150,9 @@ def _write_annotations_txt(fname, annot):
 
 
 @fill_doc
-def read_annotations(fname, sfreq="auto", uint16_codec=None, encoding="utf8"):
+def read_annotations(
+    fname, sfreq="auto", uint16_codec=None, encoding="utf8"
+) -> Annotations:
     r"""Read annotations from a file.
 
     This function reads a ``.fif``, ``.fif.gz``, ``.vmrk``, ``.amrk``,
@@ -1183,7 +1185,7 @@ def read_annotations(fname, sfreq="auto", uint16_codec=None, encoding="utf8"):
 
     Returns
     -------
-    annot : instance of Annotations | None
+    annot : instance of Annotations
         The annotations.
 
     Notes

mne/epochs.py

@@ -3850,7 +3850,7 @@ def _read_one_epoch_file(f, tree, preload):
 
 
 @verbose
-def read_epochs(fname, proj=True, preload=True, verbose=None):
+def read_epochs(fname, proj=True, preload=True, verbose=None) -> "EpochsFIF":
     """Read epochs from a fif file.
 
     Parameters

mne/io/artemis123/artemis123.py

@@ -23,7 +23,7 @@
 @verbose
 def read_raw_artemis123(
     input_fname, preload=False, verbose=None, pos_fname=None, add_head_trans=True
-):
+) -> "RawArtemis123":
     """Read Artemis123 data as raw object.
 
     Parameters

mne/io/boxy/boxy.py

@@ -15,7 +15,7 @@
 
 
 @fill_doc
-def read_raw_boxy(fname, preload=False, verbose=None):
+def read_raw_boxy(fname, preload=False, verbose=None) -> "RawBOXY":
     """Reader for an optical imaging recording.
 
     This function has been tested using the ISS Imagent I and II systems

mne/io/bti/bti.py

@@ -1435,7 +1435,7 @@ def read_raw_bti(
     eog_ch=("E63", "E64"),
     preload=False,
     verbose=None,
-):
+) -> "RawBTi":
     """Raw object from 4D Neuroimaging MagnesWH3600 data.
 
     .. note::

mne/io/cnt/cnt.py

@@ -174,7 +174,7 @@ def read_raw_cnt(
     header="auto",
     preload=False,
     verbose=None,
-):
+) -> "RawCNT":
     """Read CNT data as raw object.
 
     .. Note::

mne/io/ctf/ctf.py

@@ -33,7 +33,7 @@
 @fill_doc
 def read_raw_ctf(
     directory, system_clock="truncate", preload=False, clean_names=False, verbose=None
-):
+) -> "RawCTF":
     """Raw object from CTF directory.
 
     Parameters
@@ -55,11 +55,6 @@ def read_raw_ctf(
     -------
     raw : instance of RawCTF
         The raw data.
-        See :class:`mne.io.Raw` for documentation of attributes and methods.
-
-    See Also
-    --------
-    mne.io.Raw : Documentation of attributes and methods of RawCTF.
 
     Notes
     -----

mne/io/curry/curry.py

@@ -542,7 +542,7 @@ def _read_annotations_curry(fname, sfreq="auto"):
 
 
 @verbose
-def read_raw_curry(fname, preload=False, verbose=None):
+def read_raw_curry(fname, preload=False, verbose=None) -> "RawCurry":
     """Read raw data from Curry files.
 
     Parameters

mne/io/edf/edf.py

@@ -1567,7 +1567,7 @@ def read_raw_edf(
     encoding="utf8",
     *,
     verbose=None,
-):
+) -> RawEDF:
     """Reader function for EDF and EDF+ files.
 
     Parameters
@@ -1701,7 +1701,7 @@ def read_raw_bdf(
     encoding="utf8",
     *,
     verbose=None,
-):
+) -> RawEDF:
     """Reader function for BDF files.
 
     Parameters
@@ -1828,7 +1828,7 @@ def read_raw_gdf(
     include=None,
     preload=False,
     verbose=None,
-):
+) -> RawGDF:
     """Reader function for GDF files.
 
     Parameters

mne/io/eeglab/eeglab.py

@@ -293,7 +293,7 @@ def read_raw_eeglab(
     uint16_codec=None,
     montage_units="auto",
     verbose=None,
-):
+) -> "RawEEGLAB":
     r"""Read an EEGLAB .set file.
 
     Parameters

mne/io/egi/egi.py

@@ -104,7 +104,7 @@ def read_raw_egi(
     preload=False,
     channel_naming="E%d",
     verbose=None,
-):
+) -> "RawEGI":
     """Read EGI simple binary as raw object.
 
     .. note:: This function attempts to create a synthetic trigger channel.

mne/io/eximia/eximia.py

@@ -13,7 +13,7 @@
 
 
 @fill_doc
-def read_raw_eximia(fname, preload=False, verbose=None):
+def read_raw_eximia(fname, preload=False, verbose=None) -> "RawEximia":
     """Reader for an eXimia EEG file.
 
     Parameters

mne/io/eyelink/eyelink.py

@@ -28,7 +28,7 @@ def read_raw_eyelink(
     find_overlaps=False,
     overlap_threshold=0.05,
     verbose=None,
-):
+) -> "RawEyelink":
     """Reader for an Eyelink ``.asc`` file.
 
     Parameters

mne/io/fieldtrip/fieldtrip.py

@@ -20,7 +20,7 @@
 )
 
 
-def read_raw_fieldtrip(fname, info, data_name="data"):
+def read_raw_fieldtrip(fname, info, data_name="data") -> RawArray:
     """Load continuous (raw) data from a FieldTrip preprocessing structure.
 
     This function expects to find single trial raw data (FT_DATATYPE_RAW) in

mne/io/fiff/raw.py

@@ -502,7 +502,7 @@ def _check_entry(first, nent):
 @fill_doc
 def read_raw_fif(
     fname, allow_maxshield=False, preload=False, on_split_missing="raise", verbose=None
-):
+) -> Raw:
     """Reader function for Raw FIF data.
 
     Parameters

mne/io/fil/fil.py

@@ -25,7 +25,9 @@
 
 
 @verbose
-def read_raw_fil(binfile, precision="single", preload=False, *, verbose=None):
+def read_raw_fil(
+    binfile, precision="single", preload=False, *, verbose=None
+) -> "RawFIL":
     """Raw object from FIL-OPMEG formatted data.
 
     Parameters

mne/io/hitachi/hitachi.py

@@ -17,7 +17,7 @@
 
 
 @fill_doc
-def read_raw_hitachi(fname, preload=False, verbose=None):
+def read_raw_hitachi(fname, preload=False, verbose=None) -> "RawHitachi":
     """Reader for a Hitachi fNIRS recording.
 
     Parameters

mne/io/kit/kit.py

@@ -913,7 +913,7 @@ def read_raw_kit(
     allow_unknown_format=False,
     standardize_names=False,
     verbose=None,
-):
+) -> RawKIT:
     r"""Reader function for Ricoh/KIT conversion to FIF.
 
     Parameters

mne/io/nedf/nedf.py

@@ -202,7 +202,7 @@ def _convert_eeg(chunks, n_eeg, n_tot):
 
 
 @verbose
-def read_raw_nedf(filename, preload=False, verbose=None):
+def read_raw_nedf(filename, preload=False, verbose=None) -> "RawNedf":
     """Read NeuroElectrics .nedf files.
 
     NEDF file versions starting from 1.3 are supported.

mne/io/neuralynx/neuralynx.py

@@ -14,7 +14,7 @@
 @fill_doc
 def read_raw_neuralynx(
     fname, *, preload=False, exclude_fname_patterns=None, verbose=None
-):
+) -> "RawNeuralynx":
     """Reader for Neuralynx files.
 
     Parameters

mne/io/nicolet/nicolet.py

@@ -19,7 +19,7 @@
 @fill_doc
 def read_raw_nicolet(
     input_fname, ch_type, eog=(), ecg=(), emg=(), misc=(), preload=False, verbose=None
-):
+) -> "RawNicolet":
     """Read Nicolet data as raw object.
 
     ..note:: This reader takes data files with the extension ``.data`` as an

mne/io/nihon/nihon.py

@@ -24,7 +24,7 @@ def _ensure_path(fname):
 
 
 @fill_doc
-def read_raw_nihon(fname, preload=False, verbose=None):
+def read_raw_nihon(fname, preload=False, verbose=None) -> "RawNihon":
     """Reader for an Nihon Kohden EEG file.
 
     Parameters

mne/io/nirx/nirx.py

@@ -34,7 +34,9 @@
 
 
 @fill_doc
-def read_raw_nirx(fname, saturated="annotate", preload=False, verbose=None):
+def read_raw_nirx(
+    fname, saturated="annotate", preload=False, verbose=None
+) -> "RawNIRX":
     """Reader for a NIRX fNIRS recording.
 
     Parameters

mne/io/nsx/nsx.py

@@ -88,7 +88,7 @@
 @fill_doc
 def read_raw_nsx(
     input_fname, stim_channel=True, eog=None, misc=None, preload=False, *, verbose=None
-):
+) -> "RawNSX":
     """Reader function for NSx (Blackrock Microsystems) files.
 
     Parameters

mne/io/persyst/persyst.py

@@ -18,7 +18,7 @@
 
 
 @fill_doc
-def read_raw_persyst(fname, preload=False, verbose=None):
+def read_raw_persyst(fname, preload=False, verbose=None) -> "RawPersyst":
     """Reader for a Persyst (.lay/.dat) recording.
 
     Parameters

mne/io/snirf/_snirf.py

@@ -21,7 +21,9 @@
 
 
 @fill_doc
-def read_raw_snirf(fname, optode_frame="unknown", preload=False, verbose=None):
+def read_raw_snirf(
+    fname, optode_frame="unknown", preload=False, verbose=None
+) -> "RawSNIRF":
     """Reader for a continuous wave SNIRF data.
 
     .. note:: This reader supports the .snirf file type only,

pyproject.toml

@@ -295,10 +295,10 @@ ignore_messages = "^.*(Unknown target name|Undefined substitution referenced)[^`
 [tool.mypy]
 ignore_errors = true
 scripts_are_modules = true
-strict = true
+strict = false
 
 [[tool.mypy.overrides]]
-module = ['mne.evoked', 'mne.io']
+module = ['mne.annotations', 'mne.epochs', 'mne.evoked', 'mne.io']
 ignore_errors = false
 # Ignore "attr-defined" until we fix stuff like:
 # - BunchConstNamed: '"BunchConstNamed" has no attribute "FIFFB_EVOKED"'