From eb3cb8eec62f18c19d955ce74a6d9f009f7d139b Mon Sep 17 00:00:00 2001 From: Matthew Keeler Date: Mon, 16 Nov 2026 16:23:00 -0500 Subject: [PATCH] docs: Explain the cached data warning from the FDv2 file data source --- ldclient/datasystem.py | 3 ++ ldclient/integrations/__init__.py | 5 +++ .../test_file_data_sources_pinned_behavior.py | 39 +++++++++++++++++++ 3 files changed, 47 insertions(+) diff --git a/ldclient/datasystem.py b/ldclient/datasystem.py index 0e36ec34..48258f8b 100644 --- a/ldclient/datasystem.py +++ b/ldclient/datasystem.py @@ -155,6 +155,9 @@ def streaming_ds_builder() -> StreamingDataSourceBuilder: def file_ds_builder(paths: List[str]) -> FileDataSourceV2Builder: """ Returns a builder for a file-based data source. + + File data has no LaunchDarkly selector, so the SDK reports it as cached data. Refer to + :func:`ldclient.integrations.Files.new_data_source_v2` for the warning that this causes. """ return FileDataSourceV2Builder(paths) diff --git a/ldclient/integrations/__init__.py b/ldclient/integrations/__init__.py index 5d49e5cb..cad6c876 100644 --- a/ldclient/integrations/__init__.py +++ b/ldclient/integrations/__init__.py @@ -459,6 +459,11 @@ def new_data_source_v2(paths: str | List[str], poll_interval: float = 1, force_p If the data source encounters any error in any file-- malformed content, a missing file, or a duplicate key-- it will not load flags from any of the files. + File data has no LaunchDarkly selector, so the SDK reports it as cached data, not as data + refreshed from LaunchDarkly. When no other source supplies data from LaunchDarkly, the first + flag evaluation logs this warning once: "Feature Flag evaluation attempted before client has + initialized - using last known values from feature store". The evaluation uses the file data. + :param paths: the paths of the source files for loading flag data. These may be absolute paths or relative to the current working directory. Files will be parsed as JSON unless the ``pyyaml`` package is installed, in which case YAML is also allowed. diff --git a/ldclient/testing/integrations/test_file_data_sources_pinned_behavior.py b/ldclient/testing/integrations/test_file_data_sources_pinned_behavior.py index 6213d69c..26387920 100644 --- a/ldclient/testing/integrations/test_file_data_sources_pinned_behavior.py +++ b/ldclient/testing/integrations/test_file_data_sources_pinned_behavior.py @@ -150,6 +150,45 @@ def test_v2_flag_values_evaluate_with_a_fallthrough_reason(tmp_path): assert detail.reason == {'kind': 'FALLTHROUGH'} +# --------------------------------------------------------------------------- +# Evaluation before the client counts as initialized +# --------------------------------------------------------------------------- + +CACHED_DATA_WARNING = "Feature Flag evaluation attempted before client has initialized - using last known values" + + +def cached_data_warnings(caplog) -> List[str]: + return [r.getMessage() for r in caplog.records if r.getMessage().startswith(CACHED_DATA_WARNING)] + + +def test_v1_evaluation_does_not_log_the_cached_data_warning(tmp_path, caplog): + path = os.path.join(str(tmp_path), 'data.json') + write_file(path, DOCUMENT) + config = Config('SDK_KEY', update_processor_class=Files.new_data_source(paths=[path]), send_events=False) + with caplog.at_level(logging.WARNING), LDClient(config) as client: + assert client.variation('flag2', user, 'default') == 'value2' + assert cached_data_warnings(caplog) == [] + + +@pytest.mark.parametrize('use_as', ['initializer', 'synchronizer', 'both']) +def test_v2_evaluation_logs_the_cached_data_warning_once(tmp_path, caplog, use_as): + # File data has no selector, so the data system reports it as cached, not refreshed. + # The first evaluation then logs the cached data warning, although the value is correct. + path = os.path.join(str(tmp_path), 'data.json') + write_file(path, DOCUMENT) + file_source = Files.new_data_source_v2(paths=[path]) + builder = custom() + if use_as in ('initializer', 'both'): + builder = builder.initializers([file_source]) + if use_as in ('synchronizer', 'both'): + builder = builder.synchronizers(file_source) + config = Config('SDK_KEY', datasystem_config=builder.build(), send_events=False) + with caplog.at_level(logging.WARNING), LDClient(config) as client: + assert client.variation('flag2', user, 'default') == 'value2' + assert client.variation('flag1', user, 'default') == 'on' + assert len(cached_data_warnings(caplog)) == 1 + + # --------------------------------------------------------------------------- # Version fallback # ---------------------------------------------------------------------------