flagsmith-common 1.5.0__tar.gz

flagsmith_common-1.5.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Flagsmith
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

flagsmith_common-1.5.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.3
+Name: flagsmith-common
+Version: 1.5.0
+Summary: Flagsmith's common library
+License: BSD-3-Clause
+Author: Matthew Elwell
+Maintainer: Flagsmith Team
+Maintainer-email: support@flagsmith.com
+Requires-Python: >=3.11,<4.0
+Classifier: Framework :: Django
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+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: django-health-check
+Requires-Dist: djangorestframework
+Requires-Dist: djangorestframework-recursive
+Requires-Dist: drf-writable-nested
+Requires-Dist: environs (<15)
+Requires-Dist: flagsmith-flag-engine
+Requires-Dist: gunicorn (>=19.1)
+Requires-Dist: prometheus-client (>=0.0.16)
+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
+Project-URL: Repository, https://github.com/flagsmith/flagsmith-common
+Description-Content-Type: text/markdown
+
+# flagsmith-common
+Flagsmith's common library
+
+### Development Setup
+
+This project uses [Poetry](https://python-poetry.org/) for dependency management and includes a Makefile to simplify common development tasks.
+
+#### Prerequisites
+
+- Python >= 3.11
+- Make
+
+#### Installation
+
+You can set up your development environment using the provided Makefile:
+
+```bash
+# Install everything (pip, poetry, and project dependencies)
+make install
+
+# Individual installation steps are also available
+make install-pip       # Upgrade pip
+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:
+
+```bash
+make lint
+```
+
+Additional options can be passed to the `install-packages` target:
+
+```bash
+# Install with development dependencies
+make install-packages opts="--with dev"
+
+# Install with specific extras
+make install-packages opts="--extras 'feature1 feature2'"
+```
+
+### Usage
+
+#### Installation
+
+1. Make sure `"common.core"` is in the `INSTALLED_APPS` of your settings module.
+This enables the `manage.py flagsmith` commands.
+
+2. Add `"common.gunicorn.middleware.RouteLoggerMiddleware"` to `MIDDLEWARE` in your settings module.
+This enables the `route` label for Prometheus HTTP metrics.
+
+3. To enable the `/metrics` endpoint, set the `PROMETHEUS_ENABLED` setting to `True`.
+
+#### Metrics
+
+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`.
+
+##### Guidelines
+
+Try to come up with meaningful metrics to cover your feature with when developing it. Refer to [Prometheus best practices][1] when naming your metric and labels.
+
+Define your metrics in a `metrics.py` module of your Django application — see [example][2]. Contrary to Prometheus Python client examples and documentation, please name a metric variable exactly as your metric name.
+
+It's generally a good idea to allow users to define histogram buckets of their own. Flagsmith accepts a `PROMETHEUS_HISTOGRAM_BUCKETS` setting so users can customise their buckets. To honour the setting, use the `common.prometheus.Histogram` class when defining your histograms. When using `prometheus_client.Histogram` directly, please expose a dedicated setting like so:
+
+```python
+import prometheus_client
+from django.conf import settings
+
+distance_from_earth_au = prometheus.Histogram(
+    "distance_from_earth_au",
+    "Distance from Earth in astronomical units",
+    buckets=settings.DISTANCE_FROM_EARTH_AU_HISTOGRAM_BUCKETS,
+)
+```
+
+[1]: https://prometheus.io/docs/practices/naming/
+[2]: https://github.com/Flagsmith/flagsmith-common/blob/main/src/common/gunicorn/metrics.py
+[3]: https://docs.gunicorn.org/en/stable/design.html#server-model
+[4]: https://prometheus.github.io/client_python/multiprocess
+

flagsmith_common-1.5.0/README.md

@@ -0,0 +1,95 @@
+# flagsmith-common
+Flagsmith's common library
+
+### Development Setup
+
+This project uses [Poetry](https://python-poetry.org/) for dependency management and includes a Makefile to simplify common development tasks.
+
+#### Prerequisites
+
+- Python >= 3.11
+- Make
+
+#### Installation
+
+You can set up your development environment using the provided Makefile:
+
+```bash
+# Install everything (pip, poetry, and project dependencies)
+make install
+
+# Individual installation steps are also available
+make install-pip       # Upgrade pip
+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:
+
+```bash
+make lint
+```
+
+Additional options can be passed to the `install-packages` target:
+
+```bash
+# Install with development dependencies
+make install-packages opts="--with dev"
+
+# Install with specific extras
+make install-packages opts="--extras 'feature1 feature2'"
+```
+
+### Usage
+
+#### Installation
+
+1. Make sure `"common.core"` is in the `INSTALLED_APPS` of your settings module.
+This enables the `manage.py flagsmith` commands.
+
+2. Add `"common.gunicorn.middleware.RouteLoggerMiddleware"` to `MIDDLEWARE` in your settings module.
+This enables the `route` label for Prometheus HTTP metrics.
+
+3. To enable the `/metrics` endpoint, set the `PROMETHEUS_ENABLED` setting to `True`.
+
+#### Metrics
+
+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`.
+
+##### Guidelines
+
+Try to come up with meaningful metrics to cover your feature with when developing it. Refer to [Prometheus best practices][1] when naming your metric and labels.
+
+Define your metrics in a `metrics.py` module of your Django application — see [example][2]. Contrary to Prometheus Python client examples and documentation, please name a metric variable exactly as your metric name.
+
+It's generally a good idea to allow users to define histogram buckets of their own. Flagsmith accepts a `PROMETHEUS_HISTOGRAM_BUCKETS` setting so users can customise their buckets. To honour the setting, use the `common.prometheus.Histogram` class when defining your histograms. When using `prometheus_client.Histogram` directly, please expose a dedicated setting like so:
+
+```python
+import prometheus_client
+from django.conf import settings
+
+distance_from_earth_au = prometheus.Histogram(
+    "distance_from_earth_au",
+    "Distance from Earth in astronomical units",
+    buckets=settings.DISTANCE_FROM_EARTH_AU_HISTOGRAM_BUCKETS,
+)
+```
+
+[1]: https://prometheus.io/docs/practices/naming/
+[2]: https://github.com/Flagsmith/flagsmith-common/blob/main/src/common/gunicorn/metrics.py
+[3]: https://docs.gunicorn.org/en/stable/design.html#server-model
+[4]: https://prometheus.github.io/client_python/multiprocess

flagsmith_common-1.5.0/pyproject.toml

@@ -0,0 +1,119 @@
+[project]
+name = "flagsmith-common"
+version = "1.5.0"
+description = "Flagsmith's common library"
+requires-python = ">=3.11,<4.0"
+dependencies = [
+    "django (<5)",
+    "django-health-check",
+    "djangorestframework-recursive",
+    "djangorestframework",
+    "drf-writable-nested",
+    "flagsmith-flag-engine",
+    "gunicorn (>=19.1)",
+    "prometheus-client (>=0.0.16)",
+    "environs (<15)",
+]
+authors = [
+    { name = "Matthew Elwell" },
+    { name = "Gagan Trivedi" },
+    { name = "Kim Gustyr" },
+    { name = "Zach Aysan" },
+    { name = "Francesco Lo Franco" },
+    { name = "Rodrigo López Dato" },
+]
+maintainers = [{ name = "Flagsmith Team", email = "support@flagsmith.com" }]
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+readme = "README.md"
+dynamic = ["classifiers"]
+
+[project.urls]
+Download = "https://github.com/flagsmith/flagsmith-common/releases"
+Homepage = "https://flagsmith.com"
+Issues = "https://github.com/flagsmith/flagsmith-common/issues"
+Repository = "https://github.com/flagsmith/flagsmith-common"
+
+[project.scripts]
+flagsmith = "common.core.main:main"
+
+[project.entry-points.pytest11]
+flagsmith-test-tools = "common.test_tools.plugin"
+
+[tool.poetry]
+requires-poetry = ">=2.0"
+classifiers = [
+    "Framework :: Django",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+]
+packages = [{ include = "common", from = "src" }]
+
+[tool.poetry.group.dev.dependencies]
+django-stubs = "^5.1.3"
+djangorestframework-stubs = "^3.15.3"
+mypy = "^1.15.0"
+pre-commit = "*"
+pyfakefs = "^5.7.4"
+pytest = "^8.3.4"
+pytest-asyncio = "^0.25.3"
+pytest-cov = "^6.0.0"
+pytest-django = "^4.10.0"
+pytest-freezegun = "^0.4.2"
+pytest-mock = "^3.14.0"
+requests = "^2.32.3"
+ruff = "*"
+setuptools = "^77.0.3"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+addopts = ['--ds=settings.dev', '-vvvv', '-p', 'no:warnings']
+console_output_style = 'count'
+
+[tool.ruff]
+line-length = 88
+indent-width = 4
+target-version = "py311"
+extend-exclude = ["migrations"]
+
+[tool.ruff.format]
+# Like Black, use double quotes for strings.
+quote-style = "double"
+
+# Like Black, indent with spaces, rather than tabs.
+indent-style = "space"
+
+# Like Black, respect magic trailing commas.
+skip-magic-trailing-comma = false
+
+# Like Black, automatically detect the appropriate line ending.
+line-ending = "auto"
+
+# Enable auto-formatting of code examples in docstrings. Markdown,
+# reStructuredText code/literal blocks and doctests are all supported.
+docstring-code-format = true
+
+# Set the line length limit used when formatting code snippets in
+# docstrings.
+docstring-code-line-length = "dynamic"
+
+[tool.ruff.lint]
+# Establish parity with flake8 + isort
+select = ["C901", "E4", "E7", "E9", "F", "I", "W"]
+ignore = []
+fixable = ["ALL"]
+unfixable = []
+
+[tool.mypy]
+plugins = ["mypy_django_plugin.main"]
+strict = true
+
+[tool.django-stubs]
+django_settings_module = "settings.dev"
+
+[tool.drf-stubs]
+enabled = true

flagsmith_common-1.5.0/src/common/core/app.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class CoreConfig(AppConfig):
+    name = "common.core"
+    label = "common_core"

flagsmith_common-1.5.0/src/common/core/logging.py

@@ -0,0 +1,24 @@
+import json
+import logging
+from typing import Any
+
+
+class JsonFormatter(logging.Formatter):
+    """Custom formatter for json logs."""
+
+    def get_json_record(self, record: logging.LogRecord) -> dict[str, Any]:
+        formatted_message = record.getMessage()
+        json_record = {
+            "levelname": record.levelname,
+            "message": formatted_message,
+            "timestamp": self.formatTime(record, self.datefmt),
+            "logger_name": record.name,
+            "pid": record.process,
+            "thread_name": record.threadName,
+        }
+        if record.exc_info:
+            json_record["exc_info"] = self.formatException(record.exc_info)
+        return json_record
+
+    def format(self, record: logging.LogRecord) -> str:
+        return json.dumps(self.get_json_record(record))

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

@@ -0,0 +1,40 @@
+import logging
+import os
+import sys
+import tempfile
+
+from django.core.management import execute_from_command_line
+
+logger = logging.getLogger(__name__)
+
+
+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]`
+    """
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "settings.dev")
+
+    # Set up Prometheus' multiprocess mode
+    if "PROMETHEUS_MULTIPROC_DIR" not in os.environ:
+        prometheus_multiproc_dir = 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
+
+    # Run Django
+    execute_from_command_line(sys.argv)

flagsmith_common-1.5.0/src/common/core/management/commands/start.py

@@ -0,0 +1,41 @@
+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
+
+
+class Command(BaseCommand):
+    help = "Start the Flagsmith application."
+
+    def create_parser(self, *args: Any, **kwargs: Any) -> CommandParser:
+        return super().create_parser(*args, conflict_handler="resolve", **kwargs)
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        add_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)
+
+    def initialise(self) -> None:
+        autodiscover_modules("metrics")
+
+    def handle(
+        self,
+        *args: Any,
+        handle_method: Callable[..., None],
+        **options: Any,
+    ) -> None:
+        self.initialise()
+        handle_method(*args, **options)
+
+    def handle_api(self, *args: Any, **options: Any) -> None:
+        run_server(options)

flagsmith_common-1.5.0/src/common/core/metrics.py

@@ -0,0 +1,23 @@
+import prometheus_client
+
+from common.core.utils import get_version_info
+
+flagsmith_build_info = prometheus_client.Gauge(
+    "flagsmith_build_info",
+    "Flagsmith version and build information",
+    ["ci_commit_sha", "version"],
+    multiprocess_mode="livemax",
+)
+
+
+def advertise() -> None:
+    # Advertise Flagsmith build info.
+    version_info = get_version_info()
+
+    flagsmith_build_info.labels(
+        ci_commit_sha=version_info["ci_commit_sha"],
+        version=version_info.get("package_versions", {}).get(".") or "unknown",
+    ).set(1)
+
+
+advertise()

flagsmith_common-1.5.0/src/common/core/urls.py

@@ -0,0 +1,17 @@
+from django.conf import settings
+from django.urls import include, re_path
+
+from common.core import views
+
+urlpatterns = [
+    re_path(r"^version/?", views.version_info),
+    re_path(r"^health/liveness/?", views.version_info),
+    re_path(r"^health/readiness/?", include("health_check.urls", namespace="health")),
+    re_path(r"^health", include("health_check.urls", namespace="health-deprecated")),
+    # Aptible health checks must be on /healthcheck and cannot redirect
+    # see https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks
+    re_path(r"^healthcheck", include("health_check.urls", namespace="health-aptible")),
+]
+
+if settings.PROMETHEUS_ENABLED:
+    urlpatterns += [re_path(r"^metrics/?", views.metrics)]

flagsmith_common-1.5.0/src/common/core/utils.py

@@ -0,0 +1,90 @@
+import json
+import pathlib
+from functools import lru_cache
+from typing import NotRequired, TypedDict
+
+from django.conf import settings
+from django.contrib.auth import get_user_model
+from django.contrib.auth.models import AbstractBaseUser
+from django.db.models import Manager
+
+UNKNOWN = "unknown"
+VERSIONS_INFO_FILE_LOCATION = ".versions.json"
+
+
+class SelfHostedData(TypedDict):
+    has_users: bool
+    has_logins: bool
+
+
+class VersionInfo(TypedDict):
+    ci_commit_sha: str
+    image_tag: str
+    has_email_provider: bool
+    is_enterprise: bool
+    is_saas: bool
+    self_hosted_data: SelfHostedData | None
+    package_versions: NotRequired[dict[str, str]]
+
+
+@lru_cache()
+def is_enterprise() -> bool:
+    return pathlib.Path("./ENTERPRISE_VERSION").exists()
+
+
+@lru_cache()
+def is_saas() -> bool:
+    return pathlib.Path("./SAAS_DEPLOYMENT").exists()
+
+
+@lru_cache()
+def has_email_provider() -> bool:
+    match settings.EMAIL_BACKEND:
+        case "django.core.mail.backends.smtp.EmailBackend":
+            return settings.EMAIL_HOST_USER is not None
+        case "sgbackend.SendGridBackend":
+            return settings.SENDGRID_API_KEY is not None
+        case "django_ses.SESBackend":
+            return settings.AWS_SES_REGION_ENDPOINT is not None
+        case _:
+            return False
+
+
+def get_version_info() -> VersionInfo:
+    """Reads the version info baked into src folder of the docker container"""
+    _is_saas = is_saas()
+    version_json: VersionInfo = {
+        "ci_commit_sha": get_file_contents("./CI_COMMIT_SHA") or UNKNOWN,
+        "image_tag": UNKNOWN,
+        "has_email_provider": has_email_provider(),
+        "is_enterprise": is_enterprise(),
+        "is_saas": _is_saas,
+        "self_hosted_data": None,
+    }
+
+    manifest_versions_content = get_file_contents(VERSIONS_INFO_FILE_LOCATION)
+
+    if manifest_versions_content:
+        manifest_versions = json.loads(manifest_versions_content)
+        version_json["package_versions"] = manifest_versions
+        version_json["image_tag"] = manifest_versions["."]
+
+    if not _is_saas:
+        user_objects: Manager[AbstractBaseUser] = getattr(get_user_model(), "objects")
+
+        version_json["self_hosted_data"] = {
+            "has_users": user_objects.exists(),
+            "has_logins": user_objects.filter(last_login__isnull=False).exists(),
+        }
+
+    return version_json
+
+
+@lru_cache()
+def get_file_contents(file_path: str) -> str | None:
+    """Attempts to read a file from the filesystem and return the contents"""
+    try:
+        with open(file_path) as f:
+            return f.read().replace("\n", "")
+    except FileNotFoundError:
+        return None

flagsmith_common-1.5.0/src/common/core/views.py

@@ -0,0 +1,23 @@
+import logging
+
+import prometheus_client
+from django.http import HttpResponse, JsonResponse
+from rest_framework.request import Request
+
+from common.core import utils
+from common.prometheus.utils import get_registry
+
+logger = logging.getLogger(__name__)
+
+
+def version_info(request: Request) -> JsonResponse:
+    return JsonResponse(utils.get_version_info())
+
+
+def metrics(request: Request) -> HttpResponse:
+    registry = get_registry()
+    metrics_page = prometheus_client.generate_latest(registry)
+    return HttpResponse(
+        metrics_page,
+        content_type=prometheus_client.CONTENT_TYPE_LATEST,
+    )

flagsmith_common-1.5.0/src/common/environments/permissions.py

@@ -0,0 +1,15 @@
+# Maintain a list of permissions here
+VIEW_ENVIRONMENT = "VIEW_ENVIRONMENT"
+UPDATE_FEATURE_STATE = "UPDATE_FEATURE_STATE"
+MANAGE_IDENTITIES = "MANAGE_IDENTITIES"
+VIEW_IDENTITIES = "VIEW_IDENTITIES"
+CREATE_CHANGE_REQUEST = "CREATE_CHANGE_REQUEST"
+APPROVE_CHANGE_REQUEST = "APPROVE_CHANGE_REQUEST"
+MANAGE_SEGMENT_OVERRIDES = "MANAGE_SEGMENT_OVERRIDES"
+
+TAG_SUPPORTED_PERMISSIONS = [
+    UPDATE_FEATURE_STATE,
+    CREATE_CHANGE_REQUEST,
+    APPROVE_CHANGE_REQUEST,
+    MANAGE_SEGMENT_OVERRIDES,
+]