django-admin-mobile 0.1.0__py3-none-any.whl

admin_mobile/__init__.py

@@ -0,0 +1,3 @@
+"""Phone ergonomics for the native Django admin."""
+
+__version__ = "0.1.0"

admin_mobile/apps.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class AdminMobileConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "admin_mobile"
+    verbose_name = "Admin mobile"
+
+    def ready(self) -> None:
+        from admin_mobile.checks import register_checks
+        from admin_mobile.overrides import install_native_datetime_patch
+
+        register_checks()
+        install_native_datetime_patch()

admin_mobile/checks.py

@@ -0,0 +1,72 @@
+"""Install-order check. The template tag remains valid either way."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from django.core.checks import Warning, register
+
+_REGISTERED = False
+
+
+def _is_admin_mobile(entry: str) -> bool:
+    return entry == "admin_mobile" or entry.endswith(
+        "admin_mobile.apps.AdminMobileConfig"
+    )
+
+
+def _is_django_admin(entry: str) -> bool:
+    return entry in {
+        "django.contrib.admin",
+        "django.contrib.admin.apps.AdminConfig",
+    }
+
+
+def app_order_warnings(installed_apps: Sequence[str]) -> list[Warning]:
+    mobile_at = next(
+        (
+            index
+            for index, entry in enumerate(installed_apps)
+            if _is_admin_mobile(entry)
+        ),
+        None,
+    )
+    admin_at = next(
+        (
+            index
+            for index, entry in enumerate(installed_apps)
+            if _is_django_admin(entry)
+        ),
+        None,
+    )
+    if mobile_at is None or admin_at is None or mobile_at < admin_at:
+        return []
+    return [
+        Warning(
+            "admin_mobile is listed after django.contrib.admin, so its "
+            "admin/base.html override will not be selected.",
+            hint=(
+                "Put 'admin_mobile' before 'django.contrib.admin' in "
+                "INSTALLED_APPS, or load {% admin_mobile_assets %} from your "
+                "own admin/base.html."
+            ),
+            id="admin_mobile.W001",
+        )
+    ]
+
+
+def check_installed_before_admin(
+    app_configs: object,
+    **kwargs: object,
+) -> list[Warning]:
+    from django.conf import settings
+
+    return app_order_warnings(tuple(settings.INSTALLED_APPS))
+
+
+def register_checks() -> None:
+    global _REGISTERED
+    if _REGISTERED:
+        return
+    register(check_installed_before_admin)
+    _REGISTERED = True

admin_mobile/conf.py

@@ -0,0 +1,60 @@
+"""Typed view of the ``ADMIN_MOBILE`` setting."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+
+_SETTING_TO_FIELD: dict[str, str] = {
+    "ENABLED": "enabled",
+    "CHANGELIST_CARDS": "changelist_cards",
+    "TABULAR_INLINE_STACK": "tabular_inline_stack",
+    "STICKY_SUBMIT": "sticky_submit",
+    "TOUCH_TARGETS": "touch_targets",
+    "COLLAPSIBLE_FILTERS": "collapsible_filters",
+    "USE_NATIVE_DATETIME": "use_native_datetime",
+}
+
+
+@dataclass(frozen=True)
+class AdminMobileSettings:
+    """Feature flags. Missing keys keep these defaults."""
+
+    enabled: bool = True
+    changelist_cards: bool = True
+    tabular_inline_stack: bool = True
+    sticky_submit: bool = True
+    touch_targets: bool = True
+    collapsible_filters: bool = True
+    use_native_datetime: bool = False
+
+
+def get_config() -> AdminMobileSettings:
+    """Read ``ADMIN_MOBILE`` on each call so ``override_settings`` works."""
+
+    raw = getattr(settings, "ADMIN_MOBILE", None)
+    if raw is None:
+        return AdminMobileSettings()
+    if not isinstance(raw, Mapping):
+        raise ImproperlyConfigured("ADMIN_MOBILE must be a dict of booleans.")
+
+    unknown = sorted(str(key) for key in raw if key not in _SETTING_TO_FIELD)
+    if unknown:
+        names = ", ".join(unknown)
+        allowed = ", ".join(sorted(_SETTING_TO_FIELD))
+        raise ImproperlyConfigured(
+            f"Unknown ADMIN_MOBILE keys: {names}. Allowed keys: {allowed}."
+        )
+
+    values: dict[str, bool] = {}
+    for key, attr in _SETTING_TO_FIELD.items():
+        if key not in raw:
+            continue
+        value = raw[key]
+        if not isinstance(value, bool):
+            raise ImproperlyConfigured(f"ADMIN_MOBILE[{key!r}] must be a bool.")
+        values[attr] = value
+    return AdminMobileSettings(**values)

admin_mobile/mixins.py

@@ -0,0 +1,29 @@
+"""Per-model opt-in for native date and time widgets."""
+
+from __future__ import annotations
+
+from django.contrib.admin.sites import AdminSite
+from django.db import models
+
+from admin_mobile.overrides import (
+    NATIVE_FORMFIELD_OVERRIDES,
+    install_native_overrides,
+)
+
+
+class MobileAdminMixin:
+    """Use native date widgets on one ``ModelAdmin`` or inline.
+
+    List this mixin before ``admin.ModelAdmin`` (or ``TabularInline``).
+    A custom ``formfield_overrides`` widget for a date field is left alone.
+    The global ``USE_NATIVE_DATETIME`` flag is a separate opt-in.
+    """
+
+    formfield_overrides = {
+        field_cls: dict(options)
+        for field_cls, options in NATIVE_FORMFIELD_OVERRIDES.items()
+    }
+
+    def __init__(self, model: type[models.Model], admin_site: AdminSite) -> None:
+        super().__init__(model, admin_site)
+        install_native_overrides(self)

admin_mobile/overrides.py

@@ -0,0 +1,144 @@
+"""Swap stock admin date widgets without touching a custom widget choice."""
+
+from __future__ import annotations
+
+from django import forms
+from django.contrib.admin import widgets as admin_widgets
+from django.contrib.admin.options import BaseModelAdmin
+from django.db import models
+
+from admin_mobile.conf import get_config
+from admin_mobile.widgets import (
+    ISO_DATE_INPUT_FORMATS,
+    ISO_TIME_INPUT_FORMATS,
+    NativeDateInput,
+    NativeSplitDateTimeWidget,
+    NativeTimeInput,
+)
+
+STOCK_WIDGETS: frozenset[type[forms.Widget]] = frozenset(
+    {
+        admin_widgets.AdminDateWidget,
+        admin_widgets.AdminTimeWidget,
+        admin_widgets.AdminSplitDateTime,
+        admin_widgets.BaseAdminDateWidget,
+        admin_widgets.BaseAdminTimeWidget,
+    }
+)
+
+NATIVE_WIDGETS: frozenset[type[forms.Widget]] = frozenset(
+    {
+        NativeDateInput,
+        NativeTimeInput,
+        NativeSplitDateTimeWidget,
+    }
+)
+
+NATIVE_FORMFIELD_OVERRIDES: dict[type[models.Field], dict[str, object]] = {
+    models.DateField: {
+        "widget": NativeDateInput,
+        "input_formats": list(ISO_DATE_INPUT_FORMATS),
+        "localize": False,
+    },
+    models.TimeField: {
+        "widget": NativeTimeInput,
+        "input_formats": list(ISO_TIME_INPUT_FORMATS),
+        "localize": False,
+    },
+    models.DateTimeField: {
+        "form_class": forms.SplitDateTimeField,
+        "widget": NativeSplitDateTimeWidget,
+        "input_date_formats": list(ISO_DATE_INPUT_FORMATS),
+        "input_time_formats": list(ISO_TIME_INPUT_FORMATS),
+        "localize": False,
+    },
+}
+
+_PATCHED = False
+_ORIGINAL_FORMFIELD = BaseModelAdmin.formfield_for_dbfield
+
+
+def _native_spec(db_field: models.Field) -> dict[str, object] | None:
+    for field_cls, spec in NATIVE_FORMFIELD_OVERRIDES.items():
+        if isinstance(db_field, field_cls):
+            return spec
+    return None
+
+
+def _current_widget(admin: BaseModelAdmin, db_field: models.Field) -> object | None:
+    overrides = getattr(admin, "formfield_overrides", {})
+    for klass in db_field.__class__.mro():
+        options = overrides.get(klass)
+        if isinstance(options, dict) and "widget" in options:
+            return options["widget"]
+    return None
+
+
+def _is_replaceable(widget: object) -> bool:
+    if widget is None:
+        return True
+    return widget in STOCK_WIDGETS or widget in NATIVE_WIDGETS
+
+
+def install_native_overrides(admin: BaseModelAdmin) -> None:
+    """Point stock date widgets at the native ones. Keep any other widget."""
+
+    overrides: dict[type[models.Field], dict[str, object]] = {
+        field_cls: dict(options)
+        for field_cls, options in admin.formfield_overrides.items()
+        if isinstance(options, dict)
+    }
+    for field_cls, spec in NATIVE_FORMFIELD_OVERRIDES.items():
+        current = dict(overrides.get(field_cls, {}))
+        if not _is_replaceable(current.get("widget")):
+            continue
+        current.update(spec)
+        overrides[field_cls] = current
+    admin.formfield_overrides = overrides
+
+
+def apply_native_datetime(
+    admin: BaseModelAdmin,
+    db_field: models.Field,
+    kwargs: dict[str, object],
+) -> None:
+    """Fill native widget kwargs when the admin is still on the stock widget.
+
+    ``formfield_for_dbfield`` merges ``formfield_overrides`` under ``kwargs``,
+    so values placed here win over ``AdminDateWidget`` and lose to an explicit
+    widget argument from a caller.
+    """
+
+    if db_field.choices:
+        return
+    spec = _native_spec(db_field)
+    if spec is None or not _is_replaceable(_current_widget(admin, db_field)):
+        return
+    for key, value in spec.items():
+        kwargs.setdefault(key, value)
+
+
+def install_native_datetime_patch() -> None:
+    """Wrap ``BaseModelAdmin.formfield_for_dbfield`` once.
+
+    The wrapper checks the setting on every call so tests can toggle it.
+    Inlines inherit ``BaseModelAdmin``, not ``ModelAdmin``, so the patch has
+    to sit on the shared base.
+    """
+
+    global _PATCHED
+    if _PATCHED:
+        return
+
+    def formfield_for_dbfield(
+        self: BaseModelAdmin,
+        db_field: models.Field,
+        request: object,
+        **kwargs: object,
+    ) -> forms.Field | None:
+        if get_config().use_native_datetime:
+            apply_native_datetime(self, db_field, kwargs)
+        return _ORIGINAL_FORMFIELD(self, db_field, request, **kwargs)
+
+    BaseModelAdmin.formfield_for_dbfield = formfield_for_dbfield
+    _PATCHED = True