Fields

@dataclass
class BaseField:
    """
    The base configuration class for all model fields.

    Parameters:
        name: The field's name, which must match the attribute name in your model.
        label: A human-readable label used for display purposes.
        help_text: An optional hint or description to display within forms.
        type: The unique identifier for the field's type.
        disabled: If `True`, the field is rendered as disabled in forms.
        read_only: If `True`, the field is rendered as read-only in forms.
        default: The default value used to prefill the field on creation forms.
            This can be a static value or a callable that accepts zero or one
            positional argument (the current request).
        getter: `(request, obj) -> value`, sync or async. When set, used by
            [parse_obj][starlette_admin.fields.BaseField.parse_obj] instead of
            `getattr(obj, self.name, None)`, so a field's value can be derived
            without subclassing. See [ComputedField][starlette_admin.fields.ComputedField].
        formatter: Maps a [RequestAction][starlette_admin.types.RequestAction] to a
            `(request, value) -> value` callable, sync or async. When the current
            action has an entry, its callable replaces `serialize_value` /
            `serialize_none_value` entirely; its return value (including for a
            `None` input) is used as-is.
        parser: Maps a [RequestAction][starlette_admin.types.RequestAction] to a
            `(request, raw) -> value` callable, sync or async. When the current
            action has an entry, its callable replaces this field's default
            parsing entirely, so custom form/import parsing can be attached
            without subclassing. See
            [parse_input][starlette_admin.fields.BaseField.parse_input].
        id: A unique identifier for the field instance.
        filters: An explicit override for the list page filters available for this
            field. If `None` (the default), the view's filter registry automatically
            selects filters based on the field's `type`. See
            [FilterRegistry][starlette_admin.filters.FilterRegistry].
        required: If `True`, the field is marked as required in forms and
            enforced server-side by [validate][starlette_admin.fields.BaseField.validate].
        validators: Callables `(request, field, value)` run in order against the
            parsed form value, each raising `ValueError` to reject it. The first
            error is reported and the remaining validators are skipped. Empty
            values are only checked against `required`; validators never run on
            them. See [starlette_admin.validators][] for built-in validators.
        exclude_from_list: If `True`, hides the field from the list view.
        exclude_from_detail: If `True`, hides the field from the detail view.
        exclude_from_create: If `True`, hides the field from the creation form.
        exclude_from_edit: If `True`, hides the field from the edit form.
        exclude_from_export: If `True`, excludes the field when exporting data.
        exclude_from_import: If `True`, ignores the field when importing data.
        searchable: If `True`, the field is included in search queries.
        orderable: If `True`, allows sorting by this field in the list view.
        inline_editable: If `True`, this field can be edited inline from the
            list page. Set automatically by the view from
            `BaseModelView.inline_editable_fields`; do not set directly.
        copy_to_clipboard: If `True`, renders a button next to the field's value
            on the detail page that copies it to the clipboard.
        list_template: The template path used to render this field in the list view.
        form_template: The template path used to render this field in create/edit forms.
        detail_template: The template path used to render this field in the detail view.
        null_template: The template path used to render this field when its value is `None`,
            in both the list and detail views.
        empty_template: The template path used to render this field when its value is an
            empty list or tuple, in both the list and detail views.
        extra: A dictionary for storing custom metadata. Starlette-admin neither reads
            nor writes to this dictionary. It is provided solely as a convenience for
            developers to attach arbitrary data to a field (e.g., to access within custom
            templates or [BaseAdmin][starlette_admin.base.BaseAdmin] hooks) without needing
            to subclass the field.
    """

    name: str
    label: str | None = None
    type: str | None = None
    help_text: str | None = None
    disabled: bool | None = False
    read_only: bool | None = False
    default: Any | None = None
    # Excluded from equality: closures never compare equal.
    getter: Getter | None = dc_field(default=None, compare=False)
    formatter: dict[RequestAction, Formatter] | None = dc_field(
        default=None, compare=False
    )
    parser: dict[RequestAction, Parser] | None = dc_field(default=None, compare=False)
    id: str = ""
    filters: list[builtins.type["BaseFilter"]] | None = None
    required: bool | None = False
    # Excluded from equality: validators are closures, which never compare equal.
    validators: list[Validator] = dc_field(default_factory=list, compare=False)
    exclude_from_list: bool | None = False
    exclude_from_detail: bool | None = False
    exclude_from_create: bool | None = False
    exclude_from_edit: bool | None = False
    exclude_from_export: bool | None = False
    exclude_from_import: bool | None = False
    searchable: bool | None = True
    orderable: bool | None = True
    inline_editable: bool | None = False
    copy_to_clipboard: bool | None = False
    list_template: str = "fields/list/text.html"
    form_template: str = "fields/form/input.html"
    label_template: str = "fields/form/_label.html"
    detail_template: str = "fields/detail/text.html"
    null_template: str = "fields/detail/_null.html"
    empty_template: str = "fields/detail/_empty.html"
    extra: dict[str, Any] | None = None
    error_class = "is-invalid"
    # Set by `BaseModelView._init_fields`: the field's fully dotted name.
    # Differs from `name` only for fields nested under a CollectionField.
    _name: str = dc_field(default="", init=False, repr=False, compare=False)
    # Set by `BaseModelView._init_fields` on RelationField/CollectionField
    # instances, so nested serialization can resolve the owning view.
    _view: "BaseModelView | None" = dc_field(
        default=None, init=False, repr=False, compare=False
    )

    def __post_init__(self) -> None:
        if self.label is None:
            self.label = self.name.replace("_", " ").capitalize()
        if self.type is None:
            self.type = type(self).__name__
        self.id = self.name
        _log.debug(
            "field initialized: name=%r type=%s label=%r",
            self.name,
            self.type,
            self.label,
        )

    async def parse_form_data(self, request: Request, form_data: FormData) -> Any:
        """
        Extracts the value of this field from submitted form data.
        """
        raw = form_data.get(self.id)
        _log.debug(
            "parse_form_data: field=%r id=%r raw=%r",
            self.name,
            self.id,
            raw,
        )
        return raw

    async def parse_input(self, request: Request, raw: Any) -> Any:
        """Single entry point for turning raw input into this field's value.

        Routes to [parse_import_value][starlette_admin.fields.BaseField.parse_import_value]
        when `request.state.action` is IMPORT, otherwise to
        [parse_form_data][starlette_admin.fields.BaseField.parse_form_data]
        (CREATE, EDIT, INLINE_EDIT).

        Checks `self.parser` first, keyed by `request.state.action`: when the
        current action has an entry, its callable replaces the field's
        default parsing entirely, and `raw` is passed to it unchanged.

        Args:
            raw: A `FormData` for CREATE, EDIT, and INLINE_EDIT; the raw
                import cell value for IMPORT.
        """
        action = request.state.action
        parser = (self.parser or {}).get(action)
        if action == RequestAction.IMPORT:
            if parser is not None:
                return await maybe_async(parser(request, raw))
            return await self.parse_import_value(request, raw)
        if parser is not None:
            source = (
                raw.getlist(self.id)
                if getattr(self, "multiple", False)
                else raw.get(self.id)
            )
            return await maybe_async(parser(request, source))
        return await self.parse_form_data(request, raw)

    async def validate(
        self, request: Request, value: Any, form_values: dict[str, Any]
    ) -> None:
        """Validates this field's parsed form value, raising `ValueError` on
        the first failure.

        An empty value (`None`, `""`, or an empty collection) is only checked
        against `required`; the `validators` chain runs solely on non-empty
        values, so validators never have to handle missing input.

        Parameters:
            request: The request being processed.
            value: This field's own parsed value.
            form_values: The full submitted data, keyed by field name, parsed
                before validation started.
        """
        if is_empty_value(value):
            if self.required:
                raise ValueError(_("This field is required."))
            return
        await self._run_validators(request, self.validators, value, form_values)

    async def _run_validators(
        self,
        request: Request,
        validators: Sequence[Validator],
        value: Any,
        form_values: dict[str, Any],
    ) -> None:
        """Runs each validator in order, awaiting async ones, stopping at the
        first `ValueError`."""
        for validator in validators:
            result = validator(request, self, value, form_values)
            if inspect.isawaitable(result):
                await result

    async def parse_obj(self, request: Request, obj: Any) -> Any:
        """Extracts the value of this field from a model instance.

        By default, this function returns the value of the attribute with the name `self.name` from `obj`,
        or the result of `self.getter(request, obj)` when `getter` is set.
        This function can also be overridden to provide custom logic for computing the value of a field.

        ??? Example

            ```py
            # Suppose we have a `User` model with `id`, `first_name`, and `last_name` fields.
            # We define a custom field called `MyCustomField` to compute the full name of the user:

            class MyCustomField(StringField):
                async def parse_obj(self, request: Request, obj: Any) -> Any:
                    return f"{obj.first_name} {obj.last_name}"  # Returns the full name of the user


            # Then, we can define our view as follows

            class UserView(ModelView):
                fields = ["id", MyCustomField("full_name")]
            ```
        """
        value = (
            await maybe_async(self.getter(request, obj))
            if self.getter is not None
            else getattr(obj, self.name, None)
        )
        _log.debug(
            "parse_obj: field=%r obj_type=%s value=%r",
            self.name,
            type(obj).__name__,
            value,
        )
        return value

    async def serialize_none_value(self, request: Request) -> Any:
        """Formats a None value for sending to the frontend.

        Args:
            request: The current request object.

        Returns:
            Any: The formatted None value.
        """
        _log.debug(
            "serialize_none_value: field=%r action=%s",
            self.name,
            request.state.action,
        )
        return None

    async def serialize_value(self, request: Request, value: Any) -> Any:
        """Formats a value for sending to the frontend based on the current request action.

        !!! important

            Make sure this value is JSON Serializable for RequestAction.LIST and RequestAction.RELATION_LOOKUP

        Args:
            request: The current request object.
            value: The value to format.

        Returns:
            Any: The formatted value.
        """
        _log.debug(
            "serialize_value: field=%r action=%s value=%r",
            self.name,
            request.state.action,
            value,
        )
        return value

    async def parse_import_value(self, request: Request, value: Any) -> Any:
        """Parse a raw cell value from an import row into the value that
        ``view.create()`` expects for this field.

        Delegates to :meth:`parse_form_data` by building a minimal
        :class:`~starlette.datastructures.FormData` from the cell value, so
        import parsing stays consistent with form-submission parsing.  When
        *value* is a list (e.g. a multi-value column from JSON), each item is
        added as a separate form entry under ``self.id`` so that
        :meth:`~starlette.datastructures.FormData.getlist` returns the full
        sequence. Values are stringified through :func:`to_form_entry` so
        non-string primitives round-trip: a `date` is already an ISO string, a
        `bool` becomes `"true"`/`"false"`, and a `dict`/`list` becomes
        `json.dumps(...)` rather than Python `repr`, matching what
        `JSONField.parse_form_data` feeds to `json.loads`.

        Override this method for fields whose import logic cannot be expressed
        as a simple :class:`FormData` round-trip.

        Args:
            request: The request being processed.
            value: Raw value (string, number, bool, list, …) read from the
                import file for this field's column.

        Returns:
            The value to store in the ``data`` dict passed to ``view.create()``.
        """
        _log.debug(
            "parse_import_value: field=%r raw_type=%s raw=%r",
            self.name,
            type(value).__name__,
            value,
        )
        if value is None:
            form_data = FormData([])
        elif isinstance(value, list):
            form_data = FormData([(self.id, to_form_entry(v)) for v in value])
        else:
            form_data = FormData([(self.id, to_form_entry(value))])
        result = await self.parse_form_data(request, form_data)
        _log.debug(
            "parse_import_value: field=%r result=%r",
            self.name,
            result,
        )
        return result

    def additional_css_links(self, request: Request) -> list[str]:
        """Returns a list of CSS file URLs to include for the current request action."""
        return []

    def additional_js_links(self, request: Request) -> list[str]:
        """Returns a list of JavaScript file URLs to include for the current request action."""
        return []

    def _needs_form_assets(self, request: Request) -> bool:
        """True on a form request (create/edit/inline-edit, per `is_form()`),
        or on the list page when this field is `inline_editable`: the
        inline-edit popover renders this field's form fragment on the list
        page, so the list page must ship the same CSS/JS."""
        action = request.state.action
        return action.is_form() or (
            bool(self.inline_editable) and action == RequestAction.LIST
        )

    def dict(self) -> dict[str, Any]:
        """Return the dataclass instance as a dictionary."""
        return asdict(self)

    def input_params(self) -> str:
        """Return HTML input parameters as a string."""
        return html_params(
            {
                "disabled": self.disabled,
                "readonly": self.read_only,
            }
        )

    async def get_create_default(self, request: Request) -> Any:
        """Return the value that should be used to prefill this field on the
        create form.

        ``default`` may be:

        * a static value (e.g. ``default="hello"``),
        * a callable that takes no arguments (e.g. ``default=datetime.now``),
        * a callable that takes the current request as its only argument
          (e.g. ``default=lambda request: request.user.locale``).

        Subclasses may override this method to coerce the default into the
        shape expected by their form templates.
        """
        if self.default is None:
            return None
        if callable(self.default):
            result = self._call_default(request)
            if inspect.isawaitable(result):
                return await result
            return result
        return self.default

    def _call_default(self, request: Request) -> Any:
        """Invoke a callable ``default`` value, passing ``request`` only when
        the callable expects a positional argument.
        """
        assert callable(self.default)
        try:
            sig = inspect.signature(self.default)
        except (ValueError, TypeError):
            return self.default()
        required = [
            p
            for p in sig.parameters.values()
            if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
            and p.default is inspect.Parameter.empty
        ]
        if len(required) == 1:
            return self.default(request)
        return self.default()

@dataclass
class StringField(BaseField):
    """This field is used to represent any kind of short text content."""

    maxlength: int | None = None
    minlength: int | None = None
    input_type: str = "text"
    class_: str = "field-string form-control"
    placeholder: str | None = None

    def input_params(self) -> str:
        return html_params(
            {
                "type": self.input_type,
                "minlength": self.minlength,
                "maxlength": self.maxlength,
                "placeholder": self.placeholder,
                "required": self.required,
                "disabled": self.disabled,
                "readonly": self.read_only,
            }
        )

    async def serialize_value(self, request: Request, value: Any) -> Any:
        return str(value)

@dataclass
class TextAreaField(StringField):
    """This field is used to represent any kind of long text content.
    For short text contents, use [StringField][starlette_admin.fields.StringField]"""

    rows: int = 6
    class_: str = "field-textarea form-control"
    form_template: str = "fields/form/textarea.html"
    detail_template: str = "fields/detail/textarea.html"

    def input_params(self) -> str:
        return html_params(
            {
                "rows": self.rows,
                "minlength": self.minlength,
                "maxlength": self.maxlength,
                "placeholder": self.placeholder,
                "required": self.required,
                "disabled": self.disabled,
                "readonly": self.read_only,
            }
        )

@dataclass
class TinyMCEEditorField(TextAreaField):
    """A field that provides a WYSIWYG editor for long text content using the
     [TinyMCE](https://www.tiny.cloud/) library.

    This field can be used as an alternative to the [TextAreaField][starlette_admin.fields.TextAreaField]
    to provide a more sophisticated editor for user input.

    Parameters:
        version_tinymce: TinyMCE version
        version_tinymce_jquery: TinyMCE jQuery version
        height: Height of the editor
        menubar: Show/hide the menubar in the editor
        statusbar: Show/hide the statusbar in the editor
        toolbar: Toolbar options to show in the editor
        content_style: CSS style to apply to the editor content
        extra_options: Other options to pass to TinyMCE
    """

    class_: str = "field-tinymce-editor form-control"
    detail_template: str = "fields/detail/tinymce.html"
    version_tinymce: str = "6.4"
    version_tinymce_jquery: str = "2.0"
    height: int = 300
    menubar: bool | str = False
    statusbar: bool = False
    toolbar: str = (
        "undo redo | formatselect | bold italic backcolor | alignleft aligncenter"
        " alignright alignjustify | bullist numlist outdent indent | removeformat"
    )
    content_style: str = (
        "body { font-family: -apple-system, BlinkMacSystemFont, San Francisco, Segoe"
        " UI, Roboto, Helvetica Neue, sans-serif; font-size: 14px;"
        " -webkit-font-smoothing: antialiased; }"
    )
    extra_options: dict[str, Any] = dc_field(default_factory=dict)
    """For more options, see the [TinyMCE | Documentation](https://www.tiny.cloud/docs/tinymce/6/)"""

    def additional_js_links(self, request: Request) -> list[str]:
        if self._needs_form_assets(request):
            return [
                f"https://cdn.jsdelivr.net/npm/tinymce@{self.version_tinymce}/tinymce.min.js",
                f"https://cdn.jsdelivr.net/npm/@tinymce/tinymce-jquery@{self.version_tinymce_jquery}/dist/tinymce-jquery.min.js",
            ]
        return []

    def input_params(self) -> str:
        _options = {
            "height": self.height,
            "menubar": self.menubar,
            "statusbar": self.statusbar,
            "toolbar": self.toolbar,
            "content_style": self.content_style,
            **self.extra_options,
        }

        return (
            super().input_params()
            + " "
            + html_params({"data-options": json.dumps(_options)})
        )

@dataclass
class EmailField(StringField):
    """This field is used to represent a text content
    that stores a single email address.

    [email][starlette_admin.validators.email] is used as the default validator
    when `validators` is empty, to ensure the value is a valid email address.
    Pass your own `validators` to override it.
    """

    input_type: str = "email"
    list_template: str = "fields/list/email.html"
    class_: str = "field-email form-control"
    detail_template: str = "fields/detail/email.html"

    def __post_init__(self) -> None:
        super().__post_init__()
        if not self.validators:
            self.validators = [email()]

@dataclass
class URLField(StringField):
    """This field is used to represent a text content that stores a single URL.

    [url][starlette_admin.validators.url] is used as the default validator
    when `validators` is empty, to ensure the value is a valid absolute URL.
    Pass your own `validators` to override it.

    Attributes:
        allowed_schemes: Schemes allowed when rendering the value on the list
            and detail pages. Any other scheme (javascript:, data:, vbscript:,
            …) is stripped. Defaults to `http`, `https`, `mailto`, `tel`,
            `ftp`, `ftps`, and `sms`. Set to `None` to skip this check and
            render the value as-is.
    """

    input_type: str = "url"
    list_template: str = "fields/list/url.html"
    class_: str = "field-url form-control"
    detail_template: str = "fields/detail/url.html"
    allowed_schemes: Collection[str] | None = dc_field(
        default_factory=lambda: _URL_ALLOWED_SCHEMES
    )

    def __post_init__(self) -> None:
        super().__post_init__()
        if not self.validators:
            self.validators = [url(schemes=self.allowed_schemes)]

    async def serialize_value(self, request: Request, value: Any) -> Any:
        value = await super().serialize_value(request, value)
        if self.allowed_schemes is not None and request.state.action in (
            RequestAction.LIST,
            RequestAction.DETAIL,
        ):
            return safe_url(value, self.allowed_schemes)
        return value

@dataclass
class PhoneField(StringField):
    """A StringField, except renders an `<input type="phone">`."""

    input_type: str = "phone"
    class_: str = "field-phone form-control"

@dataclass
class ColorField(StringField):
    """A StringField, except renders an `<input type="color">`."""

    input_type: str = "color"
    class_: str = "field-color form-control form-control-color"
    list_template: str = "fields/list/color.html"
    detail_template: str = "fields/detail/color.html"

@dataclass
class PasswordField(StringField):
    """A StringField, except renders an `<input type="password">`."""

    input_type: str = "password"
    class_: str = "field-password form-control"

@dataclass
class UUIDField(StringField):
    """This field is used to represent a text content that stores a single UUID.

    [uuid][starlette_admin.validators.uuid] is used as the default validator
    when `validators` is empty, restricted to `version` when set, to ensure
    the value is a valid UUID. Pass your own `validators` to override it.

    Attributes:
        version: When set (1, 3, 4, or 5), also requires the UUID to be of
            that version.
    """

    class_: str = "field-uuid form-control"
    version: int | None = None
    copy_to_clipboard: bool | None = True

    def __post_init__(self) -> None:
        super().__post_init__()
        if not self.validators:
            self.validators = [uuid(version=self.version)]

@dataclass
class IPAddressField(StringField):
    """This field is used to represent a text content that stores a single IP address.

    [ip_address][starlette_admin.validators.ip_address] is used as the default
    validator when `validators` is empty, restricted to `ipv4`/`ipv6` when set,
    to ensure the value is a valid IP address. Pass your own `validators` to
    override it.

    Attributes:
        ipv4: If `True`, accepts IPv4 addresses.
        ipv6: If `True`, accepts IPv6 addresses.
    """

    class_: str = "field-ip-address form-control"
    ipv4: bool = True
    ipv6: bool = False

    def __post_init__(self) -> None:
        super().__post_init__()
        if not self.validators:
            self.validators = [ip_address(ipv4=self.ipv4, ipv6=self.ipv6)]

@dataclass
class SlugField(StringField):
    """
    A text field that is auto-populated (client-side) from another field as the
    user types, editable but pre-filled with a URL-safe slug.

    ```python
    SlugField("slug", populate_from="title")
    ```

    The ``populate_from`` parameter must be the *name* of another field on the
    same form.  A small piece of JavaScript watches that source field and fills
    this field whenever it is empty (or still matches the auto-generated value).
    Once the user manually edits the slug field the auto-fill stops, so an
    intentional override is never clobbered.
    """

    populate_from: str | None = None
    class_: str = "form-control"
    form_template: str = "fields/form/slug.html"

    def __post_init__(self) -> None:
        if not self.populate_from:
            raise ValueError(
                f"SlugField {self.name!r}: 'populate_from' must be set to the name "
                "of another field on the same form"
            )
        super().__post_init__()
        if not self.validators:
            self.validators = [slug()]

@dataclass
class NumberField(StringField):
    """This field is used to represent the value of properties
    that store numbers of any type (integers or decimals).
    Should not be used directly. use [IntegerField][starlette_admin.fields.IntegerField]
    or [DecimalField][starlette_admin.fields.DecimalField]
    """

    input_type: str = "number"
    max: int | None = None
    min: int | None = None
    step: str | int | None = None

    def __post_init__(self) -> None:
        super().__post_init__()
        if not self.validators and (self.min is not None or self.max is not None):
            self.validators = [number_range(min=self.min, max=self.max)]

    def input_params(self) -> str:
        return html_params(
            {
                "type": self.input_type,
                "min": self.min,
                "max": self.max,
                "step": self.step,
                "placeholder": self.placeholder,
                "required": self.required,
                "disabled": self.disabled,
                "readonly": self.read_only,
            }
        )

@dataclass
class IntegerField(NumberField):
    """
    This field is used to represent the value of properties that store integer numbers.
    Erroneous input is ignored and will not be accepted as a value."""

    class_: str = "field-integer form-control"

    async def parse_form_data(
        self, request: Request, form_data: FormData
    ) -> int | None:
        raw = form_data.get(self.id)
        try:
            result = int(raw)  # ty: ignore[invalid-argument-type]
            _log.debug(
                "IntegerField.parse_form_data: field=%r raw=%r -> %r",
                self.name,
                raw,
                result,
            )
            return result
        except (ValueError, TypeError):
            _log.warning(
                "IntegerField.parse_form_data: field=%r cannot coerce raw=%r to int; returning None",
                self.name,
                raw,
            )
            return None

    async def parse_import_value(self, request: Request, value: Any) -> int | None:
        if value is None or value == "":
            _log.debug(
                "IntegerField.parse_import_value: field=%r empty value; returning None",
                self.name,
            )
            return None
        try:
            result = int(value)
            _log.debug(
                "IntegerField.parse_import_value: field=%r raw=%r -> %r",
                self.name,
                value,
                result,
            )
            return result
        except (ValueError, TypeError) as exc:
            _log.error(
                "IntegerField.parse_import_value: field=%r invalid integer raw=%r; %s",
                self.name,
                value,
                exc,
            )
            raise ValueError(
                _("Invalid integer value for %(field)s") % {"field": self.name}
            ) from exc

    async def serialize_value(self, request: Request, value: Any) -> Any:
        result = int(value)
        _log.debug(
            "IntegerField.serialize_value: field=%r value=%r -> %r",
            self.name,
            value,
            result,
        )
        return result