plain.flags 0.0.0__tar.gz

plain_flags-0.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Dropseed, LLC
+
+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.

plain_flags-0.0.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.1
+Name: plain.flags
+Version: 0.0.0
+Summary: 
+Author: Dave Gaeddert
+Author-email: dave.gaeddert@dropseed.dev
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12

plain_flags-0.0.0/plain/flags/README.md

@@ -0,0 +1,103 @@
+# plain-flags
+
+Local feature flags via database models.
+
+Custom flags are written as subclasses of [`Flag`](./flags.py).
+You define the flag's "key" and initial value,
+and the results will be stored in the database for future reference.
+
+```python
+# app/flags.py
+from plain.flags import Flag
+
+
+class FooEnabled(Flag):
+    def __init__(self, user):
+        self.user = user
+
+    def get_key(self):
+        return self.user
+
+    def get_value(self):
+        # Initially all users will have this feature disabled
+        # and we'll enable them manually in the admin
+        return False
+```
+
+Use flags in HTML templates:
+
+```html
+{% if flags.FooEnabled(request.user) %}
+    <p>Foo is enabled for you!</p>
+{% else %}
+    <p>Foo is disabled for you.</p>
+{% endif %}
+```
+
+Or in Python:
+
+```python
+import flags
+
+
+print(flags.FooEnabled(user).value)
+```
+
+## Installation
+
+```python
+INSTALLED_PACKAGES = [
+    ...
+    "plain.flags",
+]
+```
+
+Create a `flags.py` at the top of your `app` (or point `settings.FLAGS_MODULE` to a different location).
+
+## Advanced usage
+
+Ultimately you can do whatever you want inside of `get_key` and `get_value`.
+
+```python
+class OrganizationFeature(Flag):
+    url_param_name = ""
+
+    def __init__(self, request=None, organization=None):
+        # Both of these are optional, but will usually both be given
+        self.request = request
+        self.organization = organization
+
+    def get_key(self):
+        if (
+            self.url_param_name
+            and self.request
+            and self.url_param_name in self.request.GET
+        ):
+            return None
+
+        if not self.organization:
+            # Don't save the flag result for PRs without an organization
+            return None
+
+        return self.organization
+
+    def get_value(self):
+        if self.url_param_name and self.request:
+            if self.request.GET.get(self.url_param_name) == "1":
+                return True
+
+            if self.request.GET.get(self.url_param_name) == "0":
+                return False
+
+        if not self.organization:
+            return False
+
+        # All organizations will start with False,
+        # and I'll override in the DB for the ones that should be True
+        return False
+
+
+class AIEnabled(OrganizationFeature):
+    pass
+
+```

plain_flags-0.0.0/plain/flags/__init__.py

@@ -0,0 +1,3 @@
+from .flags import Flag
+
+__all__ = ["Flag"]

plain_flags-0.0.0/plain/flags/admin.py

@@ -0,0 +1,75 @@
+from functools import cached_property
+
+from plain.models.forms import ModelForm
+from plain.staff.admin.cards import Card
+from plain.staff.admin.views import (
+    AdminModelDetailView,
+    AdminModelListView,
+    AdminModelUpdateView,
+    AdminModelViewset,
+    register_viewset,
+)
+
+from .models import Flag, FlagResult
+
+
+class UnusedFlagsCard(Card):
+    title = "Unused Flags"
+
+    @cached_property
+    def flag_errors(self):
+        return Flag.check(databases=["default"])
+
+    def get_number(self):
+        return len(self.flag_errors)
+
+    def get_text(self):
+        return "\n".join(str(e.msg) for e in self.flag_errors)
+
+
+@register_viewset
+class FlagAdmin(AdminModelViewset):
+    class ListView(AdminModelListView):
+        model = Flag
+        fields = ["name", "enabled", "created_at__date", "used_at__date", "uuid"]
+        search_fields = ["name", "description"]
+        cards = [UnusedFlagsCard]
+        nav_section = "Feature flags"
+
+    class DetailView(AdminModelDetailView):
+        model = Flag
+
+
+class FlagResultForm(ModelForm):
+    class Meta:
+        model = FlagResult
+        fields = ["key", "value"]
+
+
+@register_viewset
+class FlagResultAdmin(AdminModelViewset):
+    class ListView(AdminModelListView):
+        model = FlagResult
+        title = "Flag results"
+        fields = [
+            "flag",
+            "key",
+            "value",
+            "created_at__date",
+            "updated_at__date",
+            "uuid",
+        ]
+        search_fields = ["flag__name", "key"]
+        nav_section = "Feature flags"
+
+        def get_initial_queryset(self):
+            return self.model.objects.all().select_related("flag")
+
+    class DetailView(AdminModelDetailView):
+        model = FlagResult
+        title = "Flag result"
+
+    class UpdateView(AdminModelUpdateView):
+        model = FlagResult
+        title = "Update flag result"
+        form_class = FlagResultForm

plain_flags-0.0.0/plain/flags/bridge.py

@@ -0,0 +1,28 @@
+from plain.runtime import settings
+
+from . import exceptions
+from .flags import Flag
+
+
+def get_flags_module():
+    flags_module = settings.FLAGS_MODULE
+
+    try:
+        return __import__(flags_module)
+    except ImportError as e:
+        raise exceptions.FlagImportError(
+            f"Could not import {flags_module} module"
+        ) from e
+
+
+def get_flag_class(flag_name: str) -> Flag:
+    flags_module = get_flags_module()
+
+    try:
+        flag_class = getattr(flags_module, flag_name)
+    except AttributeError as e:
+        raise exceptions.FlagImportError(
+            f"Could not find {flag_name} in {flags_module} module"
+        ) from e
+
+    return flag_class

plain_flags-0.0.0/plain/flags/config.py

@@ -0,0 +1,6 @@
+from plain.packages import PackageConfig
+
+
+class ForgeflagsConfig(PackageConfig):
+    name = "plain.flags"
+    label = "plainflags"  # Primarily for migrations

plain_flags-0.0.0/plain/flags/default_settings.py

@@ -0,0 +1 @@
+FLAGS_MODULE: str = "flags"

plain_flags-0.0.0/plain/flags/exceptions.py

@@ -0,0 +1,10 @@
+class FlagError(Exception):
+    pass
+
+
+class FlagDisabled(FlagError):
+    pass
+
+
+class FlagImportError(FlagError):
+    pass

plain_flags-0.0.0/plain/flags/flags.py

@@ -0,0 +1,105 @@
+import logging
+from typing import Any
+
+from plain.runtime import settings
+from plain.utils import timezone
+from plain.utils.functional import cached_property
+
+from . import exceptions
+from .utils import coerce_key
+
+logger = logging.getLogger(__name__)
+
+
+class Flag:
+    def get_key(self) -> Any:
+        """
+        Determine a unique key for this instance of the flag.
+        This should be a quick operation, as it will be called on every use of the flag.
+
+        For convenience, you can return an instance of a Plain Model
+        and it will be converted to a string automatically.
+
+        Return a falsy value if you don't want to store the flag result.
+        """
+        raise NotImplementedError
+
+    def get_value(self) -> Any:
+        """
+        Compute the resulting value of the flag.
+
+        The value needs to be JSON serializable.
+
+        If get_key() returns a value, this will only be called once per key
+        and then subsequent calls will return the saved value from the DB.
+        """
+        raise NotImplementedError
+
+    def get_db_name(self) -> str:
+        """
+        Should basically always be the name of the class.
+        But this is overridable in case of renaming/refactoring/importing.
+        """
+        return self.__class__.__name__
+
+    def retrieve_or_compute_value(self) -> Any:
+        """
+        Retrieve the value from the DB if it exists,
+        otherwise compute the value and save it to the DB.
+        """
+        from .models import Flag, FlagResult  # So Plain app is ready...
+
+        # Create an associated DB Flag that we can use to enable/disable
+        # and tie the results to
+        flag_obj, _ = Flag.objects.update_or_create(
+            name=self.get_db_name(),
+            defaults={"used_at": timezone.now()},
+        )
+        if not flag_obj.enabled:
+            msg = f"The {flag_obj} flag has been disabled and should either not be called, or be re-enabled."
+            if settings.DEBUG:
+                raise exceptions.FlagDisabled(msg)
+            else:
+                logger.exception(msg)
+                # Might not be the type of return value expected! Better than totally crashing now though.
+                return None
+
+        key = self.get_key()
+        if not key:
+            # No key, so we always recompute the value and return it
+            return self.get_value()
+
+        key = coerce_key(key)
+
+        try:
+            flag_result = FlagResult.objects.get(flag=flag_obj, key=key)
+            return flag_result.value
+        except FlagResult.DoesNotExist:
+            value = self.get_value()
+            flag_result = FlagResult.objects.create(flag=flag_obj, key=key, value=value)
+            return flag_result.value
+
+    @cached_property
+    def value(self) -> Any:
+        """
+        Cached version of retrieve_or_compute_value()
+        """
+        return self.retrieve_or_compute_value()
+
+    def __bool__(self) -> bool:
+        """
+        Allow for use in boolean expressions.
+        """
+        return bool(self.value)
+
+    def __contains__(self, item) -> bool:
+        """
+        Allow for use in `in` expressions.
+        """
+        return item in self.value
+
+    def __eq__(self, other) -> bool:
+        """
+        Allow for use in `==` expressions.
+        """
+        return self.value == other

plain_flags-0.0.0/plain/flags/jinja.py

@@ -0,0 +1,5 @@
+from .bridge import get_flags_module
+
+globals = {
+    "flags": get_flags_module(),
+}

plain_flags-0.0.0/plain/flags/migrations/0001_initial.py

@@ -0,0 +1,78 @@
+# Generated by Plain 4.1.7 on 2023-03-21 19:54
+
+import uuid
+
+import plain.flags.models
+import plain.models.deletion
+from plain import models
+from plain.models import migrations
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="Flag",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                (
+                    "uuid",
+                    models.UUIDField(default=uuid.uuid4, editable=False, unique=True),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "name",
+                    models.CharField(
+                        max_length=255,
+                        unique=True,
+                        validators=[plain.flags.models.validate_flag_name],
+                    ),
+                ),
+                ("description", models.TextField(blank=True)),
+                ("enabled", models.BooleanField(default=True)),
+                ("used_at", models.DateTimeField(blank=True, null=True)),
+            ],
+        ),
+        migrations.CreateModel(
+            name="FlagResult",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                (
+                    "uuid",
+                    models.UUIDField(default=uuid.uuid4, editable=False, unique=True),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                ("key", models.CharField(max_length=255)),
+                ("value", models.JSONField()),
+                (
+                    "flag",
+                    models.ForeignKey(
+                        on_delete=plain.models.deletion.CASCADE,
+                        to="plainflags.flag",
+                    ),
+                ),
+            ],
+            options={
+                "unique_together": {("flag", "key")},
+            },
+        ),
+    ]

plain_flags-0.0.0/plain/flags/models.py

@@ -0,0 +1,93 @@
+import re
+import uuid
+
+from plain.exceptions import ValidationError
+from plain.models import ProgrammingError, models
+from plain.preflight import Info
+from plain.runtime import settings
+
+from .bridge import get_flag_class
+from .exceptions import FlagImportError
+
+
+def validate_flag_name(value):
+    if not re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", value):
+        raise ValidationError(f"{value} is not a valid Python identifier name")
+
+
+class FlagResult(models.Model):
+    uuid = models.UUIDField(default=uuid.uuid4, editable=False, unique=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    flag = models.ForeignKey("Flag", on_delete=models.CASCADE)
+    key = models.CharField(max_length=255)
+    value = models.JSONField()
+
+    class Meta:
+        unique_together = ("flag", "key")
+
+    def __str__(self):
+        return self.key
+
+
+class Flag(models.Model):
+    uuid = models.UUIDField(default=uuid.uuid4, editable=False, unique=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    name = models.CharField(
+        max_length=255, unique=True, validators=[validate_flag_name]
+    )
+
+    # Optional description that can be filled in after the flag is used/created
+    description = models.TextField(blank=True)
+
+    # To manually disable a flag before completing deleting
+    # (good to disable first to make sure the code doesn't use the flag anymore)
+    enabled = models.BooleanField(default=True)
+
+    # To provide an easier way to see if a flag is still being used
+    used_at = models.DateTimeField(blank=True, null=True)
+
+    def __str__(self):
+        return self.name
+
+    @classmethod
+    def check(cls, **kwargs):
+        """
+        Check for flags that are in the database, but no longer defined in code.
+
+        Only returns Info errors because it is valid to leave them if you're worried about
+        putting the flag back, but they should probably be deleted eventually.
+        """
+        errors = super().check(**kwargs)
+
+        databases = kwargs["databases"]
+        if not databases:
+            return errors
+
+        for database in databases:
+            flag_names = (
+                cls.objects.using(database).all().values_list("name", flat=True)
+            )
+
+            try:
+                flag_names = set(flag_names)
+            except ProgrammingError:
+                # The table doesn't exist yet
+                # (migrations probably haven't run yet),
+                # so we can't check it.
+                continue
+
+            for flag_name in flag_names:
+                try:
+                    get_flag_class(flag_name)
+                except FlagImportError:
+                    errors.append(
+                        Info(
+                            f"Flag {flag_name} is not used.",
+                            hint=f"Remove the flag from the database or define it in the {settings.FLAGS_MODULE} module.",
+                            id="plain.flags.I001",
+                        )
+                    )
+
+        return errors

plain_flags-0.0.0/plain/flags/templates/admin/plainflags/flagresult_form.html

@@ -0,0 +1,8 @@
+{% extends "admin/form.html" %}
+
+{% block form_content %}
+<div class="space-y-4">
+    <admin.InputField label="Key" field=form.key />
+    <admin.InputField label="Value" field=form.value />
+</div>
+{% endblock %}

plain_flags-0.0.0/plain/flags/utils.py

@@ -0,0 +1,17 @@
+from typing import Any
+
+from plain import models
+
+
+def coerce_key(key: Any) -> str:
+    """
+    Converts a flag key to a string for storage in the DB
+    (special handling of model instances)
+    """
+    if isinstance(key, str):
+        return key
+
+    if isinstance(key, models.Model):
+        return f"{key._meta.package_label}.{key._meta.model_name}:{key.pk}"
+
+    return str(key)

plain_flags-0.0.0/pyproject.toml

@@ -0,0 +1,17 @@
+[tool.poetry]
+name = "plain.flags"
+packages = [
+    { include = "plain" },
+]
+version = "0.0.0"
+description = ""
+authors = ["Dave Gaeddert <dave.gaeddert@dropseed.dev>"]
+# readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"