pytest-django-admin-kit 1.0.0__py3-none-any.whl

django_admin_kit/tools.py

@@ -0,0 +1,27 @@
+"""What a session hands to every page it opens."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .normalize import Normalizers
+    from .urls import AdminUrls
+    from .widgets import Widgets
+
+
+@dataclass(frozen=True)
+class PageTools:
+    """What every page of a session reads by: where the admin's pages are, the rules
+    that read the values they render, and the widget classes that read and fill their
+    controls.
+
+    Only what is built once from the settings or the session's fixtures, and is the same
+    for every page, belongs here. What belongs to one page, row, cell or field is passed
+    to it on its own. A page hands the objects it builds only the tools they use.
+    """
+
+    urls: AdminUrls
+    normalizers: Normalizers
+    widgets: Widgets

django_admin_kit/urls.py

@@ -0,0 +1,122 @@
+"""Admin URLs, resolved through the site under test.
+
+Every URL comes from Django's resolver, so a project that mounts its admin at
+``/backoffice/`` or runs a second ``AdminSite`` gets correct URLs without changing a
+test. Nothing here assembles a path from string pieces.
+
+Resolution says nothing about access. Asking for the URL of a page the current user
+could not open still returns that URL; whether it works is a separate question.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from django.contrib.admin import ModelAdmin
+from django.contrib.admin.sites import AdminSite
+from django.core.exceptions import ImproperlyConfigured
+from django.urls import reverse
+from django.utils.module_loading import import_string
+
+
+def registered_models(site: AdminSite) -> list[type[Any]]:
+    """The models ``site`` registers, in the order they were registered."""
+    return list(_registry(site))
+
+
+def model_admin(site: AdminSite, model: type[Any]) -> ModelAdmin:
+    """The model admin ``site`` registers ``model`` with."""
+    # Django 5.0 added a public accessor; before it there is only the registry.
+    if hasattr(site, "get_model_admin"):
+        return site.get_model_admin(model)
+    return _registry(site)[model]
+
+
+def _registry(site: AdminSite) -> dict[type[Any], ModelAdmin]:
+    # The one place the site's registry is read: Django lists the registered models
+    # nowhere public on any version.
+    registry: dict[type[Any], ModelAdmin] = site._registry
+    return registry
+
+
+def resolve_site(site: str | None = None) -> AdminSite:
+    """Turn the ``site`` setting into an ``AdminSite``.
+
+    Takes a dotted path, or ``None`` for the default ``django.contrib.admin.site``.
+    Only a path, because settings are imported before Django's app registry is ready
+    and an ``AdminSite`` written into settings raises ``AppRegistryNotReady`` there.
+    Code holding a site already can pass it straight to ``AdminUrls``.
+    """
+    if site is None:
+        from django.contrib import admin
+
+        return admin.site
+
+    try:
+        imported = import_string(site)
+    except ImportError as error:
+        raise ImproperlyConfigured(
+            f"DJANGO_ADMIN_KIT['site'] is {site!r}, which does not import: {error}"
+        ) from error
+
+    if not isinstance(imported, AdminSite):
+        raise ImproperlyConfigured(
+            f"DJANGO_ADMIN_KIT['site'] is {site!r}, which is a "
+            f"{type(imported).__name__}, not an AdminSite."
+        )
+    return imported
+
+
+class AdminUrls:
+    """Every admin page this package knows, addressable without opening it."""
+
+    def __init__(self, site: AdminSite) -> None:
+        self._site = site
+
+    @property
+    def site(self) -> AdminSite:
+        return self._site
+
+    def index(self) -> str:
+        return self._reverse("index")
+
+    def login(self) -> str:
+        return self._reverse("login")
+
+    def list(self, model: type[Any]) -> str:
+        return self._reverse_model(model, "changelist")
+
+    def create(self, model: type[Any]) -> str:
+        return self._reverse_model(model, "add")
+
+    def edit(self, instance: Any) -> str:
+        return self._reverse_model(type(instance), "change", [self._pk(instance, "edit")])
+
+    def delete(self, instance: Any) -> str:
+        return self._reverse_model(type(instance), "delete", [self._pk(instance, "delete")])
+
+    def _reverse(self, name: str, args: Sequence[Any] | None = None) -> str:
+        # The app namespace is always "admin"; the site's own name is the instance
+        # namespace, which is what picks between two mounted sites.
+        return str(reverse(f"admin:{name}", args=args, current_app=self._site.name))
+
+    def _reverse_model(
+        self, model: type[Any], action: str, args: Sequence[Any] | None = None
+    ) -> str:
+        if not self._site.is_registered(model):
+            labels = sorted(m._meta.label for m in registered_models(self._site))
+            raise LookupError(
+                f"{model._meta.label} is not registered with the {self._site.name!r} admin "
+                f"site, so it has no admin URLs. Registered models: "
+                f"{', '.join(labels) or 'none'}."
+            )
+        return self._reverse(f"{model._meta.app_label}_{model._meta.model_name}_{action}", args)
+
+    @staticmethod
+    def _pk(instance: Any, action: str) -> Any:
+        if instance.pk is None:
+            raise ValueError(
+                f"Cannot build the {action} URL for an unsaved "
+                f"{type(instance)._meta.label}: it has no primary key yet."
+            )
+        return instance.pk

django_admin_kit/widgets.py

@@ -0,0 +1,172 @@
+"""The widget classes that read and fill a form's controls.
+
+A widget class recognizes its widget by a marker, a CSS selector found inside a field's
+box, and says how to read the field and how to fill it. The marker only picks the
+class: ``read`` and ``fill`` get the whole field and find their own elements in its box.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Iterable, Protocol
+
+from django.db.models import Model
+from playwright.sync_api import Locator
+
+from .fields import FieldChoice
+from .rendered import text_of
+
+if TYPE_CHECKING:
+    from .fields import FormField
+
+
+class Widget(Protocol):
+    """What the package asks of a widget class. ``choices(field)`` is optional."""
+
+    def marker(self, field: FormField) -> str: ...
+
+    def read(self, field: FormField) -> Any: ...
+
+    def fill(self, field: FormField, value: Any) -> None: ...
+
+
+class CheckboxWidget:
+    """A checkbox, read and filled as a boolean."""
+
+    def marker(self, field: FormField) -> str:
+        return f'input[type="checkbox"][name="{field.name}"]'
+
+    def read(self, field: FormField) -> bool:
+        return self._control(field).is_checked()
+
+    def fill(self, field: FormField, value: Any) -> None:
+        self._control(field).set_checked(bool(value))
+
+    def _control(self, field: FormField) -> Locator:
+        return field.native.locator(f'input[type="checkbox"][name="{field.name}"]')
+
+
+class SelectWidget:
+    """A select, read as the ``FieldChoice`` chosen and filled with the option that
+    stands for a value."""
+
+    def marker(self, field: FormField) -> str:
+        return f'select[name="{field.name}"]'
+
+    def read(self, field: FormField) -> FieldChoice:
+        option = self._control(field).locator("option:checked")
+        return FieldChoice(option.get_attribute("value") or "", text_of(option))
+
+    def fill(self, field: FormField, value: Any) -> None:
+        option = self._option(field, value)
+        # An option is asked for by its value, except the blank one, whose value is the
+        # empty string: the browser layer reads that as "select nothing" on the versions
+        # that still run on Python 3.8, so it is asked for by its label.
+        if option.value:
+            self._control(field).select_option(value=option.value)
+        else:
+            self._control(field).select_option(label=option.label)
+
+    def choices(self, field: FormField) -> list[FieldChoice]:
+        """The options the select offers, in order, the blank one included."""
+        return [
+            FieldChoice(option.get_attribute("value") or "", text_of(option))
+            for option in self._control(field).locator("option").all()
+        ]
+
+    def _option(self, field: FormField, value: Any) -> FieldChoice:
+        """The option that stands for ``value``, among the ones the select offers."""
+        offered = {choice.value: choice for choice in self.choices(field)}
+        for spelling in _option_spellings(value):
+            if spelling in offered:
+                return offered[spelling]
+        raise ValueError(
+            f"The field {field.name!r} offers no option for {value!r}. Options: "
+            f"{', '.join(repr(option) for option in offered) or 'none'}."
+        )
+
+    def _control(self, field: FormField) -> Locator:
+        return field.native.locator(f'select[name="{field.name}"]')
+
+
+class TextWidget:
+    """Whatever one control carries the field's name, read and filled as text."""
+
+    def marker(self, field: FormField) -> str:
+        return f'[name="{field.name}"]'
+
+    def read(self, field: FormField) -> str:
+        return self._control(field).input_value()
+
+    def fill(self, field: FormField, value: Any) -> None:
+        self._control(field).fill("" if value is None else str(value))
+
+    def _control(self, field: FormField) -> Locator:
+        return field.native.locator(f'[name="{field.name}"]')
+
+
+class Widgets:
+    """The widget classes a form's fields are read and filled through, in the order
+    they are tried: the ``custom`` ones, then the built-in ones.
+
+    A built-in class is replaced by putting a custom class in front of it that
+    recognizes the same control.
+    """
+
+    def __init__(self, custom: Iterable[Widget] = ()) -> None:
+        # A text control is any control with the field's name, a checkbox and a select
+        # included, so it comes last.
+        self._widgets: tuple[Widget, ...] = (
+            *custom,
+            CheckboxWidget(),
+            SelectWidget(),
+            TextWidget(),
+        )
+
+    def widget_for(self, field: FormField) -> Widget | None:
+        """The first widget class whose marker matches inside the field's box, or
+        ``None`` when none of them recognizes the field.
+
+        Every marker is tried in one browser call, since each call costs a round trip
+        whatever it asks.
+        """
+        index = field.native.evaluate(
+            "(box, markers) => markers.findIndex(marker => box.querySelector(marker))",
+            [_marker(widget, field) for widget in self._widgets],
+        )
+        return self._widgets[index] if index >= 0 else None
+
+
+def _marker(widget: Widget, field: FormField) -> str:
+    """The widget class's marker for the field, checked before the browser sees it."""
+    marker = widget.marker(field)
+    if not isinstance(marker, str) or not marker:
+        raise TypeError(
+            f"{type(widget).__name__}.marker() must return a non-empty CSS selector, "
+            f"not {marker!r}."
+        )
+    return marker
+
+
+def _option_spellings(value: Any) -> list[str]:
+    """The option values ``value`` may be written as, in the order they are looked for.
+
+    A select's options are the choice values as ``str()`` renders them, with ``""`` for
+    the blank one. The exception is the widget Django gives a nullable boolean, whose
+    three options are spelled ``"unknown"``, ``"true"`` and ``"false"``. Both spellings
+    are Django's own and the page shows only which options it has, not which widget drew
+    them, so a boolean is looked for under either.
+    """
+    if isinstance(value, FieldChoice):
+        return [value.value]
+    # A select of related objects offers each one by its primary key, which is what the
+    # form posts for it.
+    if isinstance(value, Model):
+        return [str(value.pk)]
+    # `is`, because `1 == True` and a number is no boolean here.
+    if value is True:
+        return ["True", "true"]
+    if value is False:
+        return ["False", "false"]
+    if value is None:
+        return ["", "unknown"]
+    return [str(value)]