Use pathlib.Path instead of os.path to handle files and folders

[mscheltienne]

The MNE codebase uses a mix of strings (with the help of os.path) and pathlib.Path objects to handle files and folders.
I believe it would be beneficial to move to pathlib.Path objects entirely.

Summary of the PR here.

---

Current list of tests and associated functions incompatible with Path objects:

test_transforms: 
	::test_fs_xfm
	387: xfm, kind = _read_fs_xfm(str(fname))
	393: xfm_read, kind_read = _read_fs_xfm(str(fname_out))
	399: xfm_read, kind_read = _read_fs_xfm(str(fname_out))
	406: _read_fs_xfm(str(fname_out))
	409: _read_fs_xfm(str(fname_out))

viz/_brain/test_brain
	::test_brain_init
	319: brain.add_label(str(fname_label))
	435: brain.add_annotation(str(annots[-1]))
	442: brain.add_annotation(str(a), b, p, color=color)

report/test_report
	::test_open_report
	Not sure what is failing when hdf5, .fname and .subjects_dir are Path. 
	Probably requires those 2 last attributes to load Path from disk.

	::test_scraper
	719: block_vars = dict(image_path_iterator=(img for img in [str(img_fname)]),
                               example_globals=dict(a=1), target_file=target_file)
               -> impacts L723: rshe 'destination' argument of maxwell_filtert = scraper(block, block_vars, gallery_conf)

viz/_brain/test_notebook
	::test_notebook_interactive
        88: brain._renderer.actions['movie_field'].value = str(movie_path)
        89: brain._renderer.actions['screenshot_field'].value = str(screenshot_path)

[drammock]

Yes please do! It's been planned to switch entirely to pathlib but nobody had the time so far

[mscheltienne]

Great, the first step is perfect for when I'm out of energy and don't want to think too hard ;)
I'll continue this PR little by little.

[mscheltienne]

Note about this change:

When writing a src, the field "mri_volume_name" could be a Path which can not be encoded to "latin1".
IMO, it is safer to cast to string before writing than to chase every case where something else than a string might be provided to write_string.

If reverted, a test in tests/test_source_space will break, so we can always fix this issue differently if we want to.

[drammock]

agreed that casting to str before write operations is the correct fix. I think I've hit this problem before (and obviously didn't fix it everywhere 😉).

[larsoner]

The MPL deprecations should be fixed/worked around by #11497, but this one does seem related:

/home/circleci/project/tutorials/inverse/80_brainstorm_phantom_elekta.py failed leaving traceback:
Traceback (most recent call last):
  File "/home/circleci/project/tutorials/inverse/80_brainstorm_phantom_elekta.py", line 94, in <module>
    mne.viz.plot_alignment(
  File "<decorator-gen-122>", line 12, in plot_alignment
  File "/home/circleci/project/mne/viz/_3d.py", line 780, in plot_alignment
    _plot_mri_fiducials(renderer, mri_fiducials, subjects_dir, subject,
  File "/home/circleci/project/mne/viz/_3d.py", line 1033, in _plot_mri_fiducials
    fid_loc = _fiducial_coords(mri_fiducials, FIFF.FIFFV_COORD_MRI)
  File "/home/circleci/project/mne/viz/_3d.py", line 65, in _fiducial_coords
    points = [p for p in points if p['coord_frame'] == coord_frame]
TypeError: 'PosixPath' object is not iterable

probably something somewhere does not look for path-like but instead str for a filename...

[mscheltienne]

Looks like it's all green, modulo #11497. A quick summary of the changes:

Occurrences of os.path in mne-python/mne:

• on main: 364 matches in 213 files
• on this PR: 187 matches in 88 files

Changes:

• Use pathlib instead of os.path in the tests files. The exceptions are:
  • mne/io/tests/test_constants.py
  • mne/io/eeglab/tests/test_eeglab.py
  • mne/utils/tests/test_testing.py
  • mne/datasets/sleep_physionet/tests/test_physionet.py
  • mne/viz/tests/test_scraper.py
• Cast to string before writing a string FIFF tag. c.f. this comment.
• Fixes incompatibilities with Path in:
  • destination argument of maxwell_filter
  • I/O for layouts, add argument overwrite=False for Layout.save()
  • head_pos argument of simulate_raw
  • EGI evoked reader read_evokeds_mff
  • src argument of plot_bem
  • mri_fiducials argument of plot_alignment
  • hsp, elp and mrk argument of the KIT reader
  • events argument of the EpochsEEGLAB reader
• Change the behavior of _check_fname, _find_trans and get_subjects_dir that now return a Path instead of a string.

Especially for _check_fname and get_subjects_dir, I either:

• in small functions, refactored/adapted the code to work with Path
• in large functions where the variable was extensively used OR in long chain of functions OR when I was not confident about the change, I converted the value back to string retaining the legacy behavior.

Examples can be found by searching for str(_check_fname( e.g. https://github.com/mscheltienne/mne-python/blob/b1facb9076c9afb3eee3f52f8414eef801f649ad/mne/source_estimate.py#L250

And that should be a good stopping point for this PR 😄

[larsoner]

I took a cursory look at the code and it looks reasonable. Your choices also sound good to me. CIs were green before I merged main into your branch. I'll merge now with [circle deploy] and we can make sure CircleCI agrees things are all good here. Thanks for this big effort and progress @mscheltienne !

[hoechenberger]

Super nice. Thanks @mscheltienne

[agramfort]

whoooot 200 files changes 🚀

[hoechenberger]

I believe we forgot a changelog entry – @mscheltienne could you add one?

[mscheltienne]

@hoechenberger Done in #11499, but I made it very general and did not include cross-ref to the different functions now compatible with Paths.