[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. A path listed more than once is logged at warning level and the repeats are ignored; the first occurrence keeps its place in the order. Paths are compared the way the platform compares file names (os.path.normcase): without regard to case on Windows, exactly elsewhere.

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 experimental file-based flag overrides via FileOverrideSourceBuilder, wired through datasystem with overrides(...).

The source reads one or more local JSON/YAML files (same shape as the file data source: flags, flagValues, segments), merges them in path order, and pushes full snapshots to the SDK override layer on each successful load. The initial load runs synchronously in start, so startup overrides apply before the client is used; missing files contribute nothing, while read/parse failures keep the last good snapshot and retry.

Operators can choose polling (default, 1s interval with a minimum) or watchdog-based watching, plus duplicate-key handling (fail vs ignore). Each applied change logs an Info line summarizing flags/segments per file. Public API and Sphinx docs document ldclient.integrations.overrides; a large integration test suite covers builder validation, reload behavior, failure retention, and end-to-end LDClient evaluation.

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

_{Opened from termag}

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[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 99b851f. Configure here.}