[dateparser] search_dates returns None if nothing is found, stubs only say list

[MajorTanya]

Hello everyone,

according to its docstring, dateparser.search.search_dates will return None if no dates could be found:
https://github.com/scrapinghub/dateparser/blob/341d3080f377c058b35ab39353940ba0f9349724/dateparser/search/__init__.py#L41
The documentation says the same (though I'd wager this is copied from the docstring):
https://dateparser.readthedocs.io/en/v1.3.0/index.html#search-for-dates-in-longer-chunks-of-text

However, the stubs show only a list type:

typeshed/stubs/dateparser/dateparser/search/__init__.pyi

Lines 9 to 24 in 64fc8ad

	@overload
	def search_dates(
	text: str,
	languages: list[str] | tuple[str, ...] | AbstractSet[str] | None,
	settings: Settings | dict[str, Any] | None,
	add_detected_language: Literal[True],
	detect_languages_function: _DetectLanguagesFunction | None = None,
	) -> list[tuple[str, datetime, str]]: ...
	@overload
	def search_dates(
	text: str,
	languages: list[str] | tuple[str, ...] | AbstractSet[str] | None = None,
	settings: Settings | dict[str, Any] | None = None,
	add_detected_language: Literal[False] = False,
	detect_languages_function: _DetectLanguagesFunction | None = None,
	) -> list[tuple[str, datetime]]: ...

Proof:

>>> from typing import reveal_type
>>> import dateparser.search
>>> result = dateparser.search.search_dates("test")
>>> reveal_type(result)
Runtime type is 'NoneType'

I'm not sure how this should be fixed so I opted for filing an issue.

Used versions:

• dateparser==1.3.0
• types-dateparser==1.3.0.20260211

[brianschubert]

it sounds like we should add None to the return type - it's a legitimate result that users should be checking for.

PR welcome!