Overload bids2table signature for specific return types

[shnizzedy]

Instead of typehinting BIDSTable | None for the return type of bids2table, this PR updates the typehinting to dynamically be BIDSTable for bids2table(return_table=True) (or unspecified, which with return_table=True by default) or None for bids2table(return_table=False).

screen-capture.webm

The functionality is the same between just a4bcf5e or both commits here. The difference is the first commit does the overload in the main file

bids2table/bids2table/_b2t.py

Lines 16 to 56 in a4bcf5e

	@overload
	def bids2table(
	root: StrOrPath,
	*,
	with_meta: bool = True,
	persistent: bool = False,
	index_path: Optional[StrOrPath] = None,
	exclude: Optional[List[str]] = None,
	incremental: bool = False,
	overwrite: bool = False,
	workers: Optional[int] = None,
	worker_id: Optional[int] = None,
	return_table: Literal[True] = True,
	) -> BIDSTable: ...
	@overload
	def bids2table(
	root: StrOrPath,
	*,
	with_meta: bool = True,
	persistent: bool = False,
	index_path: Optional[StrOrPath] = None,
	exclude: Optional[List[str]] = None,
	incremental: bool = False,
	overwrite: bool = False,
	workers: Optional[int] = None,
	worker_id: Optional[int] = None,
	return_table: Literal[False],
	) -> None: ...
	def bids2table(
	root: StrOrPath,
	*,
	with_meta: bool = True,
	persistent: bool = False,
	index_path: Optional[StrOrPath] = None,
	exclude: Optional[List[str]] = None,
	incremental: bool = False,
	overwrite: bool = False,
	workers: Optional[int] = None,
	worker_id: Optional[int] = None,
	return_table: bool = True,
	) -> Optional[BIDSTable]:

while the second commit moves the overload to a stub file for the sake of abstraction / less scrolling in the main file.

No hard feelings if you don't want this specific typehinting.