django-admin-home 0.1.0__tar.gz

django_admin_home-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabio Valle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_admin_home-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: django-admin-home
+Version: 0.1.0
+Summary: A tree-navigation sidebar plus a favorites/most-accessed home dashboard for the Django admin
+Author: Fabio Valle
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/fdelvalle/django-admin-home
+Project-URL: Issues, https://github.com/fdelvalle/django-admin-home/issues
+Keywords: django,admin,dashboard,sidebar,navigation,django-admin
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-django>=4.8; extra == "dev"
+Dynamic: license-file
+
+# django-admin-home
+
+A tree-navigation sidebar plus a favorites/most-accessed home dashboard for
+the Django admin.
+
+By default, the Django admin's home page is a flat, alphabetical list of
+every app/model the current user can access, and the built-in sidebar has
+no favorites or usage-based shortcuts. This package replaces both with:
+
+## Features
+
+- A collapsible sidebar, grouped by app, built from the admin's own
+  `get_app_list` — so it always respects the current user's permissions.
+- A "Favorites" section and a star to pin/unpin any app or model
+  (persisted per user).
+- A home page with cards for favorites, most-accessed items (tracked per
+  user), and every module, in a responsive grid (with an optional compact
+  "masonry" layout).
+- An optional "Pages" group for custom, non-model links (dashboards, API
+  docs, external tools, ...), entirely configured via settings.
+- A dependency-free, offline SVG icon set (no external font/CDN).
+- Defensive by design: any unexpected failure falls back to the native
+  admin behaviour instead of breaking the page.
+
+## Installation
+
+```bash
+pip install django-admin-home
+```
+
+Add it to `INSTALLED_APPS` (it ships models, so run `migrate` afterwards):
+
+```python
+INSTALLED_APPS = [
+    "django_admin_home",
+    ...
+    "django.contrib.admin",
+]
+```
+
+Enable it, once — e.g. in your own app's `AppConfig.ready()`:
+
+```python
+from django.apps import AppConfig
+
+
+class MyAppConfig(AppConfig):
+    def ready(self):
+        from django_admin_home import install
+
+        install()
+```
+
+Include the bundled CSS/JS in your `admin/base_site.html`:
+
+```django
+{% load static %}
+<link rel="stylesheet" href="{% static 'django_admin_home/css/nav.css' %}">
+<link rel="stylesheet" href="{% static 'django_admin_home/css/home.css' %}">
+<script src="{% static 'django_admin_home/js/nav.js' %}" defer></script>
+```
+
+Run migrations:
+
+```bash
+python manage.py migrate django_admin_home
+```
+
+## Settings (all optional)
+
+```python
+# Icon per app/model. Value is a symbol name from the bundled SVG sprite
+# (admin_home/_icon_sprite.html) — add your own <symbol> there via a
+# template override if you need more icons.
+ADMIN_HOME_APP_ICONS = {"buyers": "building", "cards": "card"}
+ADMIN_HOME_MODEL_ICONS = {"buyers.buyer": "building"}
+
+# Extra, non-model links shown in a "Pages" group.
+ADMIN_HOME_CUSTOM_PAGES = [
+    {
+        "key": "page.dashboard",
+        "name": "Dashboard",
+        "icon": "gauge",
+        "url_name": "dashboard_index",
+        "permission": "account.view_menu_dashboard",  # optional
+        "new_tab": True,
+    },
+]
+
+# How many "most accessed" cards to show on the home page (default 8).
+ADMIN_HOME_MAX_MOST_ACCESSED = 8
+```
+
+## Overriding the brand/logo
+
+The sidebar header includes `admin_home/_brand.html`, which by default just
+shows `site_header` as text. To show your own logo, place a template at
+the same path earlier in your project's template resolution (e.g.
+`templates/admin_home/_brand.html` in your project, with `APP_DIRS` search
+order putting your project templates before installed apps).
+
+## What this package intentionally does not do
+
+- It does not set `site_header` / `site_title` / `index_title` — that
+  stays a project-level decision.
+- It does not touch `AdminSite.has_permission` — any extra access rules
+  are the host project's responsibility.
+- It does not migrate data from a previous, project-specific
+  favorites/access-tracking implementation.

django_admin_home-0.1.0/README.md

@@ -0,0 +1,109 @@
+# django-admin-home
+
+A tree-navigation sidebar plus a favorites/most-accessed home dashboard for
+the Django admin.
+
+By default, the Django admin's home page is a flat, alphabetical list of
+every app/model the current user can access, and the built-in sidebar has
+no favorites or usage-based shortcuts. This package replaces both with:
+
+## Features
+
+- A collapsible sidebar, grouped by app, built from the admin's own
+  `get_app_list` — so it always respects the current user's permissions.
+- A "Favorites" section and a star to pin/unpin any app or model
+  (persisted per user).
+- A home page with cards for favorites, most-accessed items (tracked per
+  user), and every module, in a responsive grid (with an optional compact
+  "masonry" layout).
+- An optional "Pages" group for custom, non-model links (dashboards, API
+  docs, external tools, ...), entirely configured via settings.
+- A dependency-free, offline SVG icon set (no external font/CDN).
+- Defensive by design: any unexpected failure falls back to the native
+  admin behaviour instead of breaking the page.
+
+## Installation
+
+```bash
+pip install django-admin-home
+```
+
+Add it to `INSTALLED_APPS` (it ships models, so run `migrate` afterwards):
+
+```python
+INSTALLED_APPS = [
+    "django_admin_home",
+    ...
+    "django.contrib.admin",
+]
+```
+
+Enable it, once — e.g. in your own app's `AppConfig.ready()`:
+
+```python
+from django.apps import AppConfig
+
+
+class MyAppConfig(AppConfig):
+    def ready(self):
+        from django_admin_home import install
+
+        install()
+```
+
+Include the bundled CSS/JS in your `admin/base_site.html`:
+
+```django
+{% load static %}
+<link rel="stylesheet" href="{% static 'django_admin_home/css/nav.css' %}">
+<link rel="stylesheet" href="{% static 'django_admin_home/css/home.css' %}">
+<script src="{% static 'django_admin_home/js/nav.js' %}" defer></script>
+```
+
+Run migrations:
+
+```bash
+python manage.py migrate django_admin_home
+```
+
+## Settings (all optional)
+
+```python
+# Icon per app/model. Value is a symbol name from the bundled SVG sprite
+# (admin_home/_icon_sprite.html) — add your own <symbol> there via a
+# template override if you need more icons.
+ADMIN_HOME_APP_ICONS = {"buyers": "building", "cards": "card"}
+ADMIN_HOME_MODEL_ICONS = {"buyers.buyer": "building"}
+
+# Extra, non-model links shown in a "Pages" group.
+ADMIN_HOME_CUSTOM_PAGES = [
+    {
+        "key": "page.dashboard",
+        "name": "Dashboard",
+        "icon": "gauge",
+        "url_name": "dashboard_index",
+        "permission": "account.view_menu_dashboard",  # optional
+        "new_tab": True,
+    },
+]
+
+# How many "most accessed" cards to show on the home page (default 8).
+ADMIN_HOME_MAX_MOST_ACCESSED = 8
+```
+
+## Overriding the brand/logo
+
+The sidebar header includes `admin_home/_brand.html`, which by default just
+shows `site_header` as text. To show your own logo, place a template at
+the same path earlier in your project's template resolution (e.g.
+`templates/admin_home/_brand.html` in your project, with `APP_DIRS` search
+order putting your project templates before installed apps).
+
+## What this package intentionally does not do
+
+- It does not set `site_header` / `site_title` / `index_title` — that
+  stays a project-level decision.
+- It does not touch `AdminSite.has_permission` — any extra access rules
+  are the host project's responsibility.
+- It does not migrate data from a previous, project-specific
+  favorites/access-tracking implementation.

django_admin_home-0.1.0/django_admin_home/__init__.py

@@ -0,0 +1,106 @@
+"""A tree-navigation sidebar + favorites/most-accessed home dashboard for the Django admin.
+
+By default, the Django admin's home page is a flat, alphabetical list of
+every app/model the user can access, and the built-in sidebar has no
+favorites or usage-based shortcuts. This package replaces both with:
+
+- A collapsible sidebar, grouped by app, with a "Favorites" section and a
+  star to pin/unpin any item (persisted per user).
+- A home page with cards for favorites, most-accessed items (tracked per
+  user), and every module, in a responsive grid (with an optional compact
+  "masonry" layout).
+- An optional "Pages" group for custom, non-model links (dashboards, API
+  docs, ...), configured entirely via settings.
+- A dependency-free SVG icon set, offline (no external font/CDN).
+
+Installation
+------------
+1. ``pip install django-admin-home``
+
+2. Add ``"django_admin_home"`` to ``INSTALLED_APPS`` (it ships models, so
+   run ``migrate`` afterwards)::
+
+    INSTALLED_APPS = [
+        "django_admin_home",
+        ...
+        "django.contrib.admin",
+    ]
+
+3. Enable it, once — e.g. in your own app's ``AppConfig.ready()``::
+
+    from django_admin_home import install
+
+    class MyAppConfig(AppConfig):
+        def ready(self):
+            install()
+
+4. Include the bundled CSS/JS in your ``admin/base_site.html``::
+
+    {% load static %}
+    <link rel="stylesheet" href="{% static 'django_admin_home/css/nav.css' %}">
+    <link rel="stylesheet" href="{% static 'django_admin_home/css/home.css' %}">
+    <script src="{% static 'django_admin_home/js/nav.js' %}" defer></script>
+
+Optional settings
+------------------
+- ``ADMIN_HOME_APP_ICONS`` / ``ADMIN_HOME_MODEL_ICONS``: dicts mapping an
+  ``app_label`` (or ``app_label.model_name``) to an icon symbol name.
+- ``ADMIN_HOME_CUSTOM_PAGES``: list of dicts describing extra, non-model
+  links shown in a "Pages" group. See :mod:`django_admin_home.pages`.
+- ``ADMIN_HOME_MAX_MOST_ACCESSED``: how many "most accessed" cards to show
+  on the home page (default 8).
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_APP_ICON",
+    "DEFAULT_MODEL_ICON",
+    "HOME_ICON",
+    "MenuAccess",
+    "MenuFavorite",
+    "app_menu_key",
+    "build_custom_pages_group",
+    "build_menu_tree",
+    "flatten_menu_items",
+    "icon_for_app",
+    "icon_for_model",
+    "install",
+    "model_menu_key",
+]
+
+# Names are resolved lazily (PEP 562) instead of imported eagerly here.
+# Django imports this top-level package during app-registry population
+# (phase 1, before any app's `models` module may be imported) just to
+# discover this app's AppConfig — an eager `from .models import ...` (or
+# anything that transitively imports models, like `install`/`views`) at
+# that point raises AppRegistryNotReady.
+_LAZY_ATTRS = {
+    "install": "django_admin_home.install",
+    "MenuAccess": "django_admin_home.models",
+    "MenuFavorite": "django_admin_home.models",
+    "build_custom_pages_group": "django_admin_home.pages",
+    "DEFAULT_APP_ICON": "django_admin_home.menu",
+    "DEFAULT_MODEL_ICON": "django_admin_home.menu",
+    "HOME_ICON": "django_admin_home.menu",
+    "app_menu_key": "django_admin_home.menu",
+    "build_menu_tree": "django_admin_home.menu",
+    "flatten_menu_items": "django_admin_home.menu",
+    "icon_for_app": "django_admin_home.menu",
+    "icon_for_model": "django_admin_home.menu",
+    "model_menu_key": "django_admin_home.menu",
+}
+
+
+def __getattr__(name: str):
+    module_path = _LAZY_ATTRS.get(name)
+    if module_path is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    module = importlib.import_module(module_path)
+    value = getattr(module, name)
+    globals()[name] = value  # cache: subsequent access skips __getattr__
+    return value

django_admin_home-0.1.0/django_admin_home/apps.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class AdminHomeConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_admin_home"
+    label = "admin_home"
+    verbose_name = "Admin Home Dashboard"

django_admin_home-0.1.0/django_admin_home/install.py

@@ -0,0 +1,145 @@
+"""Installs the sidebar navigation + home dashboard on an ``AdminSite``."""
+
+from __future__ import annotations
+
+from django.conf import settings
+from django.contrib import admin
+from django.urls import path
+
+from django_admin_home.menu import build_menu_tree, flatten_menu_items
+from django_admin_home.pages import build_custom_pages_group
+from django_admin_home.views import toggle_favorite, track_access
+
+
+def _max_most_accessed() -> int:
+    return getattr(settings, "ADMIN_HOME_MAX_MOST_ACCESSED", 8)
+
+
+def _favorite_keys(user):
+    from django_admin_home.models import MenuFavorite
+
+    return set(MenuFavorite.objects.filter(user=user).values_list("menu_key", flat=True))
+
+
+def _menu_tree_for_request(site, request):
+    """Builds the menu tree honouring permissions (via ``get_app_list``)."""
+    try:
+        app_list = site.get_app_list(request)
+    except Exception:
+        app_list = []
+    favorites = _favorite_keys(request.user) if request.user.is_authenticated else set()
+    menu_tree = build_menu_tree(app_list, favorites=favorites)
+
+    # Appends the "Pages" group (custom, non-model links), respecting
+    # permissions. Additive and defensive: any failure here must never
+    # prevent the rest of the menu from being built.
+    try:
+        pages_group = build_custom_pages_group(request.user, favorites=favorites)
+        if pages_group:
+            menu_tree = menu_tree + [pages_group]
+    except Exception:
+        pass
+
+    return menu_tree, favorites
+
+
+def _most_accessed(user, menu_index):
+    """Top items accessed by the user that still exist in the navigation."""
+    from django_admin_home.models import MenuAccess
+
+    rows = (
+        MenuAccess.objects.filter(user=user)
+        .order_by("-access_count", "-last_access")
+        .values("menu_key", "access_count")
+    )
+    cards = []
+    max_items = _max_most_accessed()
+    for row in rows:
+        meta = menu_index.get(row["menu_key"])
+        if not meta or not meta.get("url"):
+            continue
+        cards.append({**meta, "access_count": row["access_count"]})
+        if len(cards) >= max_items:
+            break
+    return cards
+
+
+def _favorites_cards(menu_index, favorites):
+    cards = []
+    for key in favorites:
+        meta = menu_index.get(key)
+        if meta and meta.get("url"):
+            cards.append(meta)
+    cards.sort(key=lambda c: (c["name"] or "").lower())
+    return cards
+
+
+def install(site: admin.AdminSite | None = None) -> None:
+    """Applies the sidebar + home dashboard customization to ``site``.
+
+    Idempotent (safe to call more than once) and additive: wraps
+    ``each_context``/``index``/``get_urls``, preserving the originals, and
+    never touches ``site_header``/``site_title``/``index_title`` or
+    ``has_permission`` — those stay a project-level concern.
+
+    Call this once, for example from your own app's ``AppConfig.ready()``::
+
+        from django_admin_home import install
+
+        class MyAppConfig(AppConfig):
+            def ready(self):
+                install()
+    """
+    site = site or admin.site
+
+    if getattr(site, "_admin_home_installed", False):
+        return
+
+    original_each_context = site.each_context
+    original_index = site.index
+    original_get_urls = site.get_urls
+
+    def each_context(request):
+        context = original_each_context(request)
+        try:
+            menu_tree, favorites = _menu_tree_for_request(site, request)
+            context["admin_home_menu_tree"] = menu_tree
+            context["admin_home_menu_favorites"] = _favorites_cards(flatten_menu_items(menu_tree), favorites)
+        except Exception:
+            # The sidebar is additive; it must never break the admin.
+            context.setdefault("admin_home_menu_tree", [])
+            context.setdefault("admin_home_menu_favorites", [])
+        return context
+
+    def index(request, extra_context=None):
+        extra_context = extra_context or {}
+        try:
+            menu_tree, favorites = _menu_tree_for_request(site, request)
+            menu_index = flatten_menu_items(menu_tree)
+            extra_context["admin_home_most_accessed"] = _most_accessed(request.user, menu_index)
+            extra_context["admin_home_favorite_cards"] = _favorites_cards(menu_index, favorites)
+        except Exception:
+            extra_context.setdefault("admin_home_most_accessed", [])
+            extra_context.setdefault("admin_home_favorite_cards", [])
+        return original_index(request, extra_context)
+
+    def get_urls():
+        custom = [
+            path(
+                "menu/toggle-favorite/",
+                site.admin_view(toggle_favorite),
+                name="admin_home_toggle_favorite",
+            ),
+            path(
+                "menu/track-access/",
+                site.admin_view(track_access),
+                name="admin_home_track_access",
+            ),
+        ]
+        return custom + original_get_urls()
+
+    site.each_context = each_context
+    site.index = index
+    site.get_urls = get_urls
+
+    site._admin_home_installed = True

django_admin_home-0.1.0/django_admin_home/menu.py

@@ -0,0 +1,129 @@
+"""Builds the navigable menu tree from the admin's own ``app_list``.
+
+The tree is derived from ``AdminSite.get_app_list(request)``, which already
+respects the current user's permissions — this module only enriches each
+app/model with an icon and a stable key, it never decides visibility.
+
+Icons are referenced by *name* (a ``<symbol id="i-<name}">`` in the bundled
+SVG sprite, see ``admin_home/_icon_sprite.html``), not by external font/CDN
+classes, so the navigation keeps working offline. Any app/model without a
+specific mapping falls back to a generic icon, so navigation keeps working
+as new apps/models are added.
+
+The "stable key" of each item (``menu_key``) is used both for favorites and
+for the access counter:
+
+    - Model item:  ``<app_label>.<object_name_lower>``  e.g. ``auth.user``
+    - App group:   ``app.<app_label>``                  e.g. ``app.auth``
+    - Home:        ``home``
+"""
+
+from __future__ import annotations
+
+from django.conf import settings
+
+DEFAULT_APP_ICON = "folder"
+DEFAULT_MODEL_ICON = "list"
+HOME_ICON = "home"
+
+# Minimal built-in fallback so a stock Django project (auth app) already
+# gets sensible icons. Projects override/extend via ADMIN_HOME_APP_ICONS /
+# ADMIN_HOME_MODEL_ICONS.
+_BUILTIN_APP_ICONS = {"auth": "shield"}
+_BUILTIN_MODEL_ICONS = {"auth.user": "user", "auth.group": "users"}
+
+
+def _app_icons() -> dict:
+    icons = dict(_BUILTIN_APP_ICONS)
+    icons.update(getattr(settings, "ADMIN_HOME_APP_ICONS", None) or {})
+    return icons
+
+
+def _model_icons() -> dict:
+    icons = dict(_BUILTIN_MODEL_ICONS)
+    icons.update(getattr(settings, "ADMIN_HOME_MODEL_ICONS", None) or {})
+    return icons
+
+
+def model_menu_key(app_label: str, object_name: str) -> str:
+    """Stable key for a model item."""
+    return f"{app_label}.{object_name}".lower()
+
+
+def app_menu_key(app_label: str) -> str:
+    return f"app.{app_label}".lower()
+
+
+def icon_for_app(app_label: str) -> str:
+    return _app_icons().get((app_label or "").lower(), DEFAULT_APP_ICON)
+
+
+def icon_for_model(app_label: str, object_name: str) -> str:
+    return _model_icons().get(model_menu_key(app_label, object_name), DEFAULT_MODEL_ICON)
+
+
+def build_menu_tree(app_list, favorites: set[str] | None = None) -> list[dict]:
+    """Turns the admin's ``app_list`` into a navigable tree.
+
+    Each app node: ``{key, name, icon, url, models: [...], is_favorite}``.
+    Each model node: ``{key, name, icon, url, add_url, is_favorite}``.
+
+    ``favorites`` is the set of ``menu_key`` the current user favorited.
+    """
+    favorites = favorites or set()
+    tree = []
+    for app in app_list:
+        app_label = app.get("app_label") or ""
+        app_key = app_menu_key(app_label)
+        models = []
+        for model in app.get("models", []):
+            object_name = (model.get("object_name") or model.get("name") or "").strip()
+            key = model_menu_key(app_label, object_name)
+            models.append(
+                {
+                    "key": key,
+                    "name": model.get("name"),
+                    "icon": icon_for_model(app_label, object_name),
+                    "url": model.get("admin_url"),
+                    "add_url": model.get("add_url"),
+                    "is_favorite": key in favorites,
+                }
+            )
+        tree.append(
+            {
+                "key": app_key,
+                "name": app.get("name"),
+                "icon": icon_for_app(app_label),
+                "url": app.get("app_url"),
+                "models": models,
+                "is_favorite": app_key in favorites,
+            }
+        )
+    return tree
+
+
+def flatten_menu_items(menu_tree) -> dict:
+    """Index ``menu_key -> metadata`` (apps + models).
+
+    Used to resolve "most accessed" and "favorites" cards from the
+    persisted keys, keeping name/icon/url in sync with the live menu.
+    """
+    index: dict = {}
+    for app in menu_tree:
+        index[app["key"]] = {
+            "key": app["key"],
+            "name": app["name"],
+            "icon": app["icon"],
+            "url": app["url"],
+            "parent": None,
+        }
+        for model in app["models"]:
+            index[model["key"]] = {
+                "key": model["key"],
+                "name": model["name"],
+                "icon": model["icon"],
+                "url": model["url"],
+                "parent": app["name"],
+                "new_tab": bool(model.get("new_tab")),
+            }
+    return index