Repository navigation
Conversation
Request /flags?v=3 from the sync and async clients and keep each flag's typed value, structured reason and metadata on the parsed record. - A record with a value member is a v3 record. A record without one comes from an older server: its value is variant, or enabled without one, and its config version is 1. - A known field with the wrong JSON type fails only that record with PARSE_ERROR; unknown fields are ignored. - Legacy getters, callbacks and $feature_flag_called keep reading the legacy rendering, now derived from value in one place: a string is the variant, null is disabled, and a number or object is enabled with the value as a JSON-encoded payload. - evaluate_flags() snapshots gain get_boolean/string/number/object_value and _details accessors. They never coerce and return the caller default for missing, failed, null and mismatched values.
A v3 record for a flag in the new format carries no experiment ID: an experiment is linked to its rule on the server, by rule ID. A complete experiment split is config version 2, reason experiment_split, rule type experiment, a rule ID and a variant key. - Remove experiment_id from FlagMetadata. An experiment_id key in a record is now ignored like any other unknown metadata key, whatever its type. - The vendored harness 1.13.1 fixtures still carry the field. Two reader cases that depend on it are overridden in the test until the fixtures are re-pinned to a contract without it.
A v3 record carries no holdout ID: holdouts in the new format are local to their rule and have no ID, and older records never sent one. A holdout result is identified by its rule ID and the reason holdout. - Remove holdout_id from FlagMetadata. A holdout_id key in a record is now ignored like any other unknown metadata key, whatever its type. - The vendored harness 1.13.1 fixtures still send the field. No reader case depends on it; the producer-response test skips it, like experiment_id, until the fixtures are re-pinned to a contract without it.
Clients already send v=3 and arbitrary v values, so the server selects the typed record only for an exact v=4. Request v=4 and name the record after it in tests, docstrings and the changeset. A server that answers v=4 with the older record (enabled/variant, no value) is still read the same way.
Align the evaluate_flags() typed accessors with the typed flag values API proposed in PostHog/sdk-specs#104. - FlagEvaluationDetails has an OpenFeature reason (FlagEvaluationReason) and a flag_metadata dict of the record's id, version, config_version, reason_code, condition_index, rule_type, rule_id and variant_key. It no longer carries the structured reason or the metadata object, so the payload stays on the payload accessors. - variant is set only when the accessor returns the flag's value. - Locally evaluated flags read with config_version 1 and a reason derived from the value, or DISABLED for an inactive flag. - Each client logs once when /flags sends records without typed values, and a TYPE_MISMATCH message says why the value was not returned. - Add get_integer_value/details and get_float_value/details. Object values are returned as copies. - Re-vendor the rules v2 contract fixtures from posthog-sdk-test-harness 1.22.0 (contract 7.0.0). A config version 1 record may carry an integer metadata.experiment_id, so its type is checked; it is not kept.
The adapter sends /flags?v=4, so it declares flags_response_v4. A harness that knows the capability runs flags_request_uses_v4_query_param in place of the ?v=2 check; older harness releases ignore it.
# Conflicts: # posthog/client.py # posthog/feature_flag_evaluations.py
Keep reading the /flags?v=4 response and retaining each flag's typed value, reason and metadata, with the existing getters derived from the value. Drop the public typed accessors (get_boolean_value/_details and the string, number, integer, float and object forms), FlagEvaluationDetails, FlagEvaluationReason and FlagEvaluationErrorCode, and the error code and message fields on FeatureFlag that only they read. They return in a separate change once the cross-SDK accessor API is agreed.
Add get_boolean_value, get_string_value, get_number_value, get_integer_value, get_float_value and get_object_value to the evaluate_flags() snapshot, each with a _details form that returns a FlagEvaluationDetails with an OpenFeature reason, error_code and flag_metadata. The accessors never coerce: they return the caller default when the flag is missing, failed, has no value, or has a value of another type.
![posthog[bot]](https://avatars.githubusercontent.com/in/1203049?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
PostHog Review · Standard · reviewed 3f8c315: 2 Should fix.
This is the only automatic review while this pull request is a draft. Comment @posthog review to review new changes sooner. Otherwise, a review of the new changes runs when you mark it ready for review.
See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.
Comment on lines
+611
to
+613
| "object": lambda value: ( | ||
| copy.deepcopy(value) if isinstance(value, dict) else _NOT_ACCEPTED | ||
| ), |
Contributor
There was a problem hiding this comment.
P2 · Handle recursion failures when copying object flag values
A valid JSON object nested 600 levels deep passes FeatureFlag.from_json, but copy.deepcopy exceeds Python's default recursion limit. Both get_object_value and get_object_details then propagate RecursionError into application code instead of returning a safe result, defeating the accessor's fallback behavior. Use an iterative copy or handle copy failures with the caller default.
Comment on lines
+745
to
+747
| id=metadata.id, | ||
| version=metadata.version, | ||
| config_version=metadata.config_version, |
Contributor
There was a problem hiding this comment.
P2 · Preserve absent metadata fields in evaluation details
When a typed record omits metadata.id or metadata.version, or sets either to null, parsing replaces it with 0. _resolve_flag_details then exposes that fabricated value in flag_metadata, violating the documented presence contract and giving consumers an identifier or version the server never supplied. Preserve field absence through parsing and omit those entries.
Contributor
posthog-python Compliance ReportDate: 2026-11-03T13:13:58.861124+00:00 ✅ All Tests Passed!121/121 tests passed Capture_V1 Tests✅ 95/95 tests passed View Details
Capture_Ai Tests✅ 5/5 tests passed View Details
Feature_Flags Tests✅ 17/17 tests passed View Details
Feature_Flags_Local_Evaluation Tests✅ 4/4 tests passed View Details
|
5 tasks done
The integer accessors reject numbers beyond 2**53 - 1 in magnitude, such as 1e21, so every SDK returns the same result for the same flag. A test also pins that a throwing before_send does not break a typed read.
A record without a typed value now has its known fields type-checked like a /flags?v=4 record, so a wrong-typed field fails only that flag instead of the whole response. A key member of the wrong type fails its record; the map key stays the flag key. An unreadable record keeps the field that failed it, apart from a record the server marks failed.
A record without metadata.id or metadata.version no longer reads them as 0. Events already left out a falsy ID and version, so their properties do not change.
A /flags?v=4 record with a number or object value exposes that value as its payload, even when the record also sends a payload. Other payloads are kept as sent.
# Conflicts: # posthog/test/test_flags_v4_response.py # posthog/types.py # references/public_api_snapshot.txt
The object accessors copy the value so a caller cannot change the snapshot. A value nested deeply enough made that copy raise RecursionError; it now returns the caller default with PARSE_ERROR, so a typed read never throws.
A value nested too deeply for json.dumps used to abort the whole response. Also test an empty-string reason, and the async client with unreadable and sparse records beside a healthy one. The changeset now says which results can differ from before.
…t/flags-typed-accessors # Conflicts: # posthog/test/test_flags_v4_response.py
get_flags_decision() returns FeatureFlag and FlagMetadata, so public fields could be adopted before the typed flag API is settled. The typed accessors make them public.
#1031 keeps the v4 value and rule metadata fields private. The typed accessors make them public, so this branch keeps them public and the changeset lists them.
5 tasks done
… into feat/flags-typed-accessors
…d accessors Every typed value and details accessor on the evaluate_flags() snapshot now takes the keyword-only send_feature_flag_events option that is_enabled() and get_flag() take. With send_feature_flag_events=False the read sends no $feature_flag_called and leaves the dedupe cache alone, so a later read that sends events still reports the flag. The key still counts as accessed for only_accessed(). The value form passes the option to its details form, so both forms behave the same.
Typed details of a locally evaluated flag left the flag version out of flag_metadata. The local flag definition carries the version, but the evaluate_flags() snapshot record set it to None. The record now takes the version from the definition, and the details add it to flag_metadata when it is present. The record change is the same one #1149 makes, so $feature_flag_called for a snapshot read of a locally evaluated flag also carries $feature_flag_version.
…ccessor Numbers are IEEE-754 doubles in every PostHog SDK. get_number_value and get_number_details returned an integer beyond 2**53 - 1 in magnitude exactly, so Python could return a value JavaScript cannot. They now return the nearest float. Integers within range keep their int type, the integer accessors keep TYPE_MISMATCH beyond the range, and the float accessors are unchanged. An integer too large for any double is a TYPE_MISMATCH, as in the float accessor.
A typed accessor that resolves to TYPE_MISMATCH returned the caller's default and still sent $feature_flag_called, which took the dedupe slot, so the later read of the right type sent nothing. A read of the wrong type is a bug in the calling code, not a use of the flag. It now sends no event and takes no dedupe slot, so the next read of the right type, or a get_flag() or is_enabled() read, reports the flag. The client logs the error_message once per flag key and requested type, in a cache bounded like the flag-event dedupe. The read still counts as accessed for only_accessed(). A false or null value read as another type, missing, failed and unreadable flags, and reads with send_feature_flag_events=False are unchanged.
The float accessor returned TYPE_MISMATCH for an integer too large to convert to a float, and the number accessor followed it. JavaScript parses such a number as an infinity, the nearest IEEE-754 double. Both accessors now return that infinity, with its sign, so every PostHog SDK reads the same value. The integer accessors keep TYPE_MISMATCH.
… state Move the client's record of logged type mismatches next to _logged_untyped_flags_response, the other once-per-client flag log state, in both clients.
…ields The typed value, failure flags and rule metadata were declared as dataclass fields, so repr, equality, hashing, dataclasses.asdict and the generated SDK reference showed them. Keep them as instance attributes with class-level defaults instead, import FeatureFlag privately in the snapshot module, and say in the changeset that the details stay internal.
A /flags record with a known field of the wrong type reads as disabled. The single-flag getter cached that result, replacing the last good value, so a later failed request fell back to False. An unreadable record now leaves the fallback cache alone and falls back to its value, like a failed request does; without a cached value it still reads as disabled.
FeatureFlag.from_json delegated to record parsers that always built a FeatureFlag, so a subclass calling it got a base instance. The parsers now take the class to build, for v4, older and unreadable records alike.
A snapshot kept each remotely evaluated flag twice: a flattened record and the parsed /flags record, with the payload both as its JSON text and decoded. The snapshot record now reads its fields from the parsed record and decodes the payload on its first read, then keeps it. Private record details that equal their defaults are no longer stored on each instance. Retained memory of evaluate_flags() for a /flags?v=4 response of 5,000 boolean flags (tracemalloc, Python 3.14, including JSON decoding): no payloads: 3.64 MiB -> 2.87 MiB 1 KiB JSON payload each: 28.10 MiB -> 7.95 MiB A payload that is read is decoded and kept as before, so reading every payload retains about what it did before this change.
The parity tests compare this SDK's v2 and v4 readers with each other, so a change shared by both passes. These tests compare both with results recorded once with posthog 7.82.1 for the same flags: the legacy getters, get_flags_decision, snapshot reads, $feature_flag_called properties and fallback-cache histories. Where a result differs from 7.82.1 by decision, the test says why: an absent flag ID or version reads as None, not 0, and a record with a field of the wrong type fails only itself.
A single-flag read of a record that cannot be read used to fail the whole request, so its $feature_flag_called event carried $feature_flag_error: unknown_error and no request id or evaluated-at. The read now succeeds for the other records, but this one still reports the same error and no request details, so a value served from the fallback cache stays distinguishable from a fresh one.
…t/flags-typed-accessors # Conflicts: # posthog/feature_flag_evaluations.py # posthog/test/test_feature_flag.py # posthog/test/test_flags_v4_response.py # posthog/types.py # references/public_api_snapshot.txt
…ssors # Conflicts: # posthog/async_client.py # posthog/client.py # posthog/feature_flag_evaluations.py # posthog/test/test_flags_released_behaviour.py # posthog/test/test_flags_v4_response.py # posthog/types.py # references/public_api_snapshot.txt
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Since 7.83.0 (#1031) the SDK reads the
/flags?v=4response and keeps each flag's typed value, reason and metadata, but has no accessors for reading them. Callers still cannot read a number or object flag value as such, or see why a flag returned what it did.Changes
The typed accessor API, split out of #1031 so that change could ship without new public methods:
get_boolean_value,get_string_value,get_number_value,get_integer_value,get_float_valueandget_object_valueon theevaluate_flags()snapshot, each with a_detailsform.send_feature_flag_eventsoption, with the same meaning as onis_enabled()andget_flag()(feat: add a per-read send_feature_flag_events option to snapshot reads #1148). Withsend_feature_flag_events=False, the read sends no$feature_flag_calledand leaves the dedupe cache alone, so a later read that sends events still reports the flag. The key still counts as accessed foronly_accessed(). The value form passes the option to its details form.FlagEvaluationDetails,FlagEvaluationReasonandFlagEvaluationErrorCode, with OpenFeature reasons and error codes. The accessors never coerce: they return the caller default when the flag is missing, failed, unreadable, has no value, or has a value of another type.TYPE_MISMATCH, any of the 12 methods, either client) returns the caller default with the same details as before, but sends no$feature_flag_calledand takes no dedupe slot. With feat(flags): send $experiment_exposure for v2 experiment splits #1154 that also means no$experiment_exposure. The next read of the right type, or aget_flag()oris_enabled()read, sends the event as a first read. The client logs the details'error_messageas an error once per (flag key, requested type), in a cache bounded like the flag-event dedupe cache. The read still counts as accessed foronly_accessed(), as before. Afalseornullvalue read through a non-boolean accessor, missing, failed and unreadable flags, andsend_feature_flag_events=Falsekeep their behaviour.get_number_value/get_number_detailsreturn an integer beyond2**53 - 1in magnitude as the nearestfloat, so Python returns what JavaScript does; an integer within range stays anint.get_float_valuereturns every number as the nearestfloat. An integer beyond the range of a double reads as an infinity, with its sign, through both. The integer accessors keepTYPE_MISMATCHbeyond2**53 - 1.idandversioninflag_metadata, the same values the snapshot record has taken from the definition since fix: send flag id and version on locally evaluated $feature_flag_called #1149.error_codeanderror_messageonFeatureFlag, including the cause for a flag local evaluation could not resolve.valueandfailedonFeatureFlag, andconfig_version,rule_type,rule_id,variant_keyandforced_variantonFlagMetadata.This waits for the cross-SDK accessor spec in PostHog/sdk-specs#104. Names and semantics may change to match it. #1031 and #1148 are on
main, so the diff here is only this change.Testing
test_flags_v4_response.py, for each of the 12 typed methods on the sync and the async client:send_feature_flag_events=False, the read returns the flag's value, sends no$feature_flag_calledand marks the key inonly_accessed(). A later read with the default then sends exactly one event.send_feature_flag_events=Truesends no second one.TYPE_MISMATCH, sends no$feature_flag_called, still marks the key inonly_accessed(), and logs itserror_messageonce although read twice. A later right-type read (value and details form),get_flag()oris_enabled()then sends exactly one event, on both clients. Two wrong types on one key log twice, a second snapshot from the same client logs nothing new, a read withsend_feature_flag_events=Falselogs nothing new, and another client logs again. Anullorfalsevalue read as another type, and a missing, failed or unreadable flag, still send their event and log nothing.int, and at ±253 and ±(253 + 1) thefloat±253. The integer accessor returnsTYPE_MISMATCHat ±253 and ±(253 + 1), and the float accessor returns the nearestfloatat all six. ±10**400 reads as ±infinity through the number and float accessors.test_locally_evaluated_details_carry_the_definition_version: local boolean (value and details forms) and multivariate details carry the definition'sversion, a definition without one leaves it out, and the$feature_flag_calledevent reports the same version. The test fails without either half of the change.test_flags_released_behaviour.py: results recorded with 7.82.1 still match once the fields this PR makes public are removed from each flag and its metadata. A separate test checks those fields' values, includingPARSE_ERRORfor an unreadable record andGENERALfor one the server marked failed.main: with feat(flags): send $experiment_exposure for v2 experiment splits #1154 merged in locally (not pushed), a typed read withsend_feature_flag_events=Falseon a v2 experiment split sends neither$feature_flag_callednor$experiment_exposure, as docs(flags): specify SDK-sent $experiment_exposure for config version 2 flags sdk-specs#162 asks. A later default read sends each event once. This holds for all 12 methods on both clients. The flag test modules also pass on the combined tree.$feature_flag_callednor$experiment_exposure, for each typed method on both clients, and the next right-type orget_flag()/is_enabled()read sends both. The flag test modules passed on the combined tree. The current heads of this PR and feat(flags): send $experiment_exposure for v2 experiment splits #1154 conflict only intest_flags_released_behaviour.py, where each adjusts the 7.82.1 comparison for its own change; whichever lands second combines both.pytest posthog/test: 6,253 passed, 25 skipped, withtest_metrics_autocapture.pydeselected (its forked-child tests crash on macOS in a full run, onmaintoo, and pass alone).ruff format --check,ruff check, mypy (baseline filter) and the public API snapshot check pass.🤖 Generated with Claude Code