flagsmith-common 3.2.1__tar.gz → 3.4.0__tar.gz

{flagsmith_common-3.2.1 → flagsmith_common-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flagsmith-common
-Version: 3.2.1
+Version: 3.4.0
 Summary: Flagsmith's common library
 Author: Matthew Elwell, Gagan Trivedi, Kim Gustyr, Zach Aysan, Francesco Lo Franco, Rodrigo López Dato, Evandro Myller, Wadii Zaim
 License-Expression: BSD-3-Clause
@@ -21,6 +21,7 @@ Requires-Dist: prometheus-client>=0.0.16 ; extra == 'common-core'
 Requires-Dist: psycopg2-binary>=2.9,<3 ; extra == 'common-core'
 Requires-Dist: requests ; extra == 'common-core'
 Requires-Dist: simplejson>=3,<4 ; extra == 'common-core'
+Requires-Dist: simplejson ; extra == 'flagsmith-schemas'
 Requires-Dist: typing-extensions ; extra == 'flagsmith-schemas'
 Requires-Dist: flagsmith-flag-engine>6 ; extra == 'flagsmith-schemas'
 Requires-Dist: backoff>=2.2.1,<3.0.0 ; extra == 'task-processor'
@@ -80,6 +81,26 @@ This enables the `route` label for Prometheus HTTP metrics.
 
 5. To enable the `/metrics` endpoint, set the `PROMETHEUS_ENABLED` setting to `True`.
 
+### Pre-commit hooks
+
+This repo provides a [`flagsmith-lint-tests`](.pre-commit-hooks.yaml) hook that enforces test conventions:
+
+- **FT001**: No module-level `Test*` classes — use function-based tests
+- **FT002**: No `import unittest` / `from unittest import TestCase` — use pytest (`unittest.mock` is fine)
+- **FT003**: Test names must follow `test_{subject}__{condition}__{expected}`
+- **FT004**: Test bodies must contain `# Given`, `# When`, and `# Then` comments
+
+To use in your repo, add to `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://github.com/Flagsmith/flagsmith-common
+  rev: main
+  hooks:
+    - id: flagsmith-lint-tests
+```
+
+Use `# noqa: FT003` (or any code) inline to suppress individual violations.
+
 ### Test tools
 
 #### Fixtures

{flagsmith_common-3.2.1 → flagsmith_common-3.4.0}/README.md

@@ -35,6 +35,26 @@ This enables the `route` label for Prometheus HTTP metrics.
 
 5. To enable the `/metrics` endpoint, set the `PROMETHEUS_ENABLED` setting to `True`.
 
+### Pre-commit hooks
+
+This repo provides a [`flagsmith-lint-tests`](.pre-commit-hooks.yaml) hook that enforces test conventions:
+
+- **FT001**: No module-level `Test*` classes — use function-based tests
+- **FT002**: No `import unittest` / `from unittest import TestCase` — use pytest (`unittest.mock` is fine)
+- **FT003**: Test names must follow `test_{subject}__{condition}__{expected}`
+- **FT004**: Test bodies must contain `# Given`, `# When`, and `# Then` comments
+
+To use in your repo, add to `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://github.com/Flagsmith/flagsmith-common
+  rev: main
+  hooks:
+    - id: flagsmith-lint-tests
+```
+
+Use `# noqa: FT003` (or any code) inline to suppress individual violations.
+
 ### Test tools
 
 #### Fixtures

{flagsmith_common-3.2.1 → flagsmith_common-3.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flagsmith-common"
-version = "3.2.1"
+version = "3.4.0"
 description = "Flagsmith's common library"
 requires-python = ">=3.11,<4.0"
 dependencies = []
@@ -26,6 +26,7 @@ optional-dependencies = { test-tools = [
     "django-health-check",
     "prometheus-client (>=0.0.16)",
 ], flagsmith-schemas = [
+    "simplejson",
     "typing_extensions",
     "flagsmith-flag-engine>6",
 ] }
@@ -59,12 +60,14 @@ Repository = "https://github.com/flagsmith/flagsmith-common"
 
 [project.scripts]
 flagsmith = "common.core.main:main"
+flagsmith-lint-tests = "common.lint_tests:main"
 
 [project.entry-points.pytest11]
 flagsmith-test-tools = "common.test_tools.plugin"
 
 [dependency-groups]
 dev = [
+    "diff-cover>=10.2.0",
     "dj-database-url (>=2.3.0, <3.0.0)",
     "django-stubs (>=5.1.3, <6.0.0)",
     "djangorestframework-stubs (>=3.15.3, <4.0.0)",

{flagsmith_common-3.2.1 → flagsmith_common-3.4.0}/src/common/core/templates/docgen-metrics.md

@@ -6,7 +6,9 @@ sidebar_position: 20
 
 ## Prometheus
 
-To enable the Prometheus `/metrics` endpoint, set the `PROMETHEUS_ENABLED` environment variable to `true`. 
+To enable the Prometheus `/metrics` endpoint, set the `PROMETHEUS_ENABLED` environment variable to `true`.
+
+When enabled, Flagsmith serves the `/metrics` endpoint on port 9100.
 
 The metrics provided by Flagsmith are described below.
 

{flagsmith_common-3.2.1 → flagsmith_common-3.4.0}/src/common/gunicorn/conf.py

@@ -4,6 +4,7 @@ This module is used as a default configuration file for Gunicorn.
 It is used to correctly support Prometheus metrics in a multi-process environment.
 """
 
+import os
 import typing
 
 from prometheus_client.multiprocess import mark_process_dead
@@ -13,6 +14,15 @@ if typing.TYPE_CHECKING:  # pragma: no cover
     from gunicorn.workers.base import Worker  # type: ignore[import-untyped]
 
 
-def worker_exit(server: "Arbiter", worker: "Worker") -> None:
+def when_ready(server: "Arbiter") -> None:
+    """Start the standalone Prometheus metrics server after Gunicorn is ready."""
+    prometheus_enabled = os.getenv("PROMETHEUS_ENABLED", "")
+    if prometheus_enabled.lower() == "true":  # Django settings are not available
+        from common.gunicorn.metrics_server import start_metrics_server
+
+        start_metrics_server()
+
+
+def child_exit(server: "Arbiter", worker: "Worker") -> None:
     """Detach the process Prometheus metrics collector when a worker exits."""
     mark_process_dead(worker.pid)  # type: ignore[no-untyped-call]

flagsmith_common-3.4.0/src/common/gunicorn/metrics_server.py

@@ -0,0 +1,65 @@
+"""
+Standalone Prometheus metrics HTTP server.
+
+This module provides a separate HTTP server for Prometheus metrics,
+independent of the main Gunicorn application server. This improves
+metrics reliability under high API load.
+
+The server runs in a daemon thread and serves metrics from the shared
+PROMETHEUS_MULTIPROC_DIR directory.
+"""
+
+import logging
+import os
+import threading
+
+from prometheus_client import CollectorRegistry, start_http_server
+from prometheus_client.multiprocess import MultiProcessCollector
+
+logger = logging.getLogger(__name__)
+
+METRICS_SERVER_PORT = 9100
+
+_server_started = False
+_server_lock = threading.Lock()
+
+
+def get_multiprocess_registry() -> CollectorRegistry:
+    """Create a registry configured for multiprocess metric collection."""
+    registry = CollectorRegistry()
+    MultiProcessCollector(registry)  # type: ignore[no-untyped-call]
+    return registry
+
+
+def start_metrics_server(
+    port: int = METRICS_SERVER_PORT,
+) -> None:
+    """
+    Start the standalone Prometheus metrics HTTP server.
+
+    This function is idempotent - calling it multiple times will only
+    start one server. The server runs in a daemon thread.
+
+    Args:
+        port: The port to serve metrics on. Defaults to 9100.
+    """
+    global _server_started
+
+    with _server_lock:
+        if _server_started:
+            logger.debug("Metrics server already started")
+            return
+
+        prometheus_multiproc_dir = os.environ.get("PROMETHEUS_MULTIPROC_DIR")
+        if not prometheus_multiproc_dir:
+            logger.warning("PROMETHEUS_MULTIPROC_DIR not set, skipping metrics server")
+            return
+
+        registry = get_multiprocess_registry()
+
+        try:
+            start_http_server(port=port, registry=registry)
+            _server_started = True
+            logger.info("Prometheus metrics server started on port %d", port)
+        except OSError as e:
+            logger.error("Failed to start metrics server on port %d: %s", port, e)

flagsmith_common-3.4.0/src/common/lint_tests.py

@@ -0,0 +1,279 @@
+"""Linter for Flagsmith test conventions.
+
+Enforces:
+- FT001: No module-level class Test* (function-only tests)
+- FT002: No `import unittest` / `from unittest import TestCase` (unittest.mock is fine)
+- FT003: Test name must have exactly 2 `__` separators: test_{subject}__{condition}__{expected}
+- FT004: Test body must contain # Given, # When, and # Then comments
+
+Output format matches ruff/flake8/mypy: {file}:{line}:{col}: {code} {message}
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import re
+import sys
+from pathlib import Path
+from typing import NamedTuple
+
+UNITTEST_BANNED_IMPORTS = frozenset(
+    {"TestCase", "TestSuite", "TestLoader", "TextTestRunner"}
+)
+
+
+class Violation(NamedTuple):
+    file: str
+    line: int
+    col: int
+    code: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.file}:{self.line}:{self.col}: {self.code} {self.message}"
+
+
+def _has_fixture_decorator(node: ast.FunctionDef) -> bool:
+    for decorator in node.decorator_list:
+        if isinstance(decorator, ast.Attribute) and decorator.attr == "fixture":
+            return True
+        if isinstance(decorator, ast.Name) and decorator.id == "fixture":
+            return True
+        # Handle @pytest.fixture(...)
+        if (
+            isinstance(decorator, ast.Call)
+            and isinstance(decorator.func, ast.Attribute)
+            and decorator.func.attr == "fixture"
+        ):
+            return True
+        if (
+            isinstance(decorator, ast.Call)
+            and isinstance(decorator.func, ast.Name)
+            and decorator.func.id == "fixture"
+        ):
+            return True
+    return False
+
+
+_COMMENT_RE = re.compile(r"#(.*)$")
+
+
+def _extract_comments(source: str) -> dict[int, str]:
+    """Return a mapping of line number (1-based) -> comment text."""
+    comments: dict[int, str] = {}
+    for lineno, line in enumerate(source.splitlines(), start=1):
+        match = _COMMENT_RE.search(line)
+        if match:
+            comments[lineno] = "#" + match.group(1)
+    return comments
+
+
+_NOQA_RE = re.compile(r"#\s*noqa\b(?::\s*(?P<codes>[A-Z0-9,\s]+))?")
+
+
+def _is_noqa_suppressed(comment: str, code: str) -> bool:
+    """Check if a comment contains a noqa directive that suppresses the given code."""
+    match = _NOQA_RE.search(comment)
+    if not match:
+        return False
+    codes_str = match.group("codes")
+    # Bare noqa (without specific codes) suppresses everything
+    if codes_str is None:
+        return True
+    codes = {c.strip() for c in codes_str.split(",")}
+    return code in codes
+
+
+def check_ft001(tree: ast.Module, filepath: str) -> list[Violation]:
+    """FT001: Module-level class Test* detected."""
+    violations = []
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, ast.ClassDef) and node.name.startswith("Test"):
+            violations.append(
+                Violation(
+                    file=filepath,
+                    line=node.lineno,
+                    col=node.col_offset + 1,
+                    code="FT001",
+                    message=f"Module-level test class `{node.name}` detected; use function-based tests",
+                )
+            )
+    return violations
+
+
+def check_ft002(tree: ast.Module, filepath: str) -> list[Violation]:
+    """FT002: import unittest / from unittest import TestCase etc. (NOT unittest.mock)."""
+    violations = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                # Flag `import unittest` but not `import unittest.mock`
+                if alias.name == "unittest":
+                    violations.append(
+                        Violation(
+                            file=filepath,
+                            line=node.lineno,
+                            col=node.col_offset + 1,
+                            code="FT002",
+                            message="`import unittest` is not allowed; use pytest instead",
+                        )
+                    )
+        elif isinstance(node, ast.ImportFrom):
+            if node.module == "unittest":
+                for alias in node.names:
+                    if alias.name in UNITTEST_BANNED_IMPORTS:
+                        violations.append(
+                            Violation(
+                                file=filepath,
+                                line=node.lineno,
+                                col=node.col_offset + 1,
+                                code="FT002",
+                                message=f"`from unittest import {alias.name}` is not allowed; use pytest instead",
+                            )
+                        )
+    return violations
+
+
+def check_ft003(tree: ast.Module, filepath: str) -> list[Violation]:
+    """FT003: Test name doesn't follow test_{subject}__{condition}__{expected} convention."""
+    violations = []
+    for node in ast.iter_child_nodes(tree):
+        if (
+            isinstance(node, ast.FunctionDef)
+            and node.name.startswith("test_")
+            and not _has_fixture_decorator(node)
+        ):
+            # Strip `test_` prefix and count `__` separators
+            after_prefix = node.name[5:]
+            parts = after_prefix.split("__")
+            if len(parts) != 3:
+                violations.append(
+                    Violation(
+                        file=filepath,
+                        line=node.lineno,
+                        col=node.col_offset + 1,
+                        code="FT003",
+                        message=f"Test name `{node.name}` doesn't match `test_{{subject}}__{{condition}}__{{expected}}` (found {len(parts)} parts, expected 3)",
+                    )
+                )
+    return violations
+
+
+def _find_missing_gwt(func_comments: list[str]) -> list[str]:
+    """Return list of missing Given/When/Then keywords from comments."""
+    has_given = False
+    has_when = False
+    has_then = False
+    for text in func_comments:
+        normalized = text.lstrip("#").strip().lower()
+        if normalized.startswith("given"):
+            has_given = True
+            # "Given / When" satisfies both
+            if "when" in normalized:
+                has_when = True
+        if normalized.startswith("when"):
+            has_when = True
+            # "When / Then" satisfies both
+            if "then" in normalized:
+                has_then = True
+        if normalized.startswith("then"):
+            has_then = True
+
+    missing = []
+    if not has_given:
+        missing.append("Given")
+    if not has_when:
+        missing.append("When")
+    if not has_then:
+        missing.append("Then")
+    return missing
+
+
+def check_ft004(
+    tree: ast.Module, filepath: str, comments: dict[int, str]
+) -> list[Violation]:
+    """FT004: Missing # Given, # When, or # Then comments in test body."""
+    violations = []
+    for node in ast.iter_child_nodes(tree):
+        if (
+            isinstance(node, ast.FunctionDef)
+            and node.name.startswith("test_")
+            and not _has_fixture_decorator(node)
+        ):
+            func_comments = [
+                text
+                for line_no, text in comments.items()
+                if node.lineno <= line_no <= (node.end_lineno or node.lineno)
+            ]
+            missing = _find_missing_gwt(func_comments)
+            if missing:
+                violations.append(
+                    Violation(
+                        file=filepath,
+                        line=node.lineno,
+                        col=node.col_offset + 1,
+                        code="FT004",
+                        message=f"Test `{node.name}` is missing GWT comments: {', '.join(missing)}",
+                    )
+                )
+    return violations
+
+
+def lint_file(filepath: str) -> list[Violation]:
+    """Run all checks on a single file."""
+    path = Path(filepath)
+
+    # Only check test_*.py files
+    if not (path.name.startswith("test_") and path.suffix == ".py"):
+        return []
+
+    source = path.read_text(encoding="utf-8")
+    try:
+        tree = ast.parse(source, filename=filepath)
+    except SyntaxError:
+        return [
+            Violation(
+                file=filepath,
+                line=1,
+                col=1,
+                code="FT000",
+                message="Could not parse file (SyntaxError)",
+            )
+        ]
+
+    comments = _extract_comments(source)
+
+    violations = []
+    violations.extend(check_ft001(tree, filepath))
+    violations.extend(check_ft002(tree, filepath))
+    violations.extend(check_ft003(tree, filepath))
+    violations.extend(check_ft004(tree, filepath, comments))
+
+    # Filter out violations suppressed by noqa comments
+    return [
+        v
+        for v in violations
+        if v.line not in comments or not _is_noqa_suppressed(comments[v.line], v.code)
+    ]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Lint Flagsmith test conventions",
+    )
+    parser.add_argument("files", nargs="*", help="Files to check")
+    args = parser.parse_args(argv)
+
+    has_errors = False
+    for filepath in args.files:
+        violations = lint_file(filepath)
+        for v in violations:
+            has_errors = True
+            print(v)
+
+    return 1 if has_errors else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

{flagsmith_common-3.2.1 → flagsmith_common-3.4.0}/src/flagsmith_schemas/dynamodb.py

@@ -20,6 +20,7 @@ from flagsmith_schemas.types import (
     DynamoFloat,
     DynamoInt,
     FeatureType,
+    JsonGzipped,
     UUIDStr,
 )
 
@@ -200,7 +201,7 @@ class Webhook(TypedDict):
     """Secret used to sign webhook payloads."""
 
 
-class _EnvironmentFields(TypedDict):
+class _EnvironmentBaseFields(TypedDict):
     """Common fields for Environment documents."""
 
     name: NotRequired[str]
@@ -208,13 +209,11 @@ class _EnvironmentFields(TypedDict):
     updated_at: NotRequired[DateTimeStr | None]
     """Last updated timestamp. If not set, current timestamp should be assumed."""
 
-    project: Project
-    """Project-specific data for this environment."""
-    feature_states: list[FeatureState]
-    """List of feature states representing the environment defaults."""
-
     allow_client_traits: NotRequired[bool]
-    """Whether the SDK API should allow clients to set traits for this environment. Identical to project-level's `persist_trait_data` setting. Defaults to `True`."""
+    """Whether the SDK API should allow clients to set traits for this environment.
+    If set to `False`, assumes only persisted traits and traits from server-side SDKs are used in evaluation, and traits incoming from client-side SDKs are ignored.
+    Defaults to `True`.
+    """
     hide_sensitive_data: NotRequired[bool]
     """Whether the SDK API should hide sensitive data for this environment. Defaults to `False`."""
     hide_disabled_flags: NotRequired[bool | None]
@@ -240,7 +239,52 @@ class _EnvironmentFields(TypedDict):
     """Webhook configuration."""
 
 
-### Root document schemas below. Indexed fields are marked as **INDEXED** in the docstrings. ###
+class _EnvironmentV1Fields(TypedDict):
+    """Common fields for environment documents in `flagsmith_environments`."""
+
+    api_key: str
+    """Public client-side API key for the environment. **INDEXED**."""
+    id: DynamoInt
+    """Unique identifier for the environment in Core."""
+
+
+class _EnvironmentV2MetaFields(TypedDict):
+    """Common fields for environment documents in `flagsmith_environments_v2`."""
+
+    environment_id: str
+    """Unique identifier for the environment in Core. Same as `Environment.id`, but string-typed to reduce coupling with Core's type definitions **INDEXED**."""
+    environment_api_key: str
+    """Public client-side API key for the environment. **INDEXED**."""
+    document_key: Literal["_META"]
+    """The fixed document key for the environment v2 document. Always `"_META"`. **INDEXED**."""
+
+    id: DynamoInt
+    """Unique identifier for the environment in Core. Exists for compatibility with the API environment document schema."""
+
+
+class _EnvironmentBaseFieldsUncompressed(TypedDict):
+    """Common fields for uncompressed environment documents."""
+
+    project: Project
+    """Project-specific data for this environment."""
+    feature_states: list[FeatureState]
+    """List of feature states representing the environment defaults."""
+    compressed: NotRequired[Literal[False]]
+    """Either `False` or absent to indicate the data is uncompressed."""
+
+
+class _EnvironmentBaseFieldsCompressed(TypedDict):
+    """Common fields for compressed environment documents."""
+
+    project: JsonGzipped[Project]
+    """Project-specific data for this environment. **COMPRESSED**."""
+    feature_states: JsonGzipped[list[FeatureState]]
+    """List of feature states representing the environment defaults. **COMPRESSED**."""
+    compressed: Literal[True]
+    """Always `True` to indicate the data is compressed."""
+
+
+### Root document schemas below. Indexed fields are marked as **INDEXED** in the docstrings. Compressed fields are marked as **COMPRESSED**. ###
 
 
 class EnvironmentAPIKey(TypedDict):
@@ -295,33 +339,50 @@ class Identity(TypedDict):
     """Unique identifier for the identity in Core. If identity created via Core's `edge-identities` API, this can be missing or `None`."""
 
 
-class Environment(_EnvironmentFields):
+class Environment(
+    _EnvironmentBaseFieldsUncompressed,
+    _EnvironmentV1Fields,
+    _EnvironmentBaseFields,
+):
     """Represents a Flagsmith environment. Carries all necessary data for flag evaluation within the environment.
 
     **DynamoDB table**: `flagsmith_environments`
     """
 
-    api_key: str
-    """Public client-side API key for the environment. **INDEXED**."""
-    id: DynamoInt
-    """Unique identifier for the environment in Core."""
+
+class EnvironmentCompressed(
+    _EnvironmentBaseFieldsCompressed,
+    _EnvironmentV1Fields,
+    _EnvironmentBaseFields,
+):
+    """Represents a Flagsmith environment. Carries all necessary data for flag evaluation within the environment.
+    Has compressed fields.
+
+    **DynamoDB table**: `flagsmith_environments`
+    """
 
 
-class EnvironmentV2Meta(_EnvironmentFields):
+class EnvironmentV2Meta(
+    _EnvironmentBaseFieldsUncompressed,
+    _EnvironmentV2MetaFields,
+    _EnvironmentBaseFields,
+):
     """Represents a Flagsmith environment. Carries all necessary data for flag evaluation within the environment.
 
     **DynamoDB table**: `flagsmith_environments_v2`
     """
 
-    environment_id: str
-    """Unique identifier for the environment in Core. Same as `Environment.id`, but string-typed to reduce coupling with Core's type definitions **INDEXED**."""
-    environment_api_key: str
-    """Public client-side API key for the environment. **INDEXED**."""
-    document_key: Literal["_META"]
-    """The fixed document key for the environment v2 document. Always `"_META"`. **INDEXED**."""
 
-    id: DynamoInt
-    """Unique identifier for the environment in Core. Exists for compatibility with the API environment document schema."""
+class EnvironmentV2MetaCompressed(
+    _EnvironmentBaseFieldsCompressed,
+    _EnvironmentV2MetaFields,
+    _EnvironmentBaseFields,
+):
+    """Represents a Flagsmith environment. Carries all necessary data for flag evaluation within the environment.
+    Has compressed fields.
+
+    **DynamoDB table**: `flagsmith_environments_v2`
+    """
 
 
 class EnvironmentV2IdentityOverride(TypedDict):
@@ -343,3 +404,6 @@ class EnvironmentV2IdentityOverride(TypedDict):
     """The UUID for this identity, used by `edge-identities` APIs in Core. **INDEXED**."""
     feature_state: FeatureState
     """The feature state override for this identity."""
+    created_date: NotRequired[DateTimeStr]
+    """ISO 8601 creation timestamp. Note: might change between updates due to how it's written by Core.
+    """

{flagsmith_common-3.2.1 → flagsmith_common-3.4.0}/src/flagsmith_schemas/types.py

@@ -1,10 +1,25 @@
 from decimal import Decimal
-from typing import TYPE_CHECKING, Annotated, Literal, TypeAlias
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    Generic,
+    Literal,
+    SupportsBytes,
+    TypeAlias,
+    TypeVar,
+    get_args,
+)
 
 from flagsmith_schemas.constants import PYDANTIC_INSTALLED
 
 if PYDANTIC_INSTALLED:
-    from pydantic import WithJsonSchema
+    from pydantic import (
+        GetCoreSchemaHandler,
+        TypeAdapter,
+        WithJsonSchema,
+    )
+    from pydantic_core import core_schema
 
     from flagsmith_schemas.pydantic_types import (
         ValidateDecimalAsFloat,
@@ -13,6 +28,7 @@ if PYDANTIC_INSTALLED:
         ValidateStrAsISODateTime,
         ValidateStrAsUUID,
     )
+    from flagsmith_schemas.utils import json_gzip
 elif not TYPE_CHECKING:
     # This code runs at runtime when Pydantic is not installed.
     # We could use PEP 649 strings with `Annotated`, but Pydantic is inconsistent in how it parses them.
@@ -26,6 +42,39 @@ elif not TYPE_CHECKING:
     ValidateStrAsISODateTime = ...
     ValidateStrAsUUID = ...
 
+T = TypeVar("T")
+
+
+class DynamoBinary(SupportsBytes):
+    """boto3's wrapper type for bytes stored in DynamoDB."""
+
+    value: bytes | bytearray
+
+
+class JsonGzipped(DynamoBinary, Generic[T]):
+    """A gzipped JSON blob representing a value of type `T`."""
+
+    if PYDANTIC_INSTALLED:
+
+        @classmethod
+        def __get_pydantic_core_schema__(
+            cls,
+            source_type: "type[JsonGzipped[T]]",
+            handler: GetCoreSchemaHandler,
+        ) -> core_schema.CoreSchema:
+            _adapter: TypeAdapter[T] = TypeAdapter(get_args(source_type)[0])
+
+            def _validate_json_gzipped(data: Any) -> bytes:
+                return json_gzip(_adapter.validate_python(data))
+
+            # We're returning bytes here for two reasons:
+            # 1. boto3.dynamodb seems to expect bytes as input for Binary columns.
+            # 2. We want to avoid having boto3 as a dependency.
+            return core_schema.no_info_before_validator_function(
+                _validate_json_gzipped,
+                core_schema.bytes_schema(strict=False),
+            )
+
 
 DynamoInt: TypeAlias = Annotated[Decimal, ValidateDecimalAsInt]
 """An integer value stored in DynamoDB.

flagsmith_common-3.4.0/src/flagsmith_schemas/utils.py

@@ -0,0 +1,15 @@
+import gzip
+import typing
+
+import simplejson as json
+
+
+def json_gzip(value: typing.Any) -> bytes:
+    return gzip.compress(
+        json.dumps(
+            value,
+            separators=(",", ":"),
+            sort_keys=True,
+        ).encode("utf-8"),
+        mtime=0,
+    )