BUG: Fix API for candidates

[larsoner]

PR Description

So in #1083 I added return_candidates=True, but this doesn't really solve the use case. The "list all candidates" step needs to be separate from the "traverse and read all candidates", and it's not currently. This PR splits them. Now instead of doing:

fname, candidates = bids_path.find_empty_room(return_candidates=True)

you do

candidates = bids_path.get_empty_room_candidates()
fname = bids_path.find_empty_room()

And the get_empty_room_candidates does not read any files, just lists/globs filenames so should be very fast (and negligible I/O overhead).

Merge checklist

Maintainer, please confirm the following before merging.
If applicable:

• All comments are resolved
• This is not your own PR
• All CIs are happy
• PR title starts with [MRG]
• whats_new.rst is updated
• New contributors have been added to CITATION.cff
• PR description includes phrase "closes <#issue-number>"

[larsoner]

... can I make _find_matching_sidecar public as bids_path.find_matching_sidecar()? Then we could actually get the sidecar paths for stuff like this, which is nice.

[codecov]

Codecov Report

Merging #1093 (08992a3) into main (be17f5b) will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@           Coverage Diff           @@
##             main    #1093   +/-   ##
=======================================
  Coverage   95.20%   95.21%           
=======================================
  Files          24       24           
  Lines        3861     3867    +6     
=======================================
+ Hits         3676     3682    +6     
  Misses        185      185           

Impacted Files	Coverage Δ
mne_bids/path.py	97.61% <100.00%> (+0.01%)	⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[larsoner]

Okay I pushed a bids_path.find_matching_sidecar as this is something else we've wanted for mne-bids-pipeline. If these sidecar files are updated, we need to rerun steps, so it's good to be able to find the same files that mne-bids will use / look at...

[larsoner]

I changed the private _find_matching_sidecar calls in this file to use the public interface. There are other places the private function is used like test_write.py but it doesn't seem necessary to change them all here (code churn / blame obfuscation with little benefit)

[sappelhoff]

seems sensible from a top level view, and code changes look clean as well.

[agramfort]

thx @larsoner