PyPI - plain.admin - Versions diffs - 0.25.0__tar.gz → 0.26.0__tar.gz - Mend

plain.admin 0.25.0tar.gz → 0.26.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (94) hide show

{plain_admin-0.25.0 → plain_admin-0.26.0}/.gitignore RENAMED Viewed

@@ -11,3 +11,5 @@ plain*/tests/.plain
 # Ottobot
 .aider*
+/llms-full.txt

plain_admin-0.26.0/PKG-INFO ADDED Viewed

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: plain.admin
+Version: 0.26.0
+Summary: Admin dashboard and tools for Plain.
+Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: plain-auth<1.0.0
+Requires-Dist: plain-htmx<1.0.0
+Requires-Dist: plain-tailwind<1.0.0
+Requires-Dist: plain<1.0.0
+Requires-Dist: sqlparse>=0.2.2
+Description-Content-Type: text/markdown
+# plain.admin
+**Manage your app with a backend interface.**
+The Plain Admin provides a combination of built-in views and the flexibility to create your own. You can use it to quickly get visibility into your app's data and to manage it.
+![Plain Admin user example](https://assets.plainframework.com/docs/plain-pageviews-user.png)
+## Installation
+Install the `plain.admin` package and its dependencies.
+```console
+uv add plain.admin
+```
+The admin uses a combination of other Plain packages, most of which you will already have installed. Ultimately, your settings will look something like this:
+```python
+# app/settings.py
+INSTALLED_PACKAGES = [
+    "plain.models",
+    "plain.tailwind",
+    "plain.auth",
+    "plain.sessions",
+    "plain.htmx",
+    "plain.admin",
+    "plain.elements",
+    # other packages...
+]
+AUTH_USER_MODEL = "users.User"
+AUTH_LOGIN_URL = "login"
+MIDDLEWARE = [
+    "plain.sessions.middleware.SessionMiddleware",
+    "plain.auth.middleware.AuthenticationMiddleware",
+    "plain.admin.AdminMiddleware",
+]
+```
+Your User model is expected to have an `is_admin` field (or attribute) for checking who has permission to access the admin.
+```python
+# app/users/models.py
+from plain import models
+@models.register_model
+class User(models.Model):
+    is_admin = models.BooleanField(default=False)
+    # other fields...
+```
+To make the admin accessible, add the `AdminRouter` to your root URLs.
+```python
+# app/urls.py
+from plain.admin.urls import AdminRouter
+from plain.urls import Router, include, path
+from . import views
+class AppRouter(Router):
+    namespace = ""
+    urls = [
+        include("admin/", AdminRouter),
+        path("login/", views.LoginView, name="login"),
+        path("logout/", LogoutView, name="logout"),
+        # other urls...
+    ]
+```
+Optionally, you can add the admin toolbar to your base template. The toolbar will appear when `settings.DEBUG` or when `request.user.is_admin` (including in production!).
+```html
+<!-- app/templates/base.html -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{ html_title|default("My App") }}</title>
+    {% tailwind_css %}
+</head>
+<body>
+    {% block content required %}{% endblock %}
+    {% toolbar %}
+</body>
+</html>
+```
+## Admin viewsets
+The most common use of the admin is to display and manage your `plain.models`. To do this, create a viewset with a set of inner views.
+```python
+# app/users/admin.py
+from plain.admin.views import (
+    AdminModelDetailView,
+    AdminModelListView,
+    AdminModelUpdateView,
+    AdminViewset,
+    register_viewset,
+)
+from plain.models.forms import ModelForm
+from .models import User
+class UserForm(ModelForm):
+    class Meta:
+        model = User
+        fields = ["email"]
+@register_viewset
+class UserAdmin(AdminViewset):
+    class ListView(AdminModelListView):
+        model = User
+        fields = [
+            "id",
+            "email",
+            "created_at__date",
+        ]
+        queryset_order = ["-created_at"]
+        search_fields = [
+            "email",
+        ]
+    class DetailView(AdminModelDetailView):
+        model = User
+    class UpdateView(AdminModelUpdateView):
+        template_name = "admin/users/user_form.html"
+        model = User
+        form_class = UserForm
+```
+The [`AdminViewset`](./views/viewsets.py) will automatically recognize inner views named `ListView`, `CreateView`, `DetailView`, `UpdateView`, and `DeleteView`. It will interlink these views automatically in the UI and form success URLs. You can define additional views too, but you will need to implement a couple methods to hook them up.
+## Admin cards
+TODO
+## Admin forms
+TODO
+## Toolbar
+TODO
+## Impersonate
+TODO
+## Querystats
+TODO

plain_admin-0.26.0/plain/admin/README.md ADDED Viewed

@@ -0,0 +1,163 @@
+# plain.admin
+**Manage your app with a backend interface.**
+The Plain Admin provides a combination of built-in views and the flexibility to create your own. You can use it to quickly get visibility into your app's data and to manage it.
+![Plain Admin user example](https://assets.plainframework.com/docs/plain-pageviews-user.png)
+## Installation
+Install the `plain.admin` package and its dependencies.
+```console
+uv add plain.admin
+```
+The admin uses a combination of other Plain packages, most of which you will already have installed. Ultimately, your settings will look something like this:
+```python
+# app/settings.py
+INSTALLED_PACKAGES = [
+    "plain.models",
+    "plain.tailwind",
+    "plain.auth",
+    "plain.sessions",
+    "plain.htmx",
+    "plain.admin",
+    "plain.elements",
+    # other packages...
+]
+AUTH_USER_MODEL = "users.User"
+AUTH_LOGIN_URL = "login"
+MIDDLEWARE = [
+    "plain.sessions.middleware.SessionMiddleware",
+    "plain.auth.middleware.AuthenticationMiddleware",
+    "plain.admin.AdminMiddleware",
+]
+```
+Your User model is expected to have an `is_admin` field (or attribute) for checking who has permission to access the admin.
+```python
+# app/users/models.py
+from plain import models
+@models.register_model
+class User(models.Model):
+    is_admin = models.BooleanField(default=False)
+    # other fields...
+```
+To make the admin accessible, add the `AdminRouter` to your root URLs.
+```python
+# app/urls.py
+from plain.admin.urls import AdminRouter
+from plain.urls import Router, include, path
+from . import views
+class AppRouter(Router):
+    namespace = ""
+    urls = [
+        include("admin/", AdminRouter),
+        path("login/", views.LoginView, name="login"),
+        path("logout/", LogoutView, name="logout"),
+        # other urls...
+    ]
+```
+Optionally, you can add the admin toolbar to your base template. The toolbar will appear when `settings.DEBUG` or when `request.user.is_admin` (including in production!).
+```html
+<!-- app/templates/base.html -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{ html_title|default("My App") }}</title>
+    {% tailwind_css %}
+</head>
+<body>
+    {% block content required %}{% endblock %}
+    {% toolbar %}
+</body>
+</html>
+```
+## Admin viewsets
+The most common use of the admin is to display and manage your `plain.models`. To do this, create a viewset with a set of inner views.
+```python
+# app/users/admin.py
+from plain.admin.views import (
+    AdminModelDetailView,
+    AdminModelListView,
+    AdminModelUpdateView,
+    AdminViewset,
+    register_viewset,
+)
+from plain.models.forms import ModelForm
+from .models import User
+class UserForm(ModelForm):
+    class Meta:
+        model = User
+        fields = ["email"]
+@register_viewset
+class UserAdmin(AdminViewset):
+    class ListView(AdminModelListView):
+        model = User
+        fields = [
+            "id",
+            "email",
+            "created_at__date",
+        ]
+        queryset_order = ["-created_at"]
+        search_fields = [
+            "email",
+        ]
+    class DetailView(AdminModelDetailView):
+        model = User
+    class UpdateView(AdminModelUpdateView):
+        template_name = "admin/users/user_form.html"
+        model = User
+        form_class = UserForm
+```
+The [`AdminViewset`](./views/viewsets.py) will automatically recognize inner views named `ListView`, `CreateView`, `DetailView`, `UpdateView`, and `DeleteView`. It will interlink these views automatically in the UI and form success URLs. You can define additional views too, but you will need to implement a couple methods to hook them up.
+## Admin cards
+TODO
+## Admin forms
+TODO
+## Toolbar
+TODO
+## Impersonate
+TODO
+## Querystats
+TODO

plain_admin-0.26.0/plain/admin/default_settings.py ADDED Viewed

@@ -0,0 +1,4 @@
+ADMIN_TOOLBAR_CLASS = "plain.admin.toolbar.Toolbar"
+ADMIN_TOOLBAR_VERSION: str = "dev"
+ADMIN_QUERYSTATS_IGNORE_URLS: list[str] = ["/assets/.*"]

{plain_admin-0.25.0 → plain_admin-0.26.0}/plain/admin/querystats/core.py RENAMED Viewed

@@ -8,6 +8,8 @@ from plain.utils.functional import cached_property
 IGNORE_STACK_FILES = [
     "threading",
+    "concurrent/futures",
+    "functools.py",
     "socketserver",
     "wsgiref",
     "gunicorn",
@@ -15,11 +17,8 @@ IGNORE_STACK_FILES = [
     "sentry_sdk",
     "querystats/core",
     "plain/template/base",
-    "plain/utils/decorators",
-    "plain/db",
-    "plain/utils/functional",
-    "plain/core/servers",
-    "plain/core/handlers",
+    "plain/models",
+    "plain/internal",
 ]
@@ -74,7 +73,7 @@ class QueryStats:
         # if many, then X times is len(params)
-        current_query["result"] = result
+        # current_query["result"] = result
         current_query["duration"] = time.monotonic() - start
@@ -126,7 +125,7 @@ class QueryStats:
             "num_duplicate_queries": self.num_duplicate_queries,
         }
-    def as_context_dict(self):
+    def as_context_dict(self, request):
         # If we don't create a dict, the instance of this class
         # is lost before we can use it in the template
         for query in self.queries:
@@ -137,10 +136,15 @@ class QueryStats:
             if duplicates:
                 query["duplicate_count"] = duplicates
-        summary = self.as_summary_dict()
         return {
-            **summary,
+            **self.as_summary_dict(),
+            "request": {
+                "path": request.path,
+                "method": request.method,
+                "headers": dict(request.headers),
+                "unique_id": request.unique_id,
+            },
+            "timestamp": time.time(),
             "total_time_display": self.total_time_display,
             "queries": self.queries,
         }

{plain_admin-0.25.0 → plain_admin-0.26.0}/plain/admin/querystats/middleware.py RENAMED Viewed

@@ -1,26 +1,19 @@
 import json
 import logging
 import re
-import threading
-from plain.http import ResponseRedirect
 from plain.json import PlainJSONEncoder
 from plain.models import connection
 from plain.runtime import settings
-from plain.urls import reverse
 from .core import QueryStats
 try:
-    try:
-        import psycopg
-    except ImportError:
-        import psycopg2 as psycopg
+    import psycopg
 except ImportError:
     psycopg = None
 logger = logging.getLogger(__name__)
-_local = threading.local()
 class QueryStatsJSONEncoder(PlainJSONEncoder):
@@ -28,8 +21,11 @@ class QueryStatsJSONEncoder(PlainJSONEncoder):
         try:
             return super().default(obj)
         except TypeError:
-            if psycopg and isinstance(obj, psycopg._json.Json):
-                return obj.adapted
+            print(type(obj))
+            if psycopg and isinstance(obj, psycopg.types.json.Json):
+                return obj.obj
+            elif psycopg and isinstance(obj, psycopg.types.json.Jsonb):
+                return obj.obj
             else:
                 raise
@@ -38,7 +34,7 @@ class QueryStatsMiddleware:
     def __init__(self, get_response):
         self.get_response = get_response
         self.ignore_url_patterns = [
-            re.compile(url) for url in settings.QUERYSTATS_IGNORE_URLS
+            re.compile(url) for url in settings.ADMIN_QUERYSTATS_IGNORE_URLS
         ]
     def should_ignore_request(self, request):
@@ -49,41 +45,49 @@ class QueryStatsMiddleware:
         return False
     def __call__(self, request):
-        if request.GET.get("querystats") == "disable":
+        """
+        Enables querystats for the current request.
+        If DEBUG or an admin, then Server-Timing headers are always added to the response.
+        Full querystats are only stored in the session if they are manually enabled.
+        """
+        if self.should_ignore_request(request):
             return self.get_response(request)
-        querystats = QueryStats(
-            # Only want these if we're getting ready to show it
-            include_tracebacks=request.GET.get("querystats") == "store"
-        )
+        session_querystats_enabled = "querystats" in request.session
+        querystats = QueryStats(include_tracebacks=session_querystats_enabled)
         with connection.execute_wrapper(querystats):
             # Have to wrap this first call so it is included in the querystats,
             # but we don't have to wrap everything else unless we are admin or debug
             is_admin = self.is_admin_request(request)
-        if (settings.DEBUG or is_admin) and not self.should_ignore_request(request):
-            # Persist it on the thread
-            _local.querystats = querystats
-            with connection.execute_wrapper(_local.querystats):
+        if settings.DEBUG or is_admin:
+            with connection.execute_wrapper(querystats):
                 response = self.get_response(request)
             if settings.DEBUG:
                 # TODO logging settings
-                logger.debug("Querystats: %s", _local.querystats)
+                logger.debug("Querystats: %s", querystats)
             # Make current querystats available on the current page
             # by using the server timing API which can be parsed client-side
-            response.headers["Server-Timing"] = _local.querystats.as_server_timing()
+            response.headers["Server-Timing"] = querystats.as_server_timing()
-            if request.GET.get("querystats") == "store":
-                request.session["querystats"] = json.dumps(
-                    _local.querystats.as_context_dict(), cls=QueryStatsJSONEncoder
+            if session_querystats_enabled and querystats.num_queries > 0:
+                request.session["querystats"][request.unique_id] = json.dumps(
+                    querystats.as_context_dict(request), cls=QueryStatsJSONEncoder
                 )
-                return ResponseRedirect(reverse("querystats:querystats"))
-            del _local.querystats
+                # Keep 30 requests max, in case it is left on by accident
+                if len(request.session["querystats"]) > 30:
+                    del request.session["querystats"][
+                        list(request.session["querystats"])[0]
+                    ]
+                # Did a deeper modification to the session dict...
+                request.session.modified = True
             return response

plain_admin-0.26.0/plain/admin/querystats/views.py ADDED Viewed

@@ -0,0 +1,48 @@
+import json
+from plain.auth.views import AuthViewMixin
+from plain.http import ResponseRedirect
+from plain.views import TemplateView
+class QuerystatsView(AuthViewMixin, TemplateView):
+    template_name = "querystats/querystats.html"
+    admin_required = True
+    def get_template_context(self):
+        context = super().get_template_context()
+        querystats = self.request.session.get("querystats", {})
+        for request_id, json_data in querystats.items():
+            try:
+                querystats[request_id] = json.loads(json_data)
+            except json.JSONDecodeError:
+                # If decoding fails, remove the entry from the dictionary
+                del querystats[request_id]
+        # Order them by timestamp
+        querystats = dict(
+            sorted(
+                querystats.items(),
+                key=lambda item: item[1].get("timestamp", ""),
+                reverse=True,
+            )
+        )
+        context["querystats"] = querystats
+        return context
+    def post(self):
+        querystats_action = self.request.POST["querystats_action"]
+        if querystats_action == "enable":
+            self.request.session.setdefault("querystats", {})
+        elif querystats_action == "clear":
+            self.request.session["querystats"] = {}
+        elif querystats_action == "disable" and "querystats" in self.request.session:
+            del self.request.session["querystats"]
+        # Redirect back to the page that submitted the form
+        return ResponseRedirect(self.request.POST.get("redirect_url", "."))

plain_admin-0.26.0/plain/admin/templates/querystats/querystats.html ADDED Viewed

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Querystats</title>
+    {% tailwind_css %}
+</head>
+<body class="bg-stone-950 text-stone-300">
+    <div class="flex items-center justify-between px-6 py-4">
+        <h1 class="text-lg font-semibold">Querystats</h1>
+        <div class="flex items-center space-x-2">
+            <form method="post" action=".">
+                {{ csrf_input }}
+                <input type="hidden" name="querystats_action" value="clear">
+                <button type="submit" class="px-2 py-px text-sm rounded-sm bg-stone-700 text-stone-300 hover:bg-stone-600 cursor-pointer whitespace-nowrap">Clear</button>
+            </form>
+            <form method="post" action=".">
+                {{ csrf_input }}
+                <input type="hidden" name="querystats_action" value="disable">
+                <button type="submit" class="px-2 py-px text-sm rounded-sm bg-stone-700 text-stone-300 hover:bg-stone-600 cursor-pointer whitespace-nowrap">Disable</button>
+            </form>
+        </div>
+    </div>
+    <div class="space-y-6 px-6 py-4">
+        {% for request_id, qs in querystats.items() %}
+        <div class="p-3 bg-white/5 rounded">
+            <div class="flex justify-between items-center">
+                <div>
+                    <h2 class="font-medium"><span class="font-semibold">{{ qs.request.method }}</span> {{ qs.request.path }}</h2>
+                    <p class="text-sm text-stone-400">{{ qs.summary }}</p>
+                </div>
+                <div class=text-xs>
+                    <p>Request ID <code>{{ qs.request.unique_id }}</code></p>
+                    <p>Timestamp {{ qs.timestamp }}</p>
+                    <details>
+                        <summary>Headers</summary>
+                        <pre><code>{{ qs.request.get("headers", {})|pprint }}</code></pre>
+                    </details>
+                </div>
+            </div>
+            <div class="flex w-full mt-5 overflow-auto rounded-sm">
+                {% for query in qs.queries %}
+                <a href="#query-{{ loop.index }}"
+                    {{ loop.cycle('class=\"h-4 bg-amber-300\"', 'class=\"h-4 bg-amber-400\"', 'class="h-4 bg-amber-500"', 'class="h-4 bg-amber-600"')|safe }}
+                    title="[{{ query.duration_display }}] {{ query.sql_display }}"
+                    style="width: {{ query.duration / qs.total_time * 100 }}%">
+                </a>
+                {% endfor %}
+            </div>
+            <div class="mt-4 space-y-3 text-xs">
+                {% for query in qs.queries %}
+                <details id="query-{{ loop.index }}" class="p-2 rounded bg-zinc-800">
+                    <summary class="truncate">
+                        <div class="float-right px-2 py-px mb-px ml-2 text-xs rounded-full bg-zinc-700">
+                            <span>{{ query.duration_display }}</span>
+                            {% if query.duplicate_count is defined %}
+                            <span class="text-red-500">&nbsp; duplicated {{ query.duplicate_count }} times</span>
+                            {% endif %}
+                            {#
+                            <div>many {{ query.many }}</div>
+                            <div>result {{ query.result }}</div>
+                            #}
+                        </div>
+                        <code class="font-mono">{{ query.sql }}</code>
+                    </summary>
+                    <div class="space-y-3 mt-3">
+                        <div>
+                            <pre><code class="font-mono whitespace-pre-wrap text-zinc-100">{{ query.sql_display }}</code></pre>
+                        </div>
+                        <div class="text-zinc-400">
+                            <span class="font-medium">Parameters</span>
+                            <pre><code class="font-mono">{{ query.params|pprint }}</code></pre>
+                        </div>
+                        <details>
+                            <summary>Traceback</summary>
+                            <pre><code class="block overflow-x-auto font-mono text-xs">{{ query.tb }}</code></pre>
+                        </details>
+                    </div>
+                </details>
+                {% else %}
+                <div>No queries...</div>
+                {% endfor %}
+            </div>
+        </div>
+        {% else %}
+        <div class="text-center">
+            {% if "querystats" in request.session %}
+            <div class="text-stone-500">Querystats are enabled but nothing has been tracked yet.</div>
+            {% else %}
+            <form method="post" action=".">
+                {{ csrf_input }}
+                <input type="hidden" name="querystats_action" value="enable">
+                <button type="submit" class="px-2 rounded-sm bg-stone-700 text-stone-300 hover:bg-stone-600 cursor-pointer whitespace-nowrap">Enable querystats</button>
+            </form>
+            {% endif %}
+        </div>
+        {% endfor %}
+    </div>
+</body>
+</html>

plain.admin 0.25.0__tar.gz → 0.26.0__tar.gz

plain.admin 0.25.0tar.gz → 0.26.0tar.gz