feat: warn that payload filtering has no effect with FDv2

[beekld]

Documents and warns that payload_filter_key has no effect when the FDv2 data system is used.

Closes SDK-2973.

• Config.payload_filter_key / AsyncConfig.payload_filter_key docs now state payload filtering is unsupported with FDv2
• FDv2 data system logs a warning at construction when a filter key is configured
• FDv1 behavior is unchanged; the shared option is not deprecated, since FDv1 still supports it

Requirements

• I have added test coverage for new or changed functionality
• I have followed the repository's pull request submission guidelines
• I have validated my changes against all supported platform versions

Related issues

SDK-2973, part of SDK-2575. Same change as java-core#209 and go-server-sdk#440, adapted for the shared option.

Implementation details

Unlike Go and Java, Python has no FDv2-specific filter setter — payload_filter_key is a top-level option shared by FDv1 and FDv2 — so it cannot be deprecated at the language level without also deprecating supported FDv1 usage. Instead the docstrings call out the FDv2 limitation and FDv2.__init__ warns once when the option is set.

The FDv2 data sources still append ?filter= to /sdk/poll and /sdk/stream requests. That is intentional for now: on the delivery side, FDv2 (internal/fdcore in streamer) reads the filter query param only for observability (fdrequest.Info.HasPayloadFilter, surfaced as a dogfood context attribute) and never uses it to select a payload, so the parameter is inert rather than harmful. Dropping it would also break the environment_filter_key contract-test scenarios that the pinned harness (v3.0.0-alpha.6) still runs, requiring suppressions until the harness pin is bumped past sdk-test-harness#431. Removing the parameter belongs with that bump in the removal phase.

Testing: make lint, make test (1420 passed).

Link to Devin session: https://app.devin.ai/sessions/ed604c6db94d452ea9f2dc35d6acc398
Open in Devin Desktop: https://app.devin.ai/desktop/session/ed604c6db94d452ea9f2dc35d6acc398?variant=devin
Requested by: @beekld

---

Note

Overview
Clarifies that payload_filter_key still applies to default FDv1 streaming/polling, but does not filter FDv2 payloads.

Config and AsyncConfig docstrings (constructor param and payload_filter_key property) now state that filtering is unsupported with the FDv2 data system. FDv2 and AsyncFDv2 emit a one-time warning at construction when a filter key is set, without changing runtime behavior or deprecating the shared option for FDv1.

Tests assert the warning appears when a filter key is configured and is absent when it is not, for both sync and async FDv2.

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

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[jsonbailey]

Can you rebase or merge in main to your branch. Its out of date and missing the async fdv2 file where this warning should also be added.

[devin-ai-integration]

Merged main in and added the same warning (plus tests) to AsyncFDv2.__init__ in ldclient/impl/datasystem/async_fdv2.py. The AsyncConfig.payload_filter_key docs were already updated in the original commit.