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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flagsmith-common
-Version: 3.1.0
+Version: 3.2.1
 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,8 +13,8 @@ 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'
@@ -22,6 +22,7 @@ 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>6 ; 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'

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

@@ -1,6 +1,6 @@
 [project]
 name = "flagsmith-common"
-version = "3.1.0"
+version = "3.2.1"
 description = "Flagsmith's common library"
 requires-python = ">=3.11,<4.0"
 dependencies = []
@@ -12,8 +12,8 @@ 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)",
@@ -27,6 +27,7 @@ optional-dependencies = { test-tools = [
     "prometheus-client (>=0.0.16)",
 ], flagsmith-schemas = [
     "typing_extensions",
+    "flagsmith-flag-engine>6",
 ] }
 authors = [
     { name = "Matthew Elwell" },

{flagsmith_common-3.1.0 → flagsmith_common-3.2.1}/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.2.1/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.1.0 → flagsmith_common-3.2.1}/src/flagsmith_schemas/dynamodb.py

@@ -9,18 +9,17 @@ Otherwise, they serve as documentation for the structure of the data stored in D
 
 from typing import Annotated, Literal
 
+from flag_engine.segments.types import ConditionOperator, RuleType
 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,
 )
 
@@ -99,9 +98,9 @@ class Trait(TypedDict):
     """Represents a key-value pair associated with an identity."""
 
     trait_key: str
-    """Key of the trait."""
+    """Trait key."""
     trait_value: DynamoContextValue
-    """Value of the trait."""
+    """Trait value."""
 
 
 class SegmentCondition(TypedDict):
@@ -138,7 +137,7 @@ class Segment(TypedDict):
     """Name of the segment."""
     rules: list[SegmentRule]
     """List of rules within the segment."""
-    feature_states: list[FeatureState]
+    feature_states: NotRequired[list[FeatureState]]
     """List of segment overrides."""
 
 

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

@@ -4,6 +4,8 @@ from typing import TYPE_CHECKING, Annotated, Literal, TypeAlias
 from flagsmith_schemas.constants import PYDANTIC_INSTALLED
 
 if PYDANTIC_INSTALLED:
+    from pydantic import WithJsonSchema
+
     from flagsmith_schemas.pydantic_types import (
         ValidateDecimalAsFloat,
         ValidateDecimalAsInt,
@@ -15,6 +17,9 @@ 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.
+    def WithJsonSchema(_: object) -> object:
+        return ...
+
     ValidateDecimalAsFloat = ...
     ValidateDecimalAsInt = ...
     ValidateDynamoFeatureStateValue = ...
@@ -36,7 +41,11 @@ DynamoDB represents all numbers as `Decimal`.
 `DynamoFloat` indicates that the value should be treated as a float.
 """
 
-UUIDStr: TypeAlias = Annotated[str, ValidateStrAsUUID]
+UUIDStr: TypeAlias = Annotated[
+    str,
+    ValidateStrAsUUID,
+    WithJsonSchema({"type": "string", "format": "uuid"}),
+]
 """A string representing a UUID."""
 
 DateTimeStr: TypeAlias = Annotated[str, ValidateStrAsISODateTime]
@@ -49,7 +58,7 @@ 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.
+"""Represents the value of a Flagsmith feature stored in DynamoDB. Can be stored a boolean, an integer, or a string.
 
 The default (SaaS) maximum length for strings is 20000 characters.
 """
@@ -65,27 +74,5 @@ Here's how we store different types:
 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."""
+FeatureValue: TypeAlias = int | bool | str | None
+"""Represents the value of a Flagsmith feature. Can be stored a boolean, an integer, or a string."""

{flagsmith_common-3.1.0 → flagsmith_common-3.2.1}/src/task_processor/models.py

@@ -180,7 +180,23 @@ class RecurringTask(AbstractBaseTask):
             # If we have never run this task, then we should execute it only if
             # the time has passed after which we want to ensure this task runs.
             # This allows us to control when intensive tasks should be run.
-            return not (self.first_run_time and self.first_run_time > now.time())
+            if not self.first_run_time:
+                return True
+            first_run_today = now.replace(
+                hour=self.first_run_time.hour,
+                minute=self.first_run_time.minute,
+                second=self.first_run_time.second,
+                microsecond=self.first_run_time.microsecond,
+            )
+            # Handle midnight boundary using 12-hour window heuristic.
+            time_difference = (now - first_run_today).total_seconds()
+            if time_difference > 12 * 3600:
+                # first_run_today appears far in the past; it refers to tomorrow.
+                return False
+            if time_difference < -12 * 3600:
+                # first_run_today appears far in the future; it refers to yesterday.
+                return True
+            return now >= first_run_today
 
         # if the last run was at t- run_every, then we should execute it
         if (timezone.now() - last_task_run.started_at) >= self.run_every:

{flagsmith_common-3.1.0 → flagsmith_common-3.2.1}/src/task_processor/views.py

@@ -1,6 +1,6 @@
 from typing import Any
 
-from drf_yasg.utils import swagger_auto_schema  # type: ignore[import-untyped]
+from drf_spectacular.utils import extend_schema
 from rest_framework.decorators import api_view, permission_classes
 from rest_framework.permissions import IsAdminUser, IsAuthenticated
 from rest_framework.request import Request
@@ -10,7 +10,7 @@ from task_processor.monitoring import get_num_waiting_tasks
 from task_processor.serializers import MonitoringSerializer
 
 
-@swagger_auto_schema(method="GET", responses={200: MonitoringSerializer()})  # type: ignore[untyped-decorator]
+@extend_schema(methods=["GET"], responses={200: MonitoringSerializer()})
 @api_view(http_method_names=["GET"])
 @permission_classes([IsAuthenticated, IsAdminUser])
 def monitoring(request: Request, /, **kwargs: Any) -> Response: