|
| 1 | +"""System checks for django_admin_react (#667). |
| 2 | +
|
| 3 | +Registered against ``django.core.checks`` so common misconfigurations |
| 4 | +surface at ``manage.py check`` (and on every ``runserver`` boot) with an |
| 5 | +actionable hint — instead of a lazy ``ValueError`` on first settings |
| 6 | +access, a runtime 500, or a silent template fallback. |
| 7 | +
|
| 8 | +What we validate: |
| 9 | +
|
| 10 | +- ``django_admin_rest_api`` is installed (the package implements no API of |
| 11 | + its own — every JSON endpoint lives in that sibling package). |
| 12 | +- ``DJANGO_ADMIN_REACT["ADMIN_SITE"]`` (dotted path) actually imports. |
| 13 | +- ``DJANGO_ADMIN_REACT`` has no unknown keys (the same guard ``conf._load`` |
| 14 | + enforces lazily — surfaced here at startup as a clean check error). |
| 15 | +- ``API_URL_PREFIX`` mounting is coherent: when it is set, the package |
| 16 | + skips its inline ``api/v1/`` include, so the consumer must mount |
| 17 | + ``django_admin_rest_api.urls`` themselves — a Warning reminds them. |
| 18 | +- The built SPA bundle / Vite manifest exists (a Warning, not an Error — |
| 19 | + the package serves a friendly "not built" shell, and the manifest is |
| 20 | + absent in a source checkout / before ``pnpm build``). |
| 21 | +
|
| 22 | +Severities follow Django's convention: an ``Error`` blocks (the package |
| 23 | +cannot work); a ``Warning`` is a likely-misconfiguration heads-up that |
| 24 | +does not hard-block. |
| 25 | +""" |
| 26 | + |
| 27 | +from __future__ import annotations |
| 28 | + |
| 29 | +from typing import Any |
| 30 | + |
| 31 | +from django.core.checks import Error |
| 32 | +from django.core.checks import Warning as CheckWarning |
| 33 | + |
| 34 | +# Stable check IDs (Django convention ``<app_label>.E/W###``) so a consumer |
| 35 | +# can silence a specific one via ``SILENCED_SYSTEM_CHECKS`` if they must. |
| 36 | +ID_REST_API_MISSING = "django_admin_react.E001" |
| 37 | +ID_ADMIN_SITE_IMPORT = "django_admin_react.E002" |
| 38 | +ID_UNKNOWN_SETTINGS = "django_admin_react.E003" |
| 39 | +ID_API_PREFIX_MOUNT = "django_admin_react.W001" |
| 40 | +ID_BUNDLE_MISSING = "django_admin_react.W002" |
| 41 | + |
| 42 | + |
| 43 | +def check_django_admin_react(app_configs: Any, **kwargs: Any) -> list[Any]: |
| 44 | + """Run every package configuration check. |
| 45 | +
|
| 46 | + Registered as a single callable (rather than many) so the import |
| 47 | + surface stays small and the ordering is explicit. ``app_configs`` / |
| 48 | + ``kwargs`` are the Django check-framework signature; unused here |
| 49 | + because the checks are global to the package, not per-app. |
| 50 | + """ |
| 51 | + errors: list[Any] = [] |
| 52 | + errors.extend(_check_rest_api_installed()) |
| 53 | + errors.extend(_check_admin_site_imports()) |
| 54 | + errors.extend(_check_settings_keys()) |
| 55 | + errors.extend(_check_api_prefix_coherence()) |
| 56 | + errors.extend(_check_bundle_built()) |
| 57 | + return errors |
| 58 | + |
| 59 | + |
| 60 | +def _check_rest_api_installed() -> list[Any]: |
| 61 | + from django.apps import apps as django_apps |
| 62 | + |
| 63 | + if django_apps.is_installed("django_admin_rest_api"): |
| 64 | + return [] |
| 65 | + return [ |
| 66 | + Error( |
| 67 | + "'django_admin_rest_api' is not in INSTALLED_APPS.", |
| 68 | + hint=( |
| 69 | + "django-admin-react is a React SPA over django-admin-rest-api " |
| 70 | + "and implements no API of its own. Add 'django_admin_rest_api' " |
| 71 | + "to INSTALLED_APPS (it ships as a dependency)." |
| 72 | + ), |
| 73 | + id=ID_REST_API_MISSING, |
| 74 | + ) |
| 75 | + ] |
| 76 | + |
| 77 | + |
| 78 | +def _check_admin_site_imports() -> list[Any]: |
| 79 | + from django.utils.module_loading import import_string |
| 80 | + |
| 81 | + from django_admin_react import conf as dar_conf |
| 82 | + |
| 83 | + dotted = dar_conf.ADMIN_SITE |
| 84 | + try: |
| 85 | + import_string(dotted) |
| 86 | + except ImportError as exc: |
| 87 | + return [ |
| 88 | + Error( |
| 89 | + f"DJANGO_ADMIN_REACT['ADMIN_SITE'] = {dotted!r} could not be imported " f"({exc}).", |
| 90 | + hint=( |
| 91 | + "Point ADMIN_SITE at the dotted path of your AdminSite " |
| 92 | + "instance (e.g. 'myproject.admin.site' or the default " |
| 93 | + "'django.contrib.admin.site')." |
| 94 | + ), |
| 95 | + id=ID_ADMIN_SITE_IMPORT, |
| 96 | + ) |
| 97 | + ] |
| 98 | + return [] |
| 99 | + |
| 100 | + |
| 101 | +def _check_settings_keys() -> list[Any]: |
| 102 | + from django.conf import settings as django_settings |
| 103 | + |
| 104 | + from django_admin_react.conf import DEFAULTS |
| 105 | + |
| 106 | + overrides = getattr(django_settings, "DJANGO_ADMIN_REACT", {}) or {} |
| 107 | + unknown = sorted(set(overrides) - set(DEFAULTS)) |
| 108 | + if not unknown: |
| 109 | + return [] |
| 110 | + return [ |
| 111 | + Error( |
| 112 | + "Unknown DJANGO_ADMIN_REACT key(s): " + ", ".join(unknown) + ".", |
| 113 | + hint=("Remove the typo'd key(s). Valid keys are: " + ", ".join(sorted(DEFAULTS)) + "."), |
| 114 | + id=ID_UNKNOWN_SETTINGS, |
| 115 | + ) |
| 116 | + ] |
| 117 | + |
| 118 | + |
| 119 | +def _check_api_prefix_coherence() -> list[Any]: |
| 120 | + from django_admin_react import conf as dar_conf |
| 121 | + |
| 122 | + prefix = dar_conf.API_URL_PREFIX |
| 123 | + if prefix is None: |
| 124 | + # Inline mount is active; the package mounts the API itself. Nothing |
| 125 | + # the consumer must do. |
| 126 | + return [] |
| 127 | + # The override is set, so `django_admin_react.urls` skips the inline |
| 128 | + # `api/v1/` include — the consumer MUST mount the REST API themselves at |
| 129 | + # that prefix or every SPA data call 404s. |
| 130 | + return [ |
| 131 | + CheckWarning( |
| 132 | + f"DJANGO_ADMIN_REACT['API_URL_PREFIX'] = {prefix!r} is set, so this " |
| 133 | + "package does NOT mount the REST API inline.", |
| 134 | + hint=( |
| 135 | + "Mount the sibling API yourself at that prefix, e.g.\n" |
| 136 | + f" path({prefix!r}, include('django_admin_rest_api.api.urls'))\n" |
| 137 | + "or unset API_URL_PREFIX to use the package's inline 'api/v1/' mount." |
| 138 | + ), |
| 139 | + id=ID_API_PREFIX_MOUNT, |
| 140 | + ) |
| 141 | + ] |
| 142 | + |
| 143 | + |
| 144 | +def _check_bundle_built() -> list[Any]: |
| 145 | + # Imported lazily so the check module has no import-time dependency on |
| 146 | + # the view layer. |
| 147 | + from django_admin_react.views import _MANIFEST_PATH |
| 148 | + |
| 149 | + if _MANIFEST_PATH.is_file(): |
| 150 | + return [] |
| 151 | + return [ |
| 152 | + CheckWarning( |
| 153 | + "The built SPA bundle / Vite manifest was not found at " f"{_MANIFEST_PATH}.", |
| 154 | + hint=( |
| 155 | + "Install the published wheel (which ships the built bundle), or " |
| 156 | + "build the frontend from source with 'pnpm --dir frontend build'. " |
| 157 | + "Until then the SPA shell renders a 'not built yet' page." |
| 158 | + ), |
| 159 | + id=ID_BUNDLE_MISSING, |
| 160 | + ) |
| 161 | + ] |
0 commit comments