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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flagsmith-common
-Version: 3.0.0
+Version: 3.2.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
@@ -13,14 +13,16 @@ Requires-Dist: django>4,<6 ; extra == 'common-core'
 Requires-Dist: django-health-check ; extra == 'common-core'
 Requires-Dist: djangorestframework-recursive ; extra == 'common-core'
 Requires-Dist: djangorestframework ; extra == 'common-core'
+Requires-Dist: drf-spectacular>=0.28.0,<1 ; extra == 'common-core'
 Requires-Dist: drf-writable-nested ; extra == 'common-core'
-Requires-Dist: drf-yasg>=1.21.10,<2.0.0 ; extra == 'common-core'
 Requires-Dist: environs<15 ; extra == 'common-core'
 Requires-Dist: gunicorn>=19.1 ; extra == 'common-core'
 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: flagsmith-flag-engine>10 ; 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 +38,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.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flagsmith-common"
-version = "3.0.0"
+version = "3.2.0"
 description = "Flagsmith's common library"
 requires-python = ">=3.11,<4.0"
 dependencies = []
@@ -12,20 +12,22 @@ optional-dependencies = { test-tools = [
     "django-health-check",
     "djangorestframework-recursive",
     "djangorestframework",
+    "drf-spectacular (>=0.28.0,<1)",
     "drf-writable-nested",
-    "drf-yasg (>=1.21.10,<2.0.0)",
     "environs (<15)",
     "gunicorn (>=19.1)",
     "prometheus-client (>=0.0.16)",
     "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",
+    "flagsmith-flag-engine>10",
 ] }
 authors = [
     { name = "Matthew Elwell" },
@@ -68,6 +70,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 +80,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 +89,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.2.0}/src/common/gunicorn/utils.py

@@ -6,7 +6,7 @@ from typing import Any
 from django.core.handlers.wsgi import WSGIHandler
 from django.core.wsgi import get_wsgi_application
 from django.http import HttpRequest
-from drf_yasg.generators import EndpointEnumerator  # type: ignore[import-untyped]
+from drf_spectacular.generators import EndpointEnumerator
 from environs import Env
 from gunicorn.app.wsgiapp import (  # type: ignore[import-untyped]
     WSGIApplication as GunicornWSGIApplication,
@@ -77,7 +77,7 @@ def get_route_template(route: str) -> str:
     `"^api/v1/environments/(?P<environment_api_key>[^/.]+)/api-keys/$"` ->
     `"/api/v1/environments/{environment_api_key}/api-keys/"`
     """
-    route_template: str = EndpointEnumerator().get_path_from_regex(route)
+    route_template: str = EndpointEnumerator().get_path_from_regex(route)  # type: ignore[no-untyped-call]
     return route_template
 
 

{flagsmith_common-3.0.0 → flagsmith_common-3.2.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.2.0/src/flagsmith_schemas/api.py

@@ -0,0 +1,217 @@
+"""
+The types in this module describe Flagsmith SDK API request and response schemas.
+The docstrings here comprise user-facing documentation for these types.
+
+The types are used by:
+ - SDK API OpenAPI schema generation.
+ - Flagsmith's API and SDK implementations written in Python.
+
+These types can be used with for validation and serialization
+with any library that supports TypedDict, such as Pydantic or typeguard.
+
+When updating this module, ensure that the changes are backwards compatible.
+"""
+
+from flag_engine.engine import ContextValue
+from flag_engine.segments.types import ConditionOperator, RuleType
+from typing_extensions import NotRequired, TypedDict
+
+from flagsmith_schemas.types import FeatureType, FeatureValue, UUIDStr
+
+
+class Feature(TypedDict):
+    """Represents a Flagsmith feature, defined at project level."""
+
+    id: int
+    """Unique identifier for the feature in Core."""
+    name: str
+    """Name of the feature. Must be unique within a project."""
+    type: FeatureType
+    """Feature type."""
+
+
+class MultivariateFeatureOption(TypedDict):
+    """Represents a single multivariate feature option in the Flagsmith UI."""
+
+    value: str
+    """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."""
+
+    id: int | 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: UUIDStr | None
+    """The UUID for this multivariate feature state value. Should be used for multivariate bucketing if `id` is null."""
+    percentage_allocation: float
+    """The percentage allocation for this multivariate feature state value. Should be between or equal to 0 and 100; total percentage allocation of grouped `MultivariateFeatureStateValue` must not exceed 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: int | None
+    """The priority of this segment feature override. Lower numbers indicate stronger priority. If null 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: FeatureValue
+    """The value for this feature state."""
+    featurestate_uuid: UUIDStr
+    """The UUID for this feature state."""
+    feature_segment: FeatureSegment | None
+    """Segment override data, if this feature state is for a segment override."""
+    multivariate_feature_state_values: list[MultivariateFeatureStateValue]
+    """List of multivariate feature state values, if this feature state is for a multivariate feature."""
+
+
+class Trait(TypedDict):
+    """Represents a key-value pair associated with an identity."""
+
+    trait_key: str
+    """Key of the trait."""
+    trait_value: ContextValue
+    """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: str
+    """Value to be compared against in this condition. May be `None` for `IS_SET` and `IS_NOT_SET` operators."""
+    property_: str
+    """The property (context key) this condition applies to. May be `None` for the `PERCENTAGE_SPLIT` operator.
+
+    Named `property_` for legacy reasons.
+    """
+
+
+class SegmentRule(TypedDict):
+    """Represents a rule within a segment used by Flagsmith engine. Root rules usually contain nested rules."""
+
+    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 and feature overrides."""
+
+    id: int
+    """Unique identifier for the segment in Core."""
+    name: str
+    """Segment name."""
+    rules: list[SegmentRule]
+    """List of rules within the segment."""
+    feature_states: NotRequired[list[FeatureState]]
+    """List of segment overrides."""
+
+
+class Project(TypedDict):
+    """Represents a Flagsmith project. For SDKs, this is mainly used to convey segment data."""
+
+    segments: list[Segment]
+    """List of segments."""
+
+
+class IdentityOverride(TypedDict):
+    """Represents an identity override, defining feature states specific to an identity."""
+
+    identifier: str
+    """Unique identifier for the identity."""
+    identity_features: list[FeatureState]
+    """List of identity overrides for this identity."""
+
+
+class TraitInput(TypedDict):
+    """Represents a key-value pair trait provided as input when creating or updating an identity."""
+
+    trait_key: str
+    """Trait key."""
+    trait_value: ContextValue
+    """Trait value. If `null`, the trait will be deleted."""
+    transient: NotRequired[bool | None]
+    """Whether this trait is transient (not persisted). Defaults to `false`."""
+
+
+class V1Flag(TypedDict):
+    """Represents a single flag (feature state) returned by the Flagsmith SDK."""
+
+    feature: Feature
+    """The feature that this flag represents."""
+    enabled: bool
+    """Whether the feature is enabled or disabled."""
+    feature_state_value: FeatureValue
+    """The value for this feature state."""
+
+
+### Root request schemas below. ###
+
+
+class V1IdentitiesRequest(TypedDict):
+    """`/api/v1/identities/` request.
+
+    Used to retrieve flags for an identity and store its traits.
+    """
+
+    identifier: str
+    """Unique identifier for the identity."""
+    traits: NotRequired[list[TraitInput] | None]
+    """List of traits to set for the identity. If `null` or not provided, no traits are set or updated."""
+    transient: NotRequired[bool | None]
+    """Whether the identity is transient (not persisted). Defaults to `false`."""
+
+
+### Root response schemas below. ###
+
+
+class V1EnvironmentDocumentResponse(TypedDict):
+    """`/api/v1/environment-documents/` response.
+
+    Powers Flagsmith SDK's local evaluation mode.
+    """
+
+    api_key: str
+    """Public client-side API key for the environment, used to identify it."""
+    feature_states: list[FeatureState]
+    """List of feature states representing the environment defaults."""
+    identity_overrides: list[IdentityOverride]
+    """List of identity overrides defined for this environment."""
+    name: str
+    """Environment name."""
+    project: Project
+    """Project-specific data for this environment."""
+
+
+V1FlagsResponse = list[V1Flag]
+"""`/api/v1/flags/` response.
+
+A list of flags for the specified environment."""
+
+
+class V1IdentitiesResponse(TypedDict):
+    """`/api/v1/identities/` response.
+
+    Represents the identity created or updated, along with its flags.
+    """
+
+    identifier: str
+    """Unique identifier for the identity."""
+    flags: list[V1Flag]
+    """List of flags (feature states) for the identity."""
+    traits: list[Trait]
+    """List of traits associated with the identity."""

flagsmith_common-3.2.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