flagsmith-common 3.0.0__tar.gz → 3.1.0__tar.gz

{flagsmith_common-3.0.0 → flagsmith_common-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flagsmith-common
-Version: 3.0.0
+Version: 3.1.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: typing-extensions ; extra == 'flagsmith-schemas'
 Requires-Dist: backoff>=2.2.1,<3.0.0 ; extra == 'task-processor'
 Requires-Dist: django>4,<6 ; extra == 'task-processor'
 Requires-Dist: django-health-check ; extra == 'task-processor'
@@ -36,6 +37,7 @@ Project-URL: Homepage, https://flagsmith.com
 Project-URL: Issues, https://github.com/flagsmith/flagsmith-common/issues
 Project-URL: Repository, https://github.com/flagsmith/flagsmith-common
 Provides-Extra: common-core
+Provides-Extra: flagsmith-schemas
 Provides-Extra: task-processor
 Provides-Extra: test-tools
 Description-Content-Type: text/markdown

{flagsmith_common-3.0.0 → flagsmith_common-3.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flagsmith-common"
-version = "3.0.0"
+version = "3.1.0"
 description = "Flagsmith's common library"
 requires-python = ">=3.11,<4.0"
 dependencies = []
@@ -20,12 +20,13 @@ optional-dependencies = { test-tools = [
     "psycopg2-binary (>=2.9,<3)",
     "requests",
     "simplejson (>=3,<4)",
-
 ], task-processor = [
     "backoff (>=2.2.1,<3.0.0)",
     "django (>4,<6)",
     "django-health-check",
     "prometheus-client (>=0.0.16)",
+], flagsmith-schemas = [
+    "typing_extensions",
 ] }
 authors = [
     { name = "Matthew Elwell" },
@@ -68,6 +69,7 @@ dev = [
     "djangorestframework-stubs (>=3.15.3, <4.0.0)",
     "mypy (>=1.15.0, <2.0.0)",
     "pre-commit",
+    "pydantic>=2.12.5",
     "pyfakefs (>=5.7.4, <6.0.0)",
     "pytest (>=8.3.4, <9.0.0)",
     "pytest-asyncio (>=0.25.3, <1.0.0)",
@@ -77,8 +79,8 @@ dev = [
     "pytest-httpserver (>=1.1.3, <2.0.0)",
     "pytest-mock (>=3.14.0, <4.0.0)",
     "setuptools (>=78.1.1, <79.0.0)",
-    "types-simplejson (>=3.20.0.20250326, <4.0.0)",
     "types-python-dateutil (>=2.9.0.20250516, <3.0.0)",
+    "types-simplejson (>=3.20.0.20250326, <4.0.0)",
 ]
 
 [build-system]
@@ -86,7 +88,7 @@ requires = ["uv_build>=0.9.17,<0.10.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]
-module-name = ["common", "task_processor"]
+module-name = ["common", "task_processor", "flagsmith_schemas"]
 
 [tool.coverage.report]
 # Regexes for lines to exclude from consideration

{flagsmith_common-3.0.0 → flagsmith_common-3.1.0}/src/common/test_tools/plugin.py

@@ -1,11 +1,7 @@
 from functools import partial
-from typing import Generator
+from typing import TYPE_CHECKING, Generator
 
-import prometheus_client
 import pytest
-from prometheus_client.metrics import MetricWrapperBase
-from pyfakefs.fake_filesystem import FakeFilesystem
-from pytest_django.fixtures import SettingsWrapper
 
 from common.test_tools.types import (
     AssertMetricFixture,
@@ -15,6 +11,10 @@ from common.test_tools.types import (
 )
 from task_processor.task_run_method import TaskRunMethod
 
+if TYPE_CHECKING:
+    from pyfakefs.fake_filesystem import FakeFilesystem
+    from pytest_django.fixtures import SettingsWrapper
+
 
 def pytest_addoption(parser: pytest.Parser) -> None:
     group = parser.getgroup("snapshot")
@@ -26,12 +26,14 @@ def pytest_addoption(parser: pytest.Parser) -> None:
 
 
 def assert_metric_impl() -> Generator[AssertMetricFixture, None, None]:
+    import prometheus_client
+
     registry = prometheus_client.REGISTRY
     collectors = [*registry._collector_to_names]
 
     # Reset registry state
     for collector in collectors:
-        if isinstance(collector, MetricWrapperBase):
+        if isinstance(collector, prometheus_client.metrics.MetricWrapperBase):
             collector.clear()
 
     def _assert_metric(
@@ -53,7 +55,7 @@ assert_metric = pytest.fixture(assert_metric_impl)
 
 
 @pytest.fixture()
-def saas_mode(fs: FakeFilesystem) -> Generator[None, None, None]:
+def saas_mode(fs: "FakeFilesystem") -> Generator[None, None, None]:
     from common.core.utils import is_saas
 
     is_saas.cache_clear()
@@ -65,7 +67,7 @@ def saas_mode(fs: FakeFilesystem) -> Generator[None, None, None]:
 
 
 @pytest.fixture()
-def enterprise_mode(fs: FakeFilesystem) -> Generator[None, None, None]:
+def enterprise_mode(fs: "FakeFilesystem") -> Generator[None, None, None]:
     from common.core.utils import is_enterprise
 
     is_enterprise.cache_clear()
@@ -77,7 +79,7 @@ def enterprise_mode(fs: FakeFilesystem) -> Generator[None, None, None]:
 
 
 @pytest.fixture()
-def task_processor_mode(settings: SettingsWrapper) -> None:
+def task_processor_mode(settings: "SettingsWrapper") -> None:
     settings.TASK_PROCESSOR_MODE = True
     # The setting is supposed to be set before the metrics module is imported,
     # so reload it
@@ -101,7 +103,7 @@ def flagsmith_markers_marked(
 
 @pytest.fixture(name="run_tasks")
 def run_tasks_impl(
-    settings: SettingsWrapper,
+    settings: "SettingsWrapper",
     transactional_db: None,
     task_processor_mode: None,
 ) -> RunTasksFixture:

flagsmith_common-3.1.0/src/flagsmith_schemas/constants.py

@@ -0,0 +1,4 @@
+from importlib.util import find_spec
+
+PYDANTIC_INSTALLED = find_spec("pydantic") is not None
+MAX_STRING_FEATURE_STATE_VALUE_LENGTH = 20_000

flagsmith_common-3.1.0/src/flagsmith_schemas/dynamodb.py

@@ -0,0 +1,346 @@
+"""
+The types in this module describe the Edge API's data model.
+They are used to type DynamoDB documents representing Flagsmith entities.
+
+These types can be used with Pydantic for validation and serialization
+when `pydantic` is installed.
+Otherwise, they serve as documentation for the structure of the data stored in DynamoDB.
+"""
+
+from typing import Annotated, Literal
+
+from typing_extensions import NotRequired, TypedDict
+
+from flagsmith_schemas.constants import PYDANTIC_INSTALLED
+from flagsmith_schemas.types import (
+    ConditionOperator,
+    DateTimeStr,
+    DynamoContextValue,
+    DynamoFeatureValue,
+    DynamoFloat,
+    DynamoInt,
+    FeatureType,
+    RuleType,
+    UUIDStr,
+)
+
+if PYDANTIC_INSTALLED:
+    from flagsmith_schemas.pydantic_types import (
+        ValidateIdentityFeatureStatesList,
+        ValidateMultivariateFeatureValuesList,
+    )
+
+
+class Feature(TypedDict):
+    """Represents a Flagsmith feature, defined at project level."""
+
+    id: DynamoInt
+    """Unique identifier for the feature in Core."""
+    name: str
+    """Name of the feature. Must be unique within a project."""
+    type: FeatureType
+
+
+class MultivariateFeatureOption(TypedDict):
+    """Represents a single multivariate feature option in the Flagsmith UI."""
+
+    id: NotRequired[DynamoInt | None]
+    """Unique identifier for the multivariate feature option in Core. This is used by Core UI to display the selected option for an identity override for a multivariate feature."""
+    value: DynamoFeatureValue
+    """The feature state value that should be served when this option's parent multivariate feature state is selected by the engine."""
+
+
+class MultivariateFeatureStateValue(TypedDict):
+    """Represents a multivariate feature state value.
+
+    Identity overrides are meant to hold only one of these, solely to inform the UI which option is selected for the given identity.
+    """
+
+    id: NotRequired[DynamoInt | None]
+    """Unique identifier for the multivariate feature state value in Core. Used for multivariate bucketing. If feature state created via `edge-identities` APIs in Core, this can be missing or `None`."""
+    mv_fs_value_uuid: NotRequired[UUIDStr]
+    """The UUID for this multivariate feature state value. Should be used for multivariate bucketing if `id` is `None`."""
+    percentage_allocation: DynamoFloat
+    """The percentage allocation for this multivariate feature state value. Should be between or equal to 0 and 100."""
+    multivariate_feature_option: MultivariateFeatureOption
+    """The multivariate feature option that this value corresponds to."""
+
+
+class FeatureSegment(TypedDict):
+    """Represents data specific to a segment feature override."""
+
+    priority: NotRequired[DynamoInt | None]
+    """The priority of this segment feature override. Lower numbers indicate stronger priority. If `None` or not set, the weakest priority is assumed."""
+
+
+class FeatureState(TypedDict):
+    """Used to define the state of a feature for an environment, segment overrides, and identity overrides."""
+
+    feature: Feature
+    """The feature that this feature state is for."""
+    enabled: bool
+    """Whether the feature is enabled or disabled."""
+    feature_state_value: DynamoFeatureValue
+    """The value for this feature state."""
+    django_id: NotRequired[DynamoInt | None]
+    """Unique identifier for the feature state in Core. If feature state created via Core's `edge-identities` APIs in Core, this can be missing or `None`."""
+    featurestate_uuid: NotRequired[UUIDStr]
+    """The UUID for this feature state. Should be used if `django_id` is `None`. If not set, should be generated."""
+    feature_segment: NotRequired[FeatureSegment | None]
+    """Segment override data, if this feature state is for a segment override."""
+    multivariate_feature_state_values: "NotRequired[Annotated[list[MultivariateFeatureStateValue], ValidateMultivariateFeatureValuesList]]"
+    """List of multivariate feature state values, if this feature state is for a multivariate feature.
+
+    Total `percentage_allocation` sum of the child multivariate feature state values must be less or equal to 100.
+    """
+
+
+class Trait(TypedDict):
+    """Represents a key-value pair associated with an identity."""
+
+    trait_key: str
+    """Key of the trait."""
+    trait_value: DynamoContextValue
+    """Value of the trait."""
+
+
+class SegmentCondition(TypedDict):
+    """Represents a condition within a segment rule used by Flagsmith engine."""
+
+    operator: ConditionOperator
+    """Operator to be applied for this condition."""
+    value: NotRequired[str | None]
+    """Value to be compared against in this condition. May be `None` for `IS_SET` and `IS_NOT_SET` operators."""
+    property_: NotRequired[str | None]
+    """The property (context key) this condition applies to. May be `None` for the `PERCENTAGE_SPLIT` operator.
+
+    Named `property_` to avoid conflict with Python's `property` built-in.
+    """
+
+
+class SegmentRule(TypedDict):
+    """Represents a rule within a segment used by Flagsmith engine."""
+
+    type: RuleType
+    """Type of the rule, defining how conditions are evaluated."""
+    rules: "list[SegmentRule]"
+    """Nested rules within this rule."""
+    conditions: list[SegmentCondition]
+    """Conditions that must be met for this rule, evaluated based on the rule type."""
+
+
+class Segment(TypedDict):
+    """Represents a Flagsmith segment. Carries rules, feature overrides, and segment rules."""
+
+    id: DynamoInt
+    """Unique identifier for the segment in Core."""
+    name: str
+    """Name of the segment."""
+    rules: list[SegmentRule]
+    """List of rules within the segment."""
+    feature_states: list[FeatureState]
+    """List of segment overrides."""
+
+
+class Organisation(TypedDict):
+    """Represents data about a Flagsmith organisation. Carries settings necessary for an SDK API operation."""
+
+    id: DynamoInt
+    """Unique identifier for the organisation in Core."""
+    name: str
+    """Organisation name."""
+    feature_analytics: NotRequired[bool]
+    """Whether the SDK API should log feature analytics events for this organisation. Defaults to `False`."""
+    stop_serving_flags: NotRequired[bool]
+    """Whether flag serving is disabled for this organisation. Defaults to `False`."""
+    persist_trait_data: NotRequired[bool]
+    """If set to `False`, trait data will never be persisted for this organisation. Defaults to `True`."""
+
+
+class Project(TypedDict):
+    """Represents data about a Flagsmith project. Carries settings necessary for an SDK API operation."""
+
+    id: DynamoInt
+    """Unique identifier for the project in Core."""
+    name: str
+    """Project name."""
+    organisation: Organisation
+    """The organisation that this project belongs to."""
+    segments: list[Segment]
+    """List of segments."""
+    server_key_only_feature_ids: NotRequired[list[DynamoInt]]
+    """List of feature IDs that are skipped when the SDK API serves flags for a public client-side key."""
+    enable_realtime_updates: NotRequired[bool]
+    """Whether the SDK API should use real-time updates. Defaults to `False`. Not currently used neither by SDK APIs nor by SDKs themselves."""
+    hide_disabled_flags: NotRequired[bool | None]
+    """Whether the SDK API should hide disabled flags for this project. Defaults to `False`."""
+
+
+class Integration(TypedDict):
+    """Represents evaluation integration data."""
+
+    api_key: NotRequired[str | None]
+    """API key for the integration."""
+    base_url: NotRequired[str | None]
+    """Base URL for the integration."""
+
+
+class DynatraceIntegration(Integration):
+    """Represents Dynatrace evaluation integration data."""
+
+    entity_selector: str
+    """A Dynatrace entity selector string."""
+
+
+class Webhook(TypedDict):
+    """Represents a webhook configuration."""
+
+    url: str
+    """Webhook target URL."""
+    secret: str
+    """Secret used to sign webhook payloads."""
+
+
+class _EnvironmentFields(TypedDict):
+    """Common fields for Environment documents."""
+
+    name: NotRequired[str]
+    """Environment name. Defaults to an empty string if not set."""
+    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`."""
+    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]
+    """Whether the SDK API should hide disabled flags for this environment. If `None`, the SDK API should fall back to project-level setting."""
+    use_identity_composite_key_for_hashing: NotRequired[bool]
+    """Whether the SDK API should set `$.identity.key` in engine evaluation context to identity's composite key. Defaults to `False`."""
+    use_identity_overrides_in_local_eval: NotRequired[bool]
+    """Whether the SDK API should return identity overrides as part of the environment document. Defaults to `False`."""
+
+    amplitude_config: NotRequired[Integration | None]
+    """Amplitude integration configuration."""
+    dynatrace_config: NotRequired[DynatraceIntegration | None]
+    """Dynatrace integration configuration."""
+    heap_config: NotRequired[Integration | None]
+    """Heap integration configuration."""
+    mixpanel_config: NotRequired[Integration | None]
+    """Mixpanel integration configuration."""
+    rudderstack_config: NotRequired[Integration | None]
+    """RudderStack integration configuration."""
+    segment_config: NotRequired[Integration | None]
+    """Segment integration configuration."""
+    webhook_config: NotRequired[Webhook | None]
+    """Webhook configuration."""
+
+
+### Root document schemas below. Indexed fields are marked as **INDEXED** in the docstrings. ###
+
+
+class EnvironmentAPIKey(TypedDict):
+    """Represents a server-side API key for a Flagsmith environment.
+
+    **DynamoDB table**: `flagsmith_environment_api_key`
+    """
+
+    id: DynamoInt
+    """Unique identifier for the environment API key in Core. **INDEXED**."""
+    key: str
+    """The server-side API key string, e.g. `"ser.xxxxxxxxxxxxx"`. **INDEXED**."""
+    created_at: DateTimeStr
+    """Creation timestamp."""
+    name: str
+    """Name of the API key."""
+    client_api_key: str
+    """The corresponding public client-side API key."""
+    expires_at: NotRequired[DateTimeStr | None]
+    """Expiration timestamp. If `None`, the key does not expire."""
+    active: bool
+    """Whether the key is active. Defaults to `True`."""
+
+
+class Identity(TypedDict):
+    """Represents a Flagsmith identity within an environment. Carries traits and feature overrides.
+    Used for per-identity flag evaluations in remote evaluation mode.
+
+    **DynamoDB table**: `flagsmith_identities`
+    """
+
+    identifier: str
+    """Unique identifier for the identity. **INDEXED**."""
+    environment_api_key: str
+    """API key of the environment this identity belongs to. Used to scope the identity within a specific environment. **INDEXED**."""
+    identity_uuid: UUIDStr
+    """The UUID for this identity. **INDEXED**."""
+    composite_key: str
+    """A composite key combining the environment and identifier. **INDEXED**.
+
+    Generated as: `{environment_api_key}_{identifier}`.
+    """
+    created_date: DateTimeStr
+    """Creation timestamp."""
+    identity_features: (
+        "NotRequired[Annotated[list[FeatureState], ValidateIdentityFeatureStatesList]]"
+    )
+    """List of identity overrides for this identity."""
+    identity_traits: list[Trait]
+    """List of traits associated with this identity."""
+    django_id: NotRequired[DynamoInt | None]
+    """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):
+    """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 EnvironmentV2Meta(_EnvironmentFields):
+    """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 EnvironmentV2IdentityOverride(TypedDict):
+    """Represents an identity override.
+    Used for per-identity flag evaluations in local evaluation mode. Presented as part of the API environment document.
+
+    **DynamoDB table**: `flagsmith_environments_v2`
+    """
+
+    environment_id: str
+    """Unique identifier for the environment in Core. **INDEXED**."""
+    document_key: str
+    """The document key for this identity override, formatted as `identity_override:{feature Core ID}:{identity UUID}`. **INDEXED**."""
+    environment_api_key: str
+    """Public client-side API key for the environment. **INDEXED**."""
+    identifier: str
+    """Unique identifier for the identity. **INDEXED**."""
+    identity_uuid: str
+    """The UUID for this identity, used by `edge-identities` APIs in Core. **INDEXED**."""
+    feature_state: FeatureState
+    """The feature state override for this identity."""

flagsmith_common-3.1.0/src/flagsmith_schemas/pydantic_types.py

@@ -0,0 +1,22 @@
+from datetime import datetime
+from decimal import Decimal
+from uuid import UUID
+
+from pydantic import AfterValidator, BeforeValidator, ValidateAs
+
+from flagsmith_schemas.validators import (
+    validate_dynamo_feature_state_value,
+    validate_identity_feature_states,
+    validate_multivariate_feature_state_values,
+)
+
+ValidateDecimalAsFloat = ValidateAs(float, lambda v: Decimal(str(v)))
+ValidateDecimalAsInt = ValidateAs(int, lambda v: Decimal(v))
+ValidateStrAsISODateTime = ValidateAs(datetime, lambda dt: dt.isoformat())
+ValidateStrAsUUID = ValidateAs(UUID, str)
+
+ValidateDynamoFeatureStateValue = BeforeValidator(validate_dynamo_feature_state_value)
+ValidateIdentityFeatureStatesList = AfterValidator(validate_identity_feature_states)
+ValidateMultivariateFeatureValuesList = AfterValidator(
+    validate_multivariate_feature_state_values
+)

flagsmith_common-3.1.0/src/flagsmith_schemas/types.py

@@ -0,0 +1,91 @@
+from decimal import Decimal
+from typing import TYPE_CHECKING, Annotated, Literal, TypeAlias
+
+from flagsmith_schemas.constants import PYDANTIC_INSTALLED
+
+if PYDANTIC_INSTALLED:
+    from flagsmith_schemas.pydantic_types import (
+        ValidateDecimalAsFloat,
+        ValidateDecimalAsInt,
+        ValidateDynamoFeatureStateValue,
+        ValidateStrAsISODateTime,
+        ValidateStrAsUUID,
+    )
+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.
+    # Define dummy types instead.
+    ValidateDecimalAsFloat = ...
+    ValidateDecimalAsInt = ...
+    ValidateDynamoFeatureStateValue = ...
+    ValidateStrAsISODateTime = ...
+    ValidateStrAsUUID = ...
+
+
+DynamoInt: TypeAlias = Annotated[Decimal, ValidateDecimalAsInt]
+"""An integer value stored in DynamoDB.
+
+DynamoDB represents all numbers as `Decimal`.
+`DynamoInt` indicates that the value should be treated as an integer.
+"""
+
+DynamoFloat: TypeAlias = Annotated[Decimal, ValidateDecimalAsFloat]
+"""A float value stored in DynamoDB.
+
+DynamoDB represents all numbers as `Decimal`.
+`DynamoFloat` indicates that the value should be treated as a float.
+"""
+
+UUIDStr: TypeAlias = Annotated[str, ValidateStrAsUUID]
+"""A string representing a UUID."""
+
+DateTimeStr: TypeAlias = Annotated[str, ValidateStrAsISODateTime]
+"""A string representing a date and time in ISO 8601 format."""
+
+FeatureType = Literal["STANDARD", "MULTIVARIATE"]
+"""Represents the type of a Flagsmith feature. Multivariate features include multiple weighted values."""
+
+DynamoFeatureValue: TypeAlias = Annotated[
+    DynamoInt | bool | str | None,
+    ValidateDynamoFeatureStateValue,
+]
+"""Represents the value of a Flagsmith feature. Can be stored a boolean, an integer, or a string.
+
+The default (SaaS) maximum length for strings is 20000 characters.
+"""
+
+DynamoContextValue: TypeAlias = DynamoInt | DynamoFloat | bool | str
+"""Represents a scalar value in the Flagsmith context, e.g., of an identity trait.
+Here's how we store different types:
+- Numeric string values (int, float) are stored as numbers.
+- Boolean values are stored as booleans.
+- All other values are stored as strings.
+- Maximum length for strings is 2000 characters.
+
+This type does not include complex structures like lists or dictionaries.
+"""
+
+ConditionOperator = Literal[
+    "EQUAL",
+    "GREATER_THAN",
+    "LESS_THAN",
+    "LESS_THAN_INCLUSIVE",
+    "CONTAINS",
+    "GREATER_THAN_INCLUSIVE",
+    "NOT_CONTAINS",
+    "NOT_EQUAL",
+    "REGEX",
+    "PERCENTAGE_SPLIT",
+    "MODULO",
+    "IS_SET",
+    "IS_NOT_SET",
+    "IN",
+]
+"""Represents segment condition operators used by Flagsmith engine."""
+
+RuleType = Literal[
+    "ALL",
+    "ANY",
+    "NONE",
+]
+"""Represents segment rule types used by Flagsmith engine."""

flagsmith_common-3.1.0/src/flagsmith_schemas/validators.py

@@ -0,0 +1,55 @@
+import typing
+from decimal import Decimal
+
+from flagsmith_schemas.constants import MAX_STRING_FEATURE_STATE_VALUE_LENGTH
+
+if typing.TYPE_CHECKING:
+    from flagsmith_schemas.dynamodb import FeatureState, MultivariateFeatureStateValue
+    from flagsmith_schemas.types import DynamoFeatureValue
+
+
+def validate_dynamo_feature_state_value(
+    value: typing.Any,
+) -> "DynamoFeatureValue":
+    if isinstance(value, bool | None):
+        return value
+    if isinstance(value, str):
+        if len(value) > MAX_STRING_FEATURE_STATE_VALUE_LENGTH:
+            raise ValueError(
+                "Dynamo feature state value string length cannot exceed "
+                f"{MAX_STRING_FEATURE_STATE_VALUE_LENGTH} characters "
+                f"(got {len(value)} characters)."
+            )
+        return value
+    if isinstance(value, int):
+        return Decimal(value)
+    return str(value)
+
+
+def validate_multivariate_feature_state_values(
+    values: "list[MultivariateFeatureStateValue]",
+) -> "list[MultivariateFeatureStateValue]":
+    total_percentage = sum(value["percentage_allocation"] for value in values)
+    if total_percentage > 100:
+        raise ValueError(
+            "Total `percentage_allocation` of multivariate feature state values "
+            "cannot exceed 100."
+        )
+    return values
+
+
+def validate_identity_feature_states(
+    values: "list[FeatureState]",
+) -> "list[FeatureState]":
+    seen: set[Decimal] = set()
+
+    for feature_state in values:
+        feature_id = feature_state["feature"]["id"]
+        if feature_id in seen:
+            raise ValueError(
+                f"Feature id={feature_id} cannot have multiple "
+                "feature states for a single identity."
+            )
+        seen.add(feature_id)
+
+    return values