From 35f0ef65d02af33acf55ba01fa5aa62d8697e117 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Richard=20H=C3=B6chenberger?= Date: Thu, 14 Dec 2023 22:03:44 +0100 Subject: [PATCH] Add return type hints to `read_raw_*()`, `read_epochs()`, `read_annotations()` (#12296) Co-authored-by: Eric Larson --- doc/conf.py | 51 +++++++++++++++++---------------- mne/annotations.py | 6 ++-- mne/epochs.py | 2 +- mne/io/artemis123/artemis123.py | 2 +- mne/io/boxy/boxy.py | 2 +- mne/io/bti/bti.py | 2 +- mne/io/cnt/cnt.py | 2 +- mne/io/ctf/ctf.py | 7 +---- mne/io/curry/curry.py | 2 +- mne/io/edf/edf.py | 6 ++-- mne/io/eeglab/eeglab.py | 2 +- mne/io/egi/egi.py | 2 +- mne/io/eximia/eximia.py | 2 +- mne/io/eyelink/eyelink.py | 2 +- mne/io/fieldtrip/fieldtrip.py | 2 +- mne/io/fiff/raw.py | 2 +- mne/io/fil/fil.py | 4 ++- mne/io/hitachi/hitachi.py | 2 +- mne/io/kit/kit.py | 2 +- mne/io/nedf/nedf.py | 2 +- mne/io/neuralynx/neuralynx.py | 2 +- mne/io/nicolet/nicolet.py | 2 +- mne/io/nihon/nihon.py | 2 +- mne/io/nirx/nirx.py | 4 ++- mne/io/nsx/nsx.py | 2 +- mne/io/persyst/persyst.py | 2 +- mne/io/snirf/_snirf.py | 4 ++- pyproject.toml | 4 +-- 28 files changed, 66 insertions(+), 60 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 758cb7a529a..3b544f2a03e 100644 --- a/doc/conf.py +++ b/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)", diff --git a/mne/annotations.py b/mne/annotations.py index 8a44a84f539..783ee6e1901 100644 --- a/mne/annotations.py +++ b/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 diff --git a/mne/epochs.py b/mne/epochs.py index 0ae911ac5ae..50403345e92 100644 --- a/mne/epochs.py +++ b/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 diff --git a/mne/io/artemis123/artemis123.py b/mne/io/artemis123/artemis123.py index fb7b33e5b6c..64d98c54dc2 100644 --- a/mne/io/artemis123/artemis123.py +++ b/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 diff --git a/mne/io/boxy/boxy.py b/mne/io/boxy/boxy.py index b2afe096f64..a240a1f387e 100644 --- a/mne/io/boxy/boxy.py +++ b/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 diff --git a/mne/io/bti/bti.py b/mne/io/bti/bti.py index 99a77cd2b8c..91fb2a112fd 100644 --- a/mne/io/bti/bti.py +++ b/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:: diff --git a/mne/io/cnt/cnt.py b/mne/io/cnt/cnt.py index 496ed91cd38..78bc15db580 100644 --- a/mne/io/cnt/cnt.py +++ b/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:: diff --git a/mne/io/ctf/ctf.py b/mne/io/ctf/ctf.py index 1d4970624bd..65983258db5 100644 --- a/mne/io/ctf/ctf.py +++ b/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 ----- diff --git a/mne/io/curry/curry.py b/mne/io/curry/curry.py index e5b8ce02ed3..27fdc3ce7bc 100644 --- a/mne/io/curry/curry.py +++ b/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 diff --git a/mne/io/edf/edf.py b/mne/io/edf/edf.py index 7c02642ec8f..d9a9c7f2711 100644 --- a/mne/io/edf/edf.py +++ b/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 diff --git a/mne/io/eeglab/eeglab.py b/mne/io/eeglab/eeglab.py index f4beee56119..4e9b9da1c5e 100644 --- a/mne/io/eeglab/eeglab.py +++ b/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 diff --git a/mne/io/egi/egi.py b/mne/io/egi/egi.py index 32cb71db28f..455c47ae726 100644 --- a/mne/io/egi/egi.py +++ b/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. diff --git a/mne/io/eximia/eximia.py b/mne/io/eximia/eximia.py index 0af9d9daf5d..8b85768fedc 100644 --- a/mne/io/eximia/eximia.py +++ b/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 diff --git a/mne/io/eyelink/eyelink.py b/mne/io/eyelink/eyelink.py index 196aef408b1..1eaf82500ae 100644 --- a/mne/io/eyelink/eyelink.py +++ b/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 diff --git a/mne/io/fieldtrip/fieldtrip.py b/mne/io/fieldtrip/fieldtrip.py index 8d054b076ee..bff6869e147 100644 --- a/mne/io/fieldtrip/fieldtrip.py +++ b/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 diff --git a/mne/io/fiff/raw.py b/mne/io/fiff/raw.py index f4053f88b37..1c13189f723 100644 --- a/mne/io/fiff/raw.py +++ b/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 diff --git a/mne/io/fil/fil.py b/mne/io/fil/fil.py index ea990b741de..99e2b77b2d8 100644 --- a/mne/io/fil/fil.py +++ b/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 diff --git a/mne/io/hitachi/hitachi.py b/mne/io/hitachi/hitachi.py index 0f046bb37e6..a81095712d1 100644 --- a/mne/io/hitachi/hitachi.py +++ b/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 diff --git a/mne/io/kit/kit.py b/mne/io/kit/kit.py index 88af0b2dc85..e6165a543d4 100644 --- a/mne/io/kit/kit.py +++ b/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 diff --git a/mne/io/nedf/nedf.py b/mne/io/nedf/nedf.py index c16f19d91b4..8e37cd36d54 100644 --- a/mne/io/nedf/nedf.py +++ b/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. diff --git a/mne/io/neuralynx/neuralynx.py b/mne/io/neuralynx/neuralynx.py index 06d5000fcb6..4b6dea1a339 100644 --- a/mne/io/neuralynx/neuralynx.py +++ b/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 diff --git a/mne/io/nicolet/nicolet.py b/mne/io/nicolet/nicolet.py index 37855b97054..9b5fa2b3ae5 100644 --- a/mne/io/nicolet/nicolet.py +++ b/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 diff --git a/mne/io/nihon/nihon.py b/mne/io/nihon/nihon.py index 919719f24a2..fb7855e5323 100644 --- a/mne/io/nihon/nihon.py +++ b/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 diff --git a/mne/io/nirx/nirx.py b/mne/io/nirx/nirx.py index 98d81f9c268..1fb51b50380 100644 --- a/mne/io/nirx/nirx.py +++ b/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 diff --git a/mne/io/nsx/nsx.py b/mne/io/nsx/nsx.py index 95448b1b22c..2a39efa2989 100644 --- a/mne/io/nsx/nsx.py +++ b/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 diff --git a/mne/io/persyst/persyst.py b/mne/io/persyst/persyst.py index 44334fa4555..0ef6723ba11 100644 --- a/mne/io/persyst/persyst.py +++ b/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 diff --git a/mne/io/snirf/_snirf.py b/mne/io/snirf/_snirf.py index e32b32370b3..0fc9ee246e9 100644 --- a/mne/io/snirf/_snirf.py +++ b/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, diff --git a/pyproject.toml b/pyproject.toml index c23caa13d06..39c6876e43d 100644 --- a/pyproject.toml +++ b/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"'