plain.admin 0.14.1__py3-none-any.whl

plain/admin/cards/charts.py

@@ -0,0 +1,153 @@
+from collections import defaultdict
+
+from plain.admin.dates import DatetimeRangeAliases
+from plain.models import Count
+from plain.models.functions import (
+    TruncDate,
+    TruncMonth,
+)
+
+from .base import Card
+
+
+class ChartCard(Card):
+    template_name = "admin/cards/chart.html"
+
+    def get_template_context(self):
+        context = super().get_template_context()
+        context["chart_data"] = self.get_chart_data()
+        return context
+
+    def get_chart_data(self) -> dict:
+        raise NotImplementedError
+
+
+class TrendCard(ChartCard):
+    """
+    A card that renders a trend chart.
+    Primarily intended for use with models, but it can also be customized.
+    """
+
+    model = None
+    datetime_field = None
+    default_display = DatetimeRangeAliases.SINCE_30_DAYS_AGO
+
+    displays = DatetimeRangeAliases
+
+    def get_description(self):
+        datetime_range = DatetimeRangeAliases.to_range(self.get_current_display())
+        return f"{datetime_range.start} to {datetime_range.end}"
+
+    def get_current_display(self):
+        if s := super().get_current_display():
+            return DatetimeRangeAliases.from_value(s)
+        return self.default_display
+
+    def get_trend_data(self) -> list[int | float]:
+        if not self.model or not self.datetime_field:
+            raise NotImplementedError(
+                "model and datetime_field must be set, or get_values must be overridden"
+            )
+
+        datetime_range = DatetimeRangeAliases.to_range(self.get_current_display())
+
+        filter_kwargs = {f"{self.datetime_field}__range": datetime_range.as_tuple()}
+
+        if datetime_range.total_days() < 300:
+            truncator = TruncDate
+            iterator = datetime_range.iter_days
+        else:
+            truncator = TruncMonth
+            iterator = datetime_range.iter_months
+
+        counts_by_date = (
+            self.model.objects.filter(**filter_kwargs)
+            .annotate(chart_date=truncator(self.datetime_field))
+            .values("chart_date")
+            .annotate(chart_date_count=Count("id"))
+        )
+
+        # Will do the zero filling for us on key access
+        date_values = defaultdict(int)
+
+        for row in counts_by_date:
+            date_values[row["chart_date"]] = row["chart_date_count"]
+
+        return {date.strftime("%Y-%m-%d"): date_values[date] for date in iterator()}
+
+    def get_chart_data(self) -> dict:
+        data = self.get_trend_data()
+        trend_labels = list(data.keys())
+        trend_data = list(data.values())
+
+        def calculate_trend_line(data):
+            """
+            Calculate a trend line using basic linear regression.
+            :param data: A list of numeric values representing the y-axis.
+            :return: A list of trend line values (same length as data).
+            """
+            if not data or len(data) < 2:
+                return (
+                    data  # Return the data as-is if not enough points for a trend line
+                )
+
+            n = len(data)
+            x = list(range(n))
+            y = data
+
+            # Calculate the means of x and y
+            x_mean = sum(x) / n
+            y_mean = sum(y) / n
+
+            # Calculate the slope (m) and y-intercept (b) of the line: y = mx + b
+            numerator = sum((x[i] - x_mean) * (y[i] - y_mean) for i in range(n))
+            denominator = sum((x[i] - x_mean) ** 2 for i in range(n))
+            slope = numerator / denominator if denominator != 0 else 0
+            intercept = y_mean - slope * x_mean
+
+            # Calculate the trend line values
+            trend = [slope * xi + intercept for xi in x]
+
+            # if it's all zeros, return nothing
+            if all(v == 0 for v in trend):
+                return []
+
+            return trend
+
+        return {
+            "type": "bar",
+            "data": {
+                "labels": trend_labels,
+                "datasets": [
+                    {
+                        "data": trend_data,
+                    },
+                    {
+                        "data": calculate_trend_line(trend_data),
+                        "type": "line",
+                        "borderColor": "rgba(0, 0, 0, 0.3)",
+                        "borderWidth": 2,
+                        "fill": False,
+                        "pointRadius": 0,  # Optional: Hide points
+                    },
+                ],
+            },
+            # Hide the label
+            # "options": {"legend": {"display": False}},
+            # Hide the scales
+            "options": {
+                "plugins": {"legend": {"display": False}},
+                "scales": {
+                    "x": {
+                        "display": False,
+                    },
+                    "y": {
+                        "suggestedMin": 0,
+                    },
+                },
+                "maintainAspectRatio": False,
+                "elements": {
+                    "bar": {"borderRadius": "3", "backgroundColor": "rgb(28, 25, 23)"}
+                },
+            },
+        }

plain/admin/cards/tables.py

@@ -0,0 +1,26 @@
+from .base import Card
+
+
+class TableCard(Card):
+    template_name = "admin/cards/table.html"
+    size = Card.Sizes.FULL
+
+    headers = []
+    rows = []
+    footers = []
+
+    def get_template_context(self):
+        context = super().get_template_context()
+        context["headers"] = self.get_headers()
+        context["rows"] = self.get_rows()
+        context["footers"] = self.get_footers()
+        return context
+
+    def get_headers(self):
+        return self.headers.copy()
+
+    def get_rows(self):
+        return self.rows.copy()
+
+    def get_footers(self):
+        return self.footers.copy()

plain/admin/config.py

@@ -0,0 +1,21 @@
+from importlib import import_module
+from importlib.util import find_spec
+
+from plain.packages import PackageConfig, packages
+
+
+class Config(PackageConfig):
+    name = "plain.admin"
+    label = "plainadmin"
+
+    def ready(self):
+        def _import_if_exists(module_name):
+            if find_spec(module_name):
+                import_module(module_name)
+
+        # Trigger register calls to fire by importing the modules
+        for package_config in packages.get_package_configs():
+            _import_if_exists(f"{package_config.name}.admin")
+
+        # Also trigger for the root app/admin.py module
+        _import_if_exists("app.admin")

plain/admin/dates.py

@@ -0,0 +1,254 @@
+import datetime
+from calendar import monthrange
+from enum import Enum
+
+from plain.utils import timezone
+
+
+class DatetimeRangeAliases(Enum):
+    TODAY = "Today"
+    THIS_WEEK = "This Week"
+    THIS_WEEK_TO_DATE = "This Week-to-date"
+    THIS_MONTH = "This Month"
+    THIS_MONTH_TO_DATE = "This Month-to-date"
+    THIS_QUARTER = "This Quarter"
+    THIS_QUARTER_TO_DATE = "This Quarter-to-date"
+    THIS_YEAR = "This Year"
+    THIS_YEAR_TO_DATE = "This Year-to-date"
+    LAST_WEEK = "Last Week"
+    LAST_WEEK_TO_DATE = "Last Week-to-date"
+    LAST_MONTH = "Last Month"
+    LAST_MONTH_TO_DATE = "Last Month-to-date"
+    LAST_QUARTER = "Last Quarter"
+    LAST_QUARTER_TO_DATE = "Last Quarter-to-date"
+    LAST_YEAR = "Last Year"
+    LAST_YEAR_TO_DATE = "Last Year-to-date"
+    SINCE_30_DAYS_AGO = "Since 30 Days Ago"
+    SINCE_60_DAYS_AGO = "Since 60 Days Ago"
+    SINCE_90_DAYS_AGO = "Since 90 Days Ago"
+    SINCE_365_DAYS_AGO = "Since 365 Days Ago"
+    NEXT_WEEK = "Next Week"
+    NEXT_4_WEEKS = "Next 4 Weeks"
+    NEXT_MONTH = "Next Month"
+    NEXT_QUARTER = "Next Quarter"
+    NEXT_YEAR = "Next Year"
+
+    # TODO doesn't include anything less than a day...
+    # ex. SINCE_1_HOUR_AGO = "Since 1 Hour Ago"
+
+    def __str__(self):
+        return self.value
+
+    @classmethod
+    def from_value(cls, value):
+        for member in cls:
+            if member.value == value:
+                return member
+        raise ValueError(f"{value} is not a valid value for {cls.__name__}")
+
+    @classmethod
+    def to_range(cls, value: str) -> tuple[datetime.datetime, datetime.datetime]:
+        now = timezone.localtime()
+        start_of_today = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        start_of_week = start_of_today - datetime.timedelta(
+            days=start_of_today.weekday()
+        )
+        start_of_month = start_of_today.replace(day=1)
+        start_of_quarter = start_of_today.replace(
+            month=((start_of_today.month - 1) // 3) * 3 + 1, day=1
+        )
+        start_of_year = start_of_today.replace(month=1, day=1)
+
+        def end_of_day(dt):
+            return dt.replace(hour=23, minute=59, second=59, microsecond=999999)
+
+        def end_of_month(dt):
+            last_day = monthrange(dt.year, dt.month)[1]
+            return end_of_day(dt.replace(day=last_day))
+
+        def end_of_quarter(dt):
+            end_month = ((dt.month - 1) // 3 + 1) * 3
+            return end_of_month(dt.replace(month=end_month))
+
+        def end_of_year(dt):
+            return end_of_month(dt.replace(month=12))
+
+        if value == cls.TODAY:
+            return DatetimeRange(start_of_today, end_of_day(now))
+        if value == cls.THIS_WEEK:
+            return DatetimeRange(
+                start_of_week, end_of_day(start_of_week + datetime.timedelta(days=6))
+            )
+        if value == cls.THIS_WEEK_TO_DATE:
+            return DatetimeRange(start_of_week, now)
+        if value == cls.THIS_MONTH:
+            return DatetimeRange(start_of_month, end_of_month(start_of_month))
+        if value == cls.THIS_MONTH_TO_DATE:
+            return DatetimeRange(start_of_month, now)
+        if value == cls.THIS_QUARTER:
+            return DatetimeRange(start_of_quarter, end_of_quarter(start_of_quarter))
+        if value == cls.THIS_QUARTER_TO_DATE:
+            return DatetimeRange(start_of_quarter, now)
+        if value == cls.THIS_YEAR:
+            return DatetimeRange(start_of_year, end_of_year(start_of_year))
+        if value == cls.THIS_YEAR_TO_DATE:
+            return DatetimeRange(start_of_year, now)
+        if value == cls.LAST_WEEK:
+            last_week_start = start_of_week - datetime.timedelta(days=7)
+            return DatetimeRange(
+                last_week_start,
+                end_of_day(last_week_start + datetime.timedelta(days=6)),
+            )
+        if value == cls.LAST_WEEK_TO_DATE:
+            return DatetimeRange(start_of_week - datetime.timedelta(days=7), now)
+        if value == cls.LAST_MONTH:
+            last_month = (start_of_month - datetime.timedelta(days=1)).replace(day=1)
+            return DatetimeRange(last_month, end_of_month(last_month))
+        if value == cls.LAST_MONTH_TO_DATE:
+            last_month = (start_of_month - datetime.timedelta(days=1)).replace(day=1)
+            return DatetimeRange(last_month, now)
+        if value == cls.LAST_QUARTER:
+            last_quarter = (start_of_quarter - datetime.timedelta(days=1)).replace(
+                day=1
+            )
+            return DatetimeRange(last_quarter, end_of_quarter(last_quarter))
+        if value == cls.LAST_QUARTER_TO_DATE:
+            last_quarter = (start_of_quarter - datetime.timedelta(days=1)).replace(
+                day=1
+            )
+            return DatetimeRange(last_quarter, now)
+        if value == cls.LAST_YEAR:
+            last_year = start_of_year.replace(year=start_of_year.year - 1)
+            return DatetimeRange(last_year, end_of_year(last_year))
+        if value == cls.LAST_YEAR_TO_DATE:
+            last_year = start_of_year.replace(year=start_of_year.year - 1)
+            return DatetimeRange(last_year, now)
+        if value == cls.SINCE_30_DAYS_AGO:
+            return DatetimeRange(now - datetime.timedelta(days=30), now)
+        if value == cls.SINCE_60_DAYS_AGO:
+            return DatetimeRange(now - datetime.timedelta(days=60), now)
+        if value == cls.SINCE_90_DAYS_AGO:
+            return DatetimeRange(now - datetime.timedelta(days=90), now)
+        if value == cls.SINCE_365_DAYS_AGO:
+            return DatetimeRange(now - datetime.timedelta(days=365), now)
+        if value == cls.NEXT_WEEK:
+            next_week_start = start_of_week + datetime.timedelta(days=7)
+            return DatetimeRange(
+                next_week_start,
+                end_of_day(next_week_start + datetime.timedelta(days=6)),
+            )
+        if value == cls.NEXT_4_WEEKS:
+            return DatetimeRange(now, end_of_day(now + datetime.timedelta(days=28)))
+        if value == cls.NEXT_MONTH:
+            next_month = (start_of_month + datetime.timedelta(days=31)).replace(day=1)
+            return DatetimeRange(next_month, end_of_month(next_month))
+        if value == cls.NEXT_QUARTER:
+            next_quarter = (start_of_quarter + datetime.timedelta(days=90)).replace(
+                day=1
+            )
+            return DatetimeRange(next_quarter, end_of_quarter(next_quarter))
+        if value == cls.NEXT_YEAR:
+            next_year = start_of_year.replace(year=start_of_year.year + 1)
+            return DatetimeRange(next_year, end_of_year(next_year))
+        raise ValueError(f"Invalid range: {value}")
+
+
+class DatetimeRange:
+    def __init__(self, start, end):
+        self.start = start
+        self.end = end
+
+        if isinstance(self.start, str) and self.start:
+            self.start = datetime.datetime.fromisoformat(self.start)
+
+        if isinstance(self.end, str) and self.end:
+            self.end = datetime.datetime.fromisoformat(self.end)
+
+        if isinstance(self.start, datetime.date) and not isinstance(
+            self.start, datetime.datetime
+        ):
+            self.start = timezone.localtime().replace(
+                year=self.start.year, month=self.start.month, day=self.start.day
+            )
+
+        if isinstance(self.end, datetime.date) and not isinstance(
+            self.start, datetime.datetime
+        ):
+            self.end = timezone.localtime().replace(
+                year=self.end.year, month=self.end.month, day=self.end.day
+            )
+
+    def as_tuple(self):
+        return (self.start, self.end)
+
+    def total_days(self):
+        return (self.end - self.start).days
+
+    def iter_days(self):
+        """Yields each day in the range."""
+        return iter(
+            self.start.date() + datetime.timedelta(days=i)
+            for i in range(0, self.total_days())
+        )
+
+    def iter_weeks(self):
+        """Yields the start of each week in the range."""
+        current = self.start - datetime.timedelta(days=self.start.weekday())
+        current = current.replace(hour=0, minute=0, second=0, microsecond=0)
+        while current <= self.end:
+            next_week = current + datetime.timedelta(weeks=1)
+            yield current
+            current = next_week
+
+    def iter_months(self):
+        """Yields the start of each month in the range."""
+        current = self.start.replace(day=1)
+        current = current.replace(hour=0, minute=0, second=0, microsecond=0)
+        while current <= self.end:
+            if current.month == 12:
+                next_month = current.replace(year=current.year + 1, month=1)
+            else:
+                next_month = current.replace(month=current.month + 1)
+            yield current
+            current = next_month
+
+    def iter_quarters(self):
+        """Yields the start of each quarter in the range."""
+        current = self.start.replace(month=((self.start.month - 1) // 3) * 3 + 1, day=1)
+        current = current.replace(hour=0, minute=0, second=0, microsecond=0)
+        while current <= self.end:
+            next_quarter_month = ((current.month - 1) // 3 + 1) * 3 + 1
+            if next_quarter_month > 12:
+                next_quarter_month -= 12
+                next_year = current.year + 1
+            else:
+                next_year = current.year
+            next_quarter = datetime.datetime(
+                next_year, next_quarter_month, 1, tzinfo=current.tzinfo
+            )
+            yield current
+            current = next_quarter
+
+    def iter_years(self):
+        """Yields the start of each year in the range."""
+        current = self.start.replace(month=1, day=1)
+        current = current.replace(hour=0, minute=0, second=0, microsecond=0)
+        while current <= self.end:
+            next_year = current.replace(year=current.year + 1)
+            yield current
+            current = next_year
+
+    def __repr__(self):
+        return f"DatetimeRange({self.start}, {self.end})"
+
+    def __str__(self):
+        return f"{self.start} to {self.end}"
+
+    def __eq__(self, other):
+        return self.start == other.start and self.end == other.end
+
+    def __hash__(self):
+        return hash((self.start, self.end))
+
+    def __contains__(self, item):
+        return self.start <= item <= self.end

plain/admin/default_settings.py

@@ -0,0 +1,4 @@
+TOOLBAR_CLASS = "plain.admin.toolbar.Toolbar"
+TOOLBAR_VERSION: str = "dev"
+
+QUERYSTATS_IGNORE_URLS: list[str] = ["/assets/.*"]

plain/admin/impersonate/README.md

@@ -0,0 +1,44 @@
+# plain.impersonate
+
+See what your users see.
+
+A key feature for providing customer support is to be able to view the site through their account.
+With `impersonate` installed, you can impersonate a user by finding them in the Django admin and clicking the "Impersonate" button.
+
+![](/docs/img/impersonate-admin.png)
+
+Then with the [admin toolbar](/docs/plain-toolbar/) enabled, you'll get a notice of the impersonation and a button to exit:
+
+![](/docs/img/impersonate-bar.png)
+
+## Installation
+
+To impersonate users, you need the app, middleware, and URLs:
+
+```python
+# settings.py
+INSTALLED_PACKAGES = INSTALLED_PACKAGES + [
+  "plain.admin.impersonate",
+]
+
+MIDDLEWARE = MIDDLEWARE + [
+  "plain.admin.impersonate.ImpersonateMiddleware",
+]
+```
+
+```python
+# urls.py
+urlpatterns = [
+    # ...
+    path("impersonate/", include("plain.admin.impersonate.urls")),
+]
+```
+
+## Settings
+
+By default, all admin users can impersonate other users.
+
+```python
+# settings.py
+IMPERSONATE_ALLOWED = lambda user: user.is_admin
+```

plain/admin/impersonate/__init__.py

@@ -0,0 +1,3 @@
+from .middleware import ImpersonateMiddleware
+
+__all__ = ["ImpersonateMiddleware"]

plain/admin/impersonate/middleware.py

@@ -0,0 +1,38 @@
+from plain.auth import get_user_model
+from plain.http import ResponseForbidden
+
+from .permissions import can_be_impersonator, can_impersonate_user
+from .views import IMPERSONATE_KEY
+
+
+def get_user_by_pk(pk):
+    UserModel = get_user_model()
+
+    try:
+        return UserModel.objects.get(pk=pk)
+    except UserModel.DoesNotExist:
+        return None
+
+
+class ImpersonateMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        if (
+            IMPERSONATE_KEY in request.session
+            and request.user
+            and can_be_impersonator(request.user)
+        ):
+            user_to_impersonate = get_user_by_pk(request.session[IMPERSONATE_KEY])
+            if user_to_impersonate:
+                if not can_impersonate_user(request.user, user_to_impersonate):
+                    # Can't impersonate this user, remove it and show an error
+                    del request.session[IMPERSONATE_KEY]
+                    return ResponseForbidden()
+
+                # Finally, change the request user and keep a reference to the original
+                request.impersonator = request.user
+                request.user = user_to_impersonate
+
+        return self.get_response(request)

plain/admin/impersonate/permissions.py

@@ -0,0 +1,16 @@
+from . import settings
+
+
+def can_be_impersonator(user):
+    return settings.IMPERSONATE_ALLOWED(user)
+
+
+def can_impersonate_user(impersonator, target_user):
+    if not can_be_impersonator(impersonator):
+        return False
+
+    # You can't impersonate admin users
+    if target_user.is_admin:
+        return False
+
+    return True

plain/admin/impersonate/settings.py

@@ -0,0 +1,8 @@
+from plain.runtime import settings
+
+
+def IMPERSONATE_ALLOWED(user):
+    if hasattr(settings, "IMPERSONATE_ALLOWED"):
+        return settings.IMPERSONATE_ALLOWED(user)
+
+    return user.is_admin

plain/admin/impersonate/urls.py

@@ -0,0 +1,10 @@
+from plain.urls import path
+
+from .views import ImpersonateStartView, ImpersonateStopView
+
+default_namespace = "impersonate"
+
+urlpatterns = [
+    path("stop/", ImpersonateStopView, name="stop"),
+    path("start/<pk>/", ImpersonateStartView, name="start"),
+]

plain/admin/impersonate/views.py

@@ -0,0 +1,23 @@
+from plain.http import ResponseForbidden, ResponseRedirect
+from plain.views import View
+
+from .permissions import can_be_impersonator
+
+IMPERSONATE_KEY = "impersonate"
+
+
+class ImpersonateStartView(View):
+    def get(self):
+        # We *could* already be impersonating, so need to consider that
+        impersonator = getattr(self.request, "impersonator", self.request.user)
+        if impersonator and can_be_impersonator(impersonator):
+            self.request.session[IMPERSONATE_KEY] = self.url_kwargs["pk"]
+            return ResponseRedirect(self.request.GET.get("next", "/"))
+
+        return ResponseForbidden()
+
+
+class ImpersonateStopView(View):
+    def get(self):
+        self.request.session.pop(IMPERSONATE_KEY)
+        return ResponseRedirect(self.request.GET.get("next", "/"))

plain/admin/middleware.py

@@ -0,0 +1,12 @@
+from .impersonate.middleware import ImpersonateMiddleware
+from .querystats.middleware import QueryStatsMiddleware
+
+
+class AdminMiddleware:
+    """All admin-related middleware in a single class."""
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        return QueryStatsMiddleware(ImpersonateMiddleware(self.get_response))(request)