flagsmith-common 1.5.2__tar.gz → 1.6.0__tar.gz

{flagsmith_common-1.5.2 → flagsmith_common-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flagsmith-common
-Version: 1.5.2
+Version: 1.6.0
 Summary: Flagsmith's common library
 License: BSD-3-Clause
 Author: Matthew Elwell
@@ -15,15 +15,20 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: django (<5)
+Requires-Dist: backoff (>=2.2.1,<3.0.0)
+Requires-Dist: django (>4,<5)
 Requires-Dist: django-health-check
 Requires-Dist: djangorestframework
 Requires-Dist: djangorestframework-recursive
 Requires-Dist: drf-writable-nested
+Requires-Dist: drf-yasg (>=1.21.10,<2.0.0)
 Requires-Dist: environs (<15)
 Requires-Dist: flagsmith-flag-engine
 Requires-Dist: gunicorn (>=19.1)
 Requires-Dist: prometheus-client (>=0.0.16)
+Requires-Dist: psycopg2-binary (>=2.9,<3)
+Requires-Dist: simplejson (>=3,<4)
+Project-URL: Changelog, https://github.com/flagsmith/flagsmith-common/blob/main/CHANGELOG.md
 Project-URL: Download, https://github.com/flagsmith/flagsmith-common/releases
 Project-URL: Homepage, https://flagsmith.com
 Project-URL: Issues, https://github.com/flagsmith/flagsmith-common/issues
@@ -56,12 +61,6 @@ make install-poetry    # Install Poetry
 make install-packages  # Install project dependencies
 ```
 
-By default, Poetry version 2.0.1 will be installed. You can specify a different version:
-
-```bash
-make install-poetry POETRY_VERSION=2.1.0
-```
-
 #### Development
 
 Run linting checks using pre-commit:
@@ -99,8 +98,8 @@ Flagsmith uses Prometheus to track performance metrics.
 The following default metrics are exposed:
 
 - `flagsmith_build_info`: Has the labels `version` and `ci_commit_sha`.
-- `http_server_request_duration_seconds`: Histogram labeled with `method`, `path`, and `response_status`.
-- `http_server_requests_total`: Counter labeled with `method`, `path`, and `response_status`.
+- `http_server_request_duration_seconds`: Histogram labeled with `method`, `route`, and `response_status`.
+- `http_server_requests_total`: Counter labeled with `method`, `route`, and `response_status`.
 
 ##### Guidelines
 

{flagsmith_common-1.5.2 → flagsmith_common-1.6.0}/README.md

@@ -24,12 +24,6 @@ make install-poetry    # Install Poetry
 make install-packages  # Install project dependencies
 ```
 
-By default, Poetry version 2.0.1 will be installed. You can specify a different version:
-
-```bash
-make install-poetry POETRY_VERSION=2.1.0
-```
-
 #### Development
 
 Run linting checks using pre-commit:
@@ -67,8 +61,8 @@ Flagsmith uses Prometheus to track performance metrics.
 The following default metrics are exposed:
 
 - `flagsmith_build_info`: Has the labels `version` and `ci_commit_sha`.
-- `http_server_request_duration_seconds`: Histogram labeled with `method`, `path`, and `response_status`.
-- `http_server_requests_total`: Counter labeled with `method`, `path`, and `response_status`.
+- `http_server_request_duration_seconds`: Histogram labeled with `method`, `route`, and `response_status`.
+- `http_server_requests_total`: Counter labeled with `method`, `route`, and `response_status`.
 
 ##### Guidelines
 

{flagsmith_common-1.5.2 → flagsmith_common-1.6.0}/pyproject.toml

@@ -1,18 +1,22 @@
 [project]
 name = "flagsmith-common"
-version = "1.5.2"
+version = "1.6.0"
 description = "Flagsmith's common library"
 requires-python = ">=3.11,<4.0"
 dependencies = [
-    "django (<5)",
+    "backoff (>=2.2.1,<3.0.0)",
+    "django (>4,<5)",
     "django-health-check",
     "djangorestframework-recursive",
     "djangorestframework",
     "drf-writable-nested",
+    "drf-yasg (>=1.21.10,<2.0.0)",
+    "environs (<15)",
     "flagsmith-flag-engine",
     "gunicorn (>=19.1)",
     "prometheus-client (>=0.0.16)",
-    "environs (<15)",
+    "simplejson (>=3,<4)",
+    "psycopg2-binary (>=2.9,<3)",
 ]
 authors = [
     { name = "Matthew Elwell" },
@@ -29,6 +33,7 @@ readme = "README.md"
 dynamic = ["classifiers"]
 
 [project.urls]
+Changelog = "https://github.com/flagsmith/flagsmith-common/blob/main/CHANGELOG.md"
 Download = "https://github.com/flagsmith/flagsmith-common/releases"
 Homepage = "https://flagsmith.com"
 Issues = "https://github.com/flagsmith/flagsmith-common/issues"
@@ -48,9 +53,13 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: BSD License",
 ]
-packages = [{ include = "common", from = "src" }]
+packages = [
+    { include = "common", from = "src" },
+    { include = "task_processor", from = "src" },
+]
 
 [tool.poetry.group.dev.dependencies]
+dj-database-url = "^2.3.0"
 django-stubs = "^5.1.3"
 djangorestframework-stubs = "^3.15.3"
 mypy = "^1.15.0"
@@ -65,6 +74,7 @@ pytest-mock = "^3.14.0"
 requests = "^2.32.3"
 ruff = "*"
 setuptools = "^77.0.3"
+types-simplejson = "^3.20.0.20250326"
 
 [build-system]
 requires = ["poetry-core"]

flagsmith_common-1.6.0/src/common/core/main.py

@@ -0,0 +1,80 @@
+import contextlib
+import logging
+import os
+import sys
+import tempfile
+import typing
+
+from django.core.management import execute_from_command_line
+
+logger = logging.getLogger(__name__)
+
+
+@contextlib.contextmanager
+def ensure_cli_env() -> typing.Generator[None, None, None]:
+    """
+    Set up the environment for the main entry point of the application
+    and clean up after it's done.
+
+    Add environment-related code that needs to happen before and after Django is involved
+    to here.
+
+    Use as a context manager, e.g.:
+
+    ```python
+    with ensure_cli_env():
+        main()
+    ```
+    """
+    ctx = contextlib.ExitStack()
+
+    # TODO @khvn26 Move logging setup to here
+
+    # Currently we don't install Flagsmith modules as a package, so we need to add
+    # $CWD to the Python path to be able to import them
+    sys.path.append(os.getcwd())
+
+    # TODO @khvn26 We should find a better way to pre-set the Django settings module
+    # without resorting to it being set outside of the application
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "settings.dev")
+
+    # Set up Prometheus' multiprocess mode
+    if "PROMETHEUS_MULTIPROC_DIR" not in os.environ:
+        prometheus_multiproc_dir_name = ctx.enter_context(
+            tempfile.TemporaryDirectory(
+                prefix="prometheus_multiproc",
+            )
+        )
+
+        logger.info(
+            "Created %s for Prometheus multi-process mode",
+            prometheus_multiproc_dir_name,
+        )
+        os.environ["PROMETHEUS_MULTIPROC_DIR"] = prometheus_multiproc_dir_name
+
+    if "task-processor" in sys.argv:
+        # A hacky way to signal we're not running the API
+        os.environ["RUN_BY_PROCESSOR"] = "true"
+
+    with ctx:
+        yield
+
+
+def main() -> None:
+    """
+    The main entry point to the Flagsmith application.
+
+    An equivalent to Django's `manage.py` script, this module is used to run management commands.
+
+    It's installed as the `flagsmith` command.
+
+    Everything that needs to be run before Django is started should be done here.
+
+    The end goal is to eventually replace Core API's `run-docker.sh` with this.
+
+    Usage:
+    `flagsmith <command> [options]`
+    """
+    with ensure_cli_env():
+        # Run Django
+        execute_from_command_line(sys.argv)

{flagsmith_common-1.5.2 → flagsmith_common-1.6.0}/src/common/core/management/commands/start.py

@@ -3,7 +3,10 @@ from typing import Any, Callable
 from django.core.management import BaseCommand, CommandParser
 from django.utils.module_loading import autodiscover_modules
 
-from common.gunicorn.utils import add_arguments, run_server
+from common.gunicorn.utils import add_arguments as add_gunicorn_arguments
+from common.gunicorn.utils import run_server
+from task_processor.utils import add_arguments as add_task_processor_arguments
+from task_processor.utils import start_task_processor
 
 
 class Command(BaseCommand):
@@ -13,20 +16,31 @@ class Command(BaseCommand):
         return super().create_parser(*args, conflict_handler="resolve", **kwargs)
 
     def add_arguments(self, parser: CommandParser) -> None:
-        add_arguments(parser)
+        add_gunicorn_arguments(parser)
 
         subparsers = parser.add_subparsers(
             title="sub-commands",
             required=True,
         )
+
         api_parser = subparsers.add_parser(
             "api",
             help="Start the Core API.",
         )
         api_parser.set_defaults(handle_method=self.handle_api)
 
+        task_processor_parser = subparsers.add_parser(
+            "task-processor",
+            help="Start the Task Processor.",
+        )
+        task_processor_parser.set_defaults(handle_method=self.handle_task_processor)
+        add_task_processor_arguments(task_processor_parser)
+
     def initialise(self) -> None:
-        autodiscover_modules("metrics")
+        autodiscover_modules(
+            "metrics",
+            "tasks",
+        )
 
     def handle(
         self,
@@ -39,3 +53,9 @@ class Command(BaseCommand):
 
     def handle_api(self, *args: Any, **options: Any) -> None:
         run_server(options)
+
+    def handle_task_processor(self, *args: Any, **options: Any) -> None:
+        with start_task_processor(options):
+            # Delegate signal handling to Gunicorn.
+            # The task processor will finalise once Gunicorn is shut down.
+            run_server(options)

flagsmith_common-1.6.0/src/common/core/management/commands/waitfordb.py

@@ -0,0 +1,87 @@
+import logging
+import time
+from argparse import ArgumentParser
+from typing import Any
+
+from django.core.management import BaseCommand, CommandError
+from django.db import OperationalError, connections
+from django.db.migrations.executor import MigrationExecutor
+
+logger = logging.getLogger(__name__)
+
+
+class Command(BaseCommand):
+    def add_arguments(self, parser: ArgumentParser) -> None:
+        parser.add_argument(
+            "--waitfor",
+            type=int,
+            dest="wait_for",
+            help="Number of seconds to wait for db to become available.",
+            default=5,
+        )
+        parser.add_argument(
+            "--migrations",
+            action="store_true",
+            dest="should_wait_for_migrations",
+            help="Whether to wait until all migrations are applied.",
+            default=False,
+        )
+        parser.add_argument(
+            "--database",
+            type=str,
+            dest="database",
+            help=(
+                'The database to wait for ("default", "analytics").'
+                'Defaults to the "default" database.'
+            ),
+            default="default",
+        )
+
+    def handle(
+        self,
+        *args: Any,
+        wait_for: int,
+        should_wait_for_migrations: bool,
+        database: str,
+        **options: Any,
+    ) -> None:
+        start = time.monotonic()
+        wait_between_checks = 0.25
+
+        logger.info("Checking if database is ready for connections.")
+
+        while True:
+            if time.monotonic() - start > wait_for:
+                msg = f"Failed to connect to DB within {wait_for} seconds."
+                logger.error(msg)
+                raise CommandError(msg)
+
+            conn = connections.create_connection(database)
+            try:
+                with conn.temporary_connection() as cursor:
+                    cursor.execute("SELECT 1")
+                logger.info("Successfully connected to the database.")
+                break
+            except OperationalError as e:
+                logger.warning("Database not yet ready for connections.")
+                logger.warning("Error was: %s: %s", e.__class__.__name__, e)
+
+            time.sleep(wait_between_checks)
+
+        if should_wait_for_migrations:
+            logger.info("Checking for applied migrations.")
+
+            while True:
+                if time.monotonic() - start > wait_for:
+                    msg = f"Didn't detect applied migrations for {wait_for} seconds."
+                    logger.error(msg)
+                    raise CommandError(msg)
+
+                conn = connections[database]
+                executor = MigrationExecutor(conn)
+                if not executor.migration_plan(executor.loader.graph.leaf_nodes()):
+                    logger.info("No pending migrations detected, good to go.")
+                    return
+
+                logger.warning("Migrations not yet applied.")
+                time.sleep(wait_between_checks)

{flagsmith_common-1.5.2 → flagsmith_common-1.6.0}/src/common/gunicorn/middleware.py

@@ -3,6 +3,7 @@ from typing import Callable
 from django.http import HttpRequest, HttpResponse
 
 from common.gunicorn.constants import WSGI_DJANGO_ROUTE_ENVIRON_KEY
+from common.gunicorn.utils import get_route_template
 
 
 class RouteLoggerMiddleware:
@@ -23,6 +24,8 @@ class RouteLoggerMiddleware:
         if resolver_match := request.resolver_match:
             # https://peps.python.org/pep-3333/#specification-details
             # "...the application is allowed to modify the dictionary in any way it desires"
-            request.META[WSGI_DJANGO_ROUTE_ENVIRON_KEY] = resolver_match.route
+            request.META[WSGI_DJANGO_ROUTE_ENVIRON_KEY] = get_route_template(
+                resolver_match.route
+            )
 
         return response

{flagsmith_common-1.5.2 → flagsmith_common-1.6.0}/src/common/gunicorn/utils.py

@@ -1,9 +1,11 @@
 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 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,
@@ -59,3 +61,18 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
 
 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

flagsmith_common-1.6.0/src/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"]

flagsmith_common-1.6.0/src/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)

flagsmith_common-1.6.0/src/task_processor/admin.py

@@ -0,0 +1,38 @@
+from datetime import datetime
+
+from django.contrib import admin
+from django.db.models import QuerySet
+from django.http import HttpRequest
+
+from task_processor.models import RecurringTask
+
+
+@admin.register(RecurringTask)
+class RecurringTaskAdmin(admin.ModelAdmin[RecurringTask]):
+    list_display = (
+        "uuid",
+        "task_identifier",
+        "run_every",
+        "last_run_status",
+        "last_run_finished_at",
+        "is_locked",
+    )
+    readonly_fields = ("args", "kwargs")
+
+    def last_run_status(self, instance: RecurringTask) -> str | None:
+        if last_run := instance.task_runs.order_by("-started_at").first():
+            return last_run.result
+        return None
+
+    def last_run_finished_at(self, instance: RecurringTask) -> datetime | None:
+        if last_run := instance.task_runs.order_by("-started_at").first():
+            return last_run.finished_at
+        return None
+
+    @admin.action(description="Unlock selected tasks")
+    def unlock(
+        self,
+        request: HttpRequest,
+        queryset: QuerySet[RecurringTask],
+    ) -> None:
+        queryset.update(is_locked=False)

flagsmith_common-1.6.0/src/task_processor/apps.py

@@ -0,0 +1,18 @@
+from django.apps import AppConfig
+from django.conf import settings
+from health_check.plugins import plugin_dir  # type: ignore[import-untyped]
+
+from task_processor.task_run_method import TaskRunMethod
+
+
+class TaskProcessorAppConfig(AppConfig):
+    name = "task_processor"
+
+    def ready(self) -> None:
+        if (
+            settings.ENABLE_TASK_PROCESSOR_HEALTH_CHECK
+            and settings.TASK_RUN_METHOD == TaskRunMethod.TASK_PROCESSOR
+        ):
+            from .health import TaskProcessorHealthCheckBackend
+
+            plugin_dir.register(TaskProcessorHealthCheckBackend)