[AdrianAtZyte]

Resolves #1044, resolves #1162

[codspeed]

Merging this PR will not alter performance

✅ 10 untouched benchmarks

---

_{Comparing AdrianAtZyte:search-dates-period (0f185ef) with master (2467be8)}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.09%. Comparing base (2f54bb0) to head (0f185ef).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1437   +/-   ##
=======================================
  Coverage   99.09%   99.09%           
=======================================
  Files         239      239           
  Lines        3988     3997    +9     
=======================================
+ Hits         3952     3961    +9     
  Misses         36       36           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[serhii73]

Code review (claude code-review, at ed46bd2; probes run on this head and on the merge-base). The new add_period option is opt-in, and I found no wrong date, so I'm approving. The branch conflicts with master, so it needs a rebase before merge. Two points to settle first:

• Undeclared change to parse(). The freshness parser now reports period time for relative expressions with an hours, minutes or seconds unit whenever RETURN_TIME_AS_PERIOD is set. DateDataParser(settings={'RETURN_TIME_AS_PERIOD': True}).get_date_data('2 hours ago') gave day on master and gives time here; in 2 hours, 5 minutes ago and hace 2 horas change the same way, and 1 week 2 hours ago changes from week to time. That may well be the more correct value, but the PR is described as search_dates only, so please add a changelog note (and mention it under RETURN_TIME_AS_PERIOD in the settings docs).
• Time-span entries always say day. With RETURN_TIME_SPAN, both the start and end entries are hard-coded to day, so a year or month span reports the wrong granularity (the PR's own test asserts day for a one-month span).

Non-blocking notes:

• add_period changes the tuple arity, together with add_detected_language, so (s, d, x) cannot be told apart by the caller and the # type: ignore[return-value] hides it from mypy. Always producing 3-tuples internally and trimming once in the public function (or a NamedTuple) would be safer; the (a, b, p) if add_period else (a, b) expression is repeated in three places.
• The split path reads date_data['period'] directly, while the ngram path has a date_obj is not None guard.
• Tests cover only English and Portuguese with one date each; a multi-date text would catch misaligned periods. The docstring still has versionadded:: VERSION.