feat: Add the file-based override source

[kinyoklion]

Summary

This is the fifth step of the flag overrides port described by the OVERRIDE specification. It is based on the events branch because the phases are stacked; retarget to feat/overrides once that branch merges.

ldclient.integrations.overrides.FileOverrideSourceBuilder is the public entry point. It is passed to datasystem.ConfigBuilder.overrides(...) and builds an override source that reads one or more local files in the file data source document format (optional flags, flagValues, and segments members, JSON or YAML) and supplies each successful load to the SDK's override sink as a full snapshot. flagValues entries expand into full flag definitions, so the layer holds only full entities; as the specification describes for a value-only override, the expansion is a flag that is on and serves its single variation as the fallthrough, so the evaluation reason kind is FALLTHROUGH. The existing file data sources keep their current behavior, including their own flagValues expansion.

Behavior:

• Files are combined in the configured order. duplicate_keys_handling is fail by default, which rejects the reload and keeps the previously loaded overrides, or ignore, which keeps the first configured file's entry.
• A configured file that does not exist contributes no overrides and is not an error: it can be created later, deleting a file removes its overrides, and deleting the last file clears the layer.
• Change detection is in place before the initial load, so a change made between the two is not missed.
• A file that exists but cannot be read or parsed fails that whole reload. The last good overrides stay in effect, the failure is logged, and the load is retried after a bounded delay and on the next detected change, so a file observed mid-write recovers on its own.
• change_detection is one of two alternatives. polling (the default) compares modification time and size on an interval, one second by default with a one second minimum; a lower interval is raised to the minimum with a warning, and a value that is not a finite number, or longer than the runtime can wait, is a construction error. watching uses the watchdog package and is a construction error when the package is not installed. Notifications are debounced so a burst from one edit produces one reload.
• The initial load runs synchronously inside start, which the data system calls during client construction, so an override present at startup takes effect from the first evaluation.
• Every applied change is logged at Info level, for example Flag overrides in effect: 2 flags, 1 segment (/etc/ld/a.json: 2 flags, 1 segment; /etc/ld/b.json: absent), or Flag overrides: none in effect (...).
• A builder with no paths is a construction error. Unknown change_detection or duplicate_keys_handling values raise ValueError when set. This is stricter than the Go builder, which treats an unrecognized duplicate keys handling as fail.

The module is added to the API reference (docs/api-integrations.rst) and every public docstring carries the experimental note.

Tests cover the builder validation and defaults, synchronous initial load, YAML, multi-file order and duplicate handling, absent files appearing and disappearing, the Info log lines, both change detection modes, last-good retention across a malformed edit in both modes, the automatic retry with no change signal, close semantics, and an end-to-end run through LDClient where a file is added, changed, and emptied while the client never receives LaunchDarkly data.

SDK-3250

---

Note

Overview
Adds an experimental file-based flag override source so operators can force flag/segment values from local JSON or YAML without restarting the app or reaching LaunchDarkly. The public entry point is FileOverrideSourceBuilder, wired through datasystem.ConfigBuilder.overrides(...).

The source merges one or more files (same format as the file data source, including flagValues expansion), applies full snapshots to the override sink, and reloads on file changes via polling (default, 1s minimum) or optional watchdog watching. Missing files contribute nothing; bad parses or duplicate keys (default fail) keep the last good snapshot and retry. Info logs summarize what is in effect per file. API docs cover ldclient.integrations.overrides.

Tests cover builder validation, merge/absent-file behavior, both change-detection modes, failure retention/retry, lifecycle/close, and an LDClient flow where overrides are added, changed, and cleared live.

^{Reviewed by Cursor Bugbot for commit cfb781a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[kinyoklion]

bugbot review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit cfb781a. Configure here.}