flagsmith-common 2.2.4__py3-none-any.whl

common/gunicorn/utils.py

@@ -0,0 +1,104 @@
+import argparse
+import os
+from functools import lru_cache
+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 environs import Env
+from gunicorn.app.wsgiapp import (  # type: ignore[import-untyped]
+    WSGIApplication as GunicornWSGIApplication,
+)
+from gunicorn.config import Config  # type: ignore[import-untyped]
+
+from common.gunicorn.constants import WSGI_EXTRA_PREFIX
+
+env = Env()
+
+DEFAULT_ACCESS_LOG_FORMAT = '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s" %({origin}i)s %({access-control-allow-origin}o)s'
+GUNICORN_FLAGSMITH_DEFAULTS = {
+    "access_log_format": env.str("ACCESS_LOG_FORMAT", DEFAULT_ACCESS_LOG_FORMAT),
+    "accesslog": env.str("ACCESS_LOG_LOCATION", os.devnull),
+    "bind": "0.0.0.0:8000",
+    "config": "python:common.gunicorn.conf",
+    "logger_class": "common.gunicorn.logging.GunicornJsonCapableLogger",
+    "statsd_prefix": "flagsmith.api",
+    "threads": env.int("GUNICORN_THREADS", 1),
+    "timeout": env.int("GUNICORN_TIMEOUT", 30),
+    "worker_class": "sync",
+    "workers": env.int("GUNICORN_WORKERS", 1),
+}
+
+
+class DjangoWSGIApplication(GunicornWSGIApplication):  # type: ignore[misc]
+    def __init__(self, options: dict[str, Any] | None) -> None:
+        self.options = {
+            key: value for key, value in (options or {}).items() if value is not None
+        }
+        super().__init__()
+
+    def load_config(self) -> None:
+        cfg_settings = self.cfg.settings
+        options_items = (
+            (key, value)
+            for key, value in {**GUNICORN_FLAGSMITH_DEFAULTS, **self.options}.items()
+            if key in cfg_settings
+        )
+        for key, value in options_items:
+            self.cfg.set(key.lower(), value)
+        self.load_config_from_module_name_or_filename(self.cfg.config)
+
+    def load_wsgiapp(self) -> WSGIHandler:
+        return get_wsgi_application()
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    gunicorn_group = parser.add_argument_group("gunicorn")
+    _config = Config()
+    keys = sorted(_config.settings, key=_config.settings.__getitem__)
+    for key in keys:
+        _config.settings[key].add_option(gunicorn_group)
+
+
+def run_server(options: dict[str, Any] | None = None) -> None:
+    DjangoWSGIApplication(options).run()
+
+
+@lru_cache
+def get_route_template(route: str) -> str:
+    """
+    Convert a Django regex route to a template string that can be
+    searched for in the API documentation.
+
+    e.g.,
+
+    `"^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)
+    return route_template
+
+
+def log_extra(
+    request: HttpRequest,
+    key: str,
+    value: Any,
+) -> None:
+    """
+    Store a value in the WSGI request `environ` using a prefixed key.
+
+    https://peps.python.org/pep-3333/#specification-details
+    "...the application is allowed to modify the dictionary in any way it desires"
+    """
+    meta_key = f"{WSGI_EXTRA_PREFIX}{key}"
+    request.META[meta_key] = value
+
+
+def get_extra(environ: dict[str, Any], key: str) -> Any:
+    """
+    Retrieve a value from the WSGI request `environ` using a prefixed key.
+    """
+    meta_key = f"{WSGI_EXTRA_PREFIX}{key}"
+    return environ.get(meta_key)

common/migrations/helpers/__init__.py

@@ -0,0 +1,9 @@
+"""
+Note: django doesn't support adding submodules to the migrations module directory
+that don't include a Migration class. As such, I've defined this helpers submodule
+and simplified the imports by defining the __all__ attribute.
+"""
+
+from common.migrations.helpers.postgres_helpers import PostgresOnlyRunSQL
+
+__all__ = ["PostgresOnlyRunSQL"]

common/migrations/helpers/postgres_helpers.py

@@ -0,0 +1,41 @@
+from contextlib import suppress
+
+from django.db import migrations
+from django.db.backends.base.schema import BaseDatabaseSchemaEditor
+from django.db.migrations.state import ProjectState
+
+
+class PostgresOnlyRunSQL(migrations.RunSQL):
+    @classmethod
+    def from_sql_file(
+        cls,
+        file_path: str,
+        reverse_sql: str = "",
+    ) -> "PostgresOnlyRunSQL":
+        with open(file_path) as forward_sql:
+            with suppress(FileNotFoundError):
+                with open(reverse_sql) as reverse_sql_file:
+                    reverse_sql = reverse_sql_file.read()
+            return cls(forward_sql.read(), reverse_sql=reverse_sql)
+
+    def database_forwards(
+        self,
+        app_label: str,
+        schema_editor: BaseDatabaseSchemaEditor,
+        from_state: ProjectState,
+        to_state: ProjectState,
+    ) -> None:
+        if schema_editor.connection.vendor != "postgresql":
+            return
+        super().database_forwards(app_label, schema_editor, from_state, to_state)
+
+    def database_backwards(
+        self,
+        app_label: str,
+        schema_editor: BaseDatabaseSchemaEditor,
+        from_state: ProjectState,
+        to_state: ProjectState,
+    ) -> None:
+        if schema_editor.connection.vendor != "postgresql":
+            return
+        super().database_backwards(app_label, schema_editor, from_state, to_state)

common/organisations/permissions.py

@@ -0,0 +1,10 @@
+CREATE_PROJECT = "CREATE_PROJECT"
+MANAGE_USER_GROUPS = "MANAGE_USER_GROUPS"
+
+ORGANISATION_PERMISSIONS = (
+    (CREATE_PROJECT, "Allows the user to create projects in this organisation."),
+    (
+        MANAGE_USER_GROUPS,
+        "Allows the user to manage the groups in the organisation and their members.",
+    ),
+)

common/projects/permissions.py

@@ -0,0 +1,40 @@
+VIEW_AUDIT_LOG = "VIEW_AUDIT_LOG"
+
+# Maintain a list of permissions here
+VIEW_PROJECT = "VIEW_PROJECT"
+CREATE_ENVIRONMENT = "CREATE_ENVIRONMENT"
+DELETE_FEATURE = "DELETE_FEATURE"
+CREATE_FEATURE = "CREATE_FEATURE"
+EDIT_FEATURE = "EDIT_FEATURE"
+MANAGE_SEGMENTS = "MANAGE_SEGMENTS"
+MANAGE_TAGS = "MANAGE_TAGS"
+
+# Note that this does not impact change requests in an environment
+MANAGE_PROJECT_LEVEL_CHANGE_REQUESTS = "MANAGE_PROJECT_LEVEL_CHANGE_REQUESTS"
+APPROVE_PROJECT_LEVEL_CHANGE_REQUESTS = "APPROVE_PROJECT_LEVEL_CHANGE_REQUESTS"
+CREATE_PROJECT_LEVEL_CHANGE_REQUESTS = "CREATE_PROJECT_LEVEL_CHANGE_REQUESTS"
+
+TAG_SUPPORTED_PERMISSIONS = [DELETE_FEATURE]
+
+PROJECT_PERMISSIONS = [
+    (VIEW_PROJECT, "View permission for the given project."),
+    (CREATE_ENVIRONMENT, "Ability to create an environment in the given project."),
+    (DELETE_FEATURE, "Ability to delete features in the given project."),
+    (CREATE_FEATURE, "Ability to create features in the given project."),
+    (EDIT_FEATURE, "Ability to edit features in the given project."),
+    (MANAGE_SEGMENTS, "Ability to manage segments in the given project."),
+    (VIEW_AUDIT_LOG, "Allows the user to view the audit logs for this organisation."),
+    (
+        MANAGE_PROJECT_LEVEL_CHANGE_REQUESTS,
+        "Ability to create, delete, and publish change requests associated with a project.",
+    ),
+    (
+        APPROVE_PROJECT_LEVEL_CHANGE_REQUESTS,
+        "Ability to approve project level change requests.",
+    ),
+    (
+        CREATE_PROJECT_LEVEL_CHANGE_REQUESTS,
+        "Ability to create project level change requests.",
+    ),
+    (MANAGE_TAGS, "Allows the user to manage tags in the given project."),
+]

common/prometheus/__init__.py

@@ -0,0 +1,3 @@
+from common.prometheus.utils import Histogram
+
+__all__ = ("Histogram",)

common/prometheus/utils.py

@@ -0,0 +1,38 @@
+import importlib
+
+import prometheus_client
+from django.conf import settings
+from prometheus_client.metrics import MetricWrapperBase
+from prometheus_client.multiprocess import MultiProcessCollector
+
+
+class Histogram(prometheus_client.Histogram):
+    DEFAULT_BUCKETS = settings.PROMETHEUS_HISTOGRAM_BUCKETS
+
+
+def get_registry() -> prometheus_client.CollectorRegistry:
+    registry = prometheus_client.CollectorRegistry()
+    MultiProcessCollector(registry)  # type: ignore[no-untyped-call]
+    return registry
+
+
+def reload_metrics(*metric_module_names: str) -> None:
+    """
+    Clear the registry of all collectors from the given modules
+    and reload the modules to register the collectors again.
+
+    Used in tests to reset the state of the metrics module
+    when needed.
+    """
+
+    registry = prometheus_client.REGISTRY
+
+    for module_name in metric_module_names:
+        metrics_module = importlib.import_module(module_name)
+
+        for module_attr in vars(metrics_module).values():
+            if isinstance(module_attr, MetricWrapperBase):
+                # Unregister the collector from the registry
+                registry.unregister(module_attr)
+
+        importlib.reload(metrics_module)

common/test_tools/__init__.py

@@ -0,0 +1,11 @@
+from common.test_tools.types import (
+    AssertMetricFixture,
+    RunTasksFixture,
+    SnapshotFixture,
+)
+
+__all__ = (
+    "AssertMetricFixture",
+    "RunTasksFixture",
+    "SnapshotFixture",
+)

common/test_tools/plugin.py

@@ -0,0 +1,139 @@
+from functools import partial
+from typing import 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,
+    RunTasksFixture,
+    Snapshot,
+    SnapshotFixture,
+)
+from task_processor.task_run_method import TaskRunMethod
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("snapshot")
+    group.addoption(
+        "--snapshot-update",
+        action="store_true",
+        help="Update snapshot files instead of testing against them.",
+    )
+
+
+def assert_metric_impl() -> Generator[AssertMetricFixture, None, None]:
+    registry = prometheus_client.REGISTRY
+    collectors = [*registry._collector_to_names]
+
+    # Reset registry state
+    for collector in collectors:
+        if isinstance(collector, MetricWrapperBase):
+            collector.clear()
+
+    def _assert_metric(
+        *,
+        name: str,
+        labels: dict[str, str],
+        value: float | int,
+    ) -> None:
+        metric_value = registry.get_sample_value(name, labels)
+        assert metric_value == value, (
+            f"Metric {name} not found in registry:\n"
+            f"{prometheus_client.generate_latest(registry).decode()}"
+        )
+
+    yield _assert_metric
+
+
+assert_metric = pytest.fixture(assert_metric_impl)
+
+
+@pytest.fixture()
+def saas_mode(fs: FakeFilesystem) -> Generator[None, None, None]:
+    from common.core.utils import is_saas
+
+    is_saas.cache_clear()
+    fs.create_file("./SAAS_DEPLOYMENT")
+
+    yield
+
+    is_saas.cache_clear()
+
+
+@pytest.fixture()
+def enterprise_mode(fs: FakeFilesystem) -> Generator[None, None, None]:
+    from common.core.utils import is_enterprise
+
+    is_enterprise.cache_clear()
+    fs.create_file("./ENTERPRISE_VERSION")
+
+    yield
+
+    is_enterprise.cache_clear()
+
+
+@pytest.fixture()
+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
+    from common.prometheus.utils import reload_metrics
+
+    reload_metrics("task_processor.metrics")
+
+
+@pytest.fixture(autouse=True)
+def flagsmith_markers_marked(
+    request: pytest.FixtureRequest,
+) -> None:
+    for marker in request.node.iter_markers():
+        if marker.name == "saas_mode":
+            request.getfixturevalue("saas_mode")
+        if marker.name == "enterprise_mode":
+            request.getfixturevalue("enterprise_mode")
+        if marker.name == "task_processor_mode":
+            request.getfixturevalue("task_processor_mode")
+
+
+@pytest.fixture(name="run_tasks")
+def run_tasks_impl(
+    settings: SettingsWrapper,
+    transactional_db: None,
+    task_processor_mode: None,
+) -> RunTasksFixture:
+    settings.TASK_RUN_METHOD = TaskRunMethod.TASK_PROCESSOR
+
+    from task_processor.processor import run_tasks
+
+    return partial(run_tasks, database="default")
+
+
+@pytest.fixture
+def snapshot(request: pytest.FixtureRequest) -> SnapshotFixture:
+    """
+    Retrieve a `Snapshot` object getter for the current test.
+    The snapshot is stored in the `snapshots` directory next to the test file.
+
+    Snapshot files are named after the test function name (+ ".txt") by default.
+    If a name is provided to the getter, the snapshot will be stored in a file with that name.
+    The name is relative to the `snapshots` directory.
+
+    When `--snapshot-update` is provided to `pytest`:
+    - The snapshot will be created if it does not exist.
+    - If the comparison is false, the snapshot will be updated with the string it's being compared to in the test,
+    and the test will be marked as expected to fail.
+    """
+    for_update = request.config.getoption("--snapshot-update")
+    snapshot_dir = request.path.parent / "snapshots"
+    snapshot_dir.mkdir(exist_ok=True)
+
+    def _get_snapshot(name: str = "") -> Snapshot:
+        snapshot_name = name or f"{request.node.name}.txt"
+        snapshot_path = snapshot_dir / snapshot_name
+        return Snapshot(snapshot_path, for_update=for_update)
+
+    return _get_snapshot

common/test_tools/types.py

@@ -0,0 +1,56 @@
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol
+
+import pytest
+
+if TYPE_CHECKING:
+    from task_processor.models import TaskRun
+
+
+class AssertMetricFixture(Protocol):
+    def __call__(
+        self,
+        *,
+        name: str,
+        labels: dict[str, str],
+        value: float | int,
+    ) -> None: ...
+
+
+class RunTasksFixture(Protocol):
+    def __call__(
+        self,
+        num_tasks: int,
+    ) -> "list[TaskRun]": ...
+
+
+class SnapshotFixture(Protocol):
+    def __call__(self, name: str = "") -> "Snapshot": ...
+
+
+class Snapshot:
+    """
+    Read contents of `path` and make them available for comparison via the `==` operator.
+    If the contents are different, and `Snapshot` initialised in update mode,
+    (e.g. by running `pytest` with `--snapshot-update`), write the new contents to `path`.
+    """
+
+    def __init__(self, path: Path, for_update: bool) -> None:
+        self.path = path
+        mode = "r" if not for_update else "w+"
+        self.content: str = open(path, encoding="utf-8", mode=mode).read()
+        self.for_update = for_update
+
+    def __eq__(self, other: object) -> bool:
+        if self.content == other:
+            return True
+        if self.for_update and isinstance(other, str):
+            with open(self.path, "w", encoding="utf-8") as f:
+                f.write(other)
+            pytest.xfail(reason=f"Snapshot updated: {self.path}")
+        return False
+
+    def __str__(self) -> str:
+        return self.content
+
+    __repr__ = __str__

common/test_tools/utils.py

@@ -0,0 +1,11 @@
+from typing import Literal
+
+from common.core.utils import is_enterprise, is_saas
+
+
+def edition_printer() -> Literal["saas!", "enterprise!", "oss!"]:
+    if is_saas():
+        return "saas!"
+    if is_enterprise():
+        return "enterprise!"
+    return "oss!"

common/types.py

@@ -0,0 +1,45 @@
+import typing
+
+if typing.TYPE_CHECKING:
+    from django.contrib.contenttypes.models import ContentType
+    from django.db import models
+
+    FeatureStateValue: typing.TypeAlias = models.Model
+    FeatureSegment: typing.TypeAlias = models.Model
+    Condition: typing.TypeAlias = models.Model
+    MultivariateFeatureStateValue: typing.TypeAlias = models.Model
+    Metadata: typing.TypeAlias = models.Model
+    Organisation: typing.TypeAlias = models.Model
+
+    class SoftDeleteExportableModel(models.Model):
+        def hard_delete(self) -> None: ...
+
+    class Segment(SoftDeleteExportableModel):
+        id: int
+        version: int | None
+        rules = models.ForeignKey("Rule", on_delete=models.CASCADE)
+
+        def deep_clone(self) -> "Segment": ...
+
+    class Rule(models.Model):
+        def get_segment(self) -> Segment: ...
+
+    class SegmentRule(Rule):
+        pass
+
+    class Project(models.Model):
+        organisation: "Organisation"
+        max_segments_allowed: int
+
+    class MetadataField(models.Model):
+        name: str
+        organisation: "Organisation"
+
+    class MetadataModelField(models.Model):
+        field: "MetadataField"
+        content_type: ContentType
+
+    class MetadataModelFieldRequirement(models.Model):
+        model_field: "MetadataModelField"
+        object_id: int
+        content_type: ContentType