feat: expose client readiness for local evaluation

VJ
3h ago
+67-0

Summary

When the initial environment-document fetch fails, applications using local evaluation cannot tell whether evaluating a flag will use the local document or fall back to the remote API. Add a non-blocking Flagsmith.ready() check so callers can use their own fallback until the background poller has loaded a document.

  • Local and offline clients are ready when an environment document is available. A failed refresh leaves the last successful document usable and readiness stays true.
  • Remote-evaluation clients are immediately ready; this is not an API connectivity or freshness check.
  • Readiness makes no requests and does not alter evaluation or fallback semantics. The README shows how to guard evaluations to avoid per-evaluation remote fallback during an initial outage. Changing fallback behavior automatically would break existing callers, so this takes the explicit readiness-API approach requested in the issue.

Fixes #197

Verification

  • The three new tests fail on unchanged upstream because ready() is absent.
  • pytest -q: 381 passed, including initial fetch failure, recovery, subsequent refresh failure, remote evaluation and offline evaluation.
  • mypy --strict .: passed, 33 source files.
  • Configured Black, isort and Flake8 checks passed for both changed Python files.
  • git diff --check: passed.

Validated on Python 3.12.13 / Windows using the repository's declared dependency ranges. AI assistance was used to implement and test this contribution.