markupsafe 3.0.3: Pin MarkupSafe __html__ protocol evaluation discrepancies between format() and escape(), format specifier rejections, % helper type errors, and mutation auto-escaping

# MarkupSafe Formatting, Protocol, and Interpolation Behavior Notes

## 1. Search Result
- **`search_known_solution`**: Queried for `markupsafe` configuration, environment, and formatting behaviors. The search returned matches on unrelated packages and template engines (`sha256:7165aa668a3332e95a7414214c7250c1ba3b40d762ba8657b145704ef6b8c93e` for Jinja2 whitespace trimming, and `sha256:b2080a64b14418f27755c77010ee8859ad93ed72a2c7e3ed4ce68c76ec5d96cc` for Jinja2 `StrictUndefined`). No existing sample covered MarkupSafe's `__html__` protocol evaluation discrepancies, `__html_format__` requirements, `%` helper limitations, or string mutation auto-escaping.

## 2. Release Pinned
- Pinned `markupsafe==3.0.3` under Python 3.10+.

## 3. What a Model Would Have Written Instead
- A model would assume that implementing `__html__() -> str` on a custom object is sufficient across all HTML rendering methods in the library. Specifically, it would expect `Markup("{}").format(obj)` to yield the same unescaped HTML output as `escape(obj)` and `Markup("%s") % obj`.
- A model would expect `Markup` strings to support standard string format specifiers in `.format()`, such as `Markup("{:>10}").format(Markup("text"))`.
- A model would expect `%x`, `%X`, `%o`, and `%c` interpolation on `Markup` templates to format integer arguments just like `%d`.
- A model would expect string padding methods on `Markup` (like `.ljust()`, `.rjust()`, `.center()`) to accept HTML characters like `"<"` as the `fillchar`.

## 4. How the Wrong Version Fails
- The `__html__() -> str` divergence fails silently with escaped HTML: `Markup("<div>{}</div>").format(obj)` produces `Markup("<div>&lt;p&gt;...&lt;/p&gt;</div>")` instead of raw markup. Because `EscapeFormatter.format_field` invokes `self.escape(rv)` on any return value that is not already an instance of `Markup`, plain `str` objects are treated as untrusted text.
- Format specifiers on `Markup` instances fail loudly with `ValueError: Unsupported format specification for Markup.`
- Objects defining `__html__()` formatted with specifiers fail loudly with `ValueError: Format specifier ... given, but <class> does not define __html_format__.`
- Integer base interpolation with `%x` / `%o` fails loudly with `TypeError: %x format: an integer is required, not _MarkupEscapeHelper` because `_MarkupEscapeHelper` implements `__int__` and `__float__` but lacks `__index__`.
- String padding with HTML special characters fails loudly with `TypeError: The fill character must be exactly one character long` because `self.escape(fillchar)` expands the single character into a multi-character HTML entity before calling the underlying string padding method.

{"case":{"believed":"Markup.format() treats objects returning str from __html__() as pre-escaped HTML identically to escape() and % interpolation.","caseId":"case:sha256:13fba1ebc23a323dde88188203f14a10b3fa8a7dc9dd7c1f1825d21cee7cb0c5","contract":["Markup.format() escapes plain str returns from __html__() into HTML entities because EscapeFormatter wraps format_field results in escape(), requiring __html__() to return Markup or define __html_format__ for unescaped formatting","assert Markup.format() with format specifiers raises ValueError on Markup instances and classes defining only __html__","assert Markup % interpolation fails with TypeError on %x, %X, %o, and %c because _MarkupEscapeHelper lacks __index__","assert Markup.replace auto-escapes plain string replacements and padding methods fail with TypeError on HTML fillchar","assert Markup.striptags and unescape return plain str which re-escapes when combined with Markup","assert soft_str preserves Markup instances to prevent double escaping when re-passed to escape"],"goal":"Pin MarkupSafe __html__ protocol evaluation discrepancies between format() and escape(), format specifier rejections, % helper type errors, and mutation auto-escaping","kind":"HOW","packages":["pkg:pypi/markupsafe@3.0.3"],"schemaVersion":1,"symbols":["Markup","EscapeFormatter","escape","soft_str"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","ecosystem":"pypi","executionContext":"python","language":"python","os":"linux","packageManager":"pip","runtime":"python","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/markupsafe@3.0.3"],"schemaVersion":1,"symbols":["Markup","EscapeFormatter","escape","soft_str"],"verifierAdapter":"python@1"}

markupsafe==3.0.3

"""MarkupSafe configuration and formatting contract package."""

"""Safe formatting and component rendering helpers for MarkupSafe."""

from __future__ import annotations

from typing import Any
from markupsafe import Markup, escape, escape_silent, soft_str


class RawStringComponent:
    """Component returning plain str from __html__.

    Works as safe HTML with escape() and % interpolation, but gets escaped by Markup.format().
    """

    def __init__(self, tag: str, content: str) -> None:
        self.tag = tag
        self.content = content

    def __html__(self) -> str:
        return f"<{self.tag}>{self.content}</{self.tag}>"


class MarkupComponent:
    """Component returning Markup from __html__.

    Works as unescaped safe HTML across escape(), %, and Markup.format().
    """

    def __init__(self, tag: str, content: str) -> None:
        self.tag = tag
        self.content = content

    def __html__(self) -> Markup:
        return Markup(f"<{self.tag}>{escape(self.content)}</{self.tag}>")


class FormattableComponent:
    """Component implementing __html_format__ to support custom format specifiers in Markup.format()."""

    def __init__(self, text: str) -> None:
        self.text = text

    def __html__(self) -> Markup:
        return Markup(f"<span>{escape(self.text)}</span>")

    def __html_format__(self, format_spec: str) -> Markup:
        if format_spec == "bold":
            return Markup(f"<strong>{escape(self.text)}</strong>")
        if format_spec == "italic":
            return Markup(f"<em>{escape(self.text)}</em>")
        if not format_spec:
            return self.__html__()
        raise ValueError(f"Unknown format specifier: {format_spec}")


def safe_render_template(template: Markup, *args: Any, **kwargs: Any) -> Markup:
    """Render a Markup template using format(), ensuring components behave safely."""
    return template.format(*args, **kwargs)


def safe_escape_chain(value: Any) -> Markup:
    """Preserve pre-escaped Markup objects while escaping unknown string inputs."""
    return escape(soft_str(value))

"""Contract test proving MarkupSafe formatting, protocol, and interpolation behaviors."""

import sys
from pathlib import Path

# Add project root to sys.path
sys.path.insert(0, str(Path(__file__).parent.parent))

from markupsafe import Markup, escape, escape_silent, soft_str
from src.formatter import (
    RawStringComponent,
    MarkupComponent,
    FormattableComponent,
    safe_render_template,
    safe_escape_chain,
)


def test_html_protocol_format_vs_escape() -> None:
    """Prove __html__() returning plain str is escaped by Markup.format() but not by escape() or %."""
    raw_comp = RawStringComponent("p", "hello & world")

    # escape() treats __html__ str as safe HTML
    escaped_direct = escape(raw_comp)
    assert escaped_direct == Markup("<p>hello & world</p>")

    # %s interpolation treats __html__ str as safe HTML
    percent_rendered = Markup("<div>%s</div>") % raw_comp
    assert percent_rendered == Markup("<div><p>hello & world</p></div>")

    # Markup.format() treats plain str return as untrusted and escapes HTML characters
    format_rendered = Markup("<div>{}</div>").format(raw_comp)
    assert format_rendered == Markup("<div>&lt;p&gt;hello &amp; world&lt;/p&gt;</div>")

    # Returning Markup from __html__ preserves unescaped HTML in Markup.format()
    markup_comp = MarkupComponent("p", "hello & world")
    markup_rendered = safe_render_template(Markup("<div>{}</div>"), markup_comp)
    assert markup_rendered == Markup("<div><p>hello &amp; world</p></div>")

    # Custom __html_format__ allows explicit formatting in Markup.format()
    formattable = FormattableComponent("alert")
    assert safe_render_template(Markup("{:bold}"), formattable) == Markup("<strong>alert</strong>")
    assert safe_render_template(Markup("{:italic}"), formattable) == Markup("<em>alert</em>")


def test_format_specifier_rejections() -> None:
    """Prove format specifiers raise ValueError on Markup instances and __html__-only classes."""
    # Plain strings accept format specifiers and escape the padded result
    assert Markup("{:>8}").format("test") == Markup("    test")

    # Markup instances reject any non-empty format specifier
    try:
        Markup("{:>8}").format(Markup("test"))
        raise AssertionError("Expected ValueError on Markup format specifier")
    except ValueError as exc:
        assert "Unsupported format specification for Markup" in str(exc)

    try:
        Markup("{:s}").format(Markup("test"))
        raise AssertionError("Expected ValueError on {:s} with Markup")
    except ValueError as exc:
        assert "Unsupported format specification for Markup" in str(exc)

    # Classes implementing __html__ without __html_format__ reject format specifiers
    raw_comp = RawStringComponent("span", "text")
    try:
        Markup("{:>10}").format(raw_comp)
        raise AssertionError("Expected ValueError on __html__ class without __html_format__")
    except ValueError as exc:
        assert "does not define __html_format__" in str(exc)


def test_mod_interpolation_and_helper_limitations() -> None:
    """Prove % interpolation succeeds on %s, %r, %d, %f but fails on %x, %X, %o, %c."""
    # Standard formatters supported by _MarkupEscapeHelper (__str__, __repr__, __int__, __float__)
    assert Markup("val=%d") % 42 == Markup("val=42")
    assert Markup("price=%.2f") % 9.99 == Markup("price=9.99")
    assert Markup("repr=%r") % "<a>" == Markup("repr=&#39;&lt;a&gt;&#39;")

    # Integer base formatting fails because _MarkupEscapeHelper lacks __index__
    for spec in ("%x", "%X", "%o"):
        try:
            Markup(f"hex={spec}") % 255
            raise AssertionError(f"Expected TypeError for {spec}")
        except TypeError as exc:
            assert "an integer is required" in str(exc) or "_MarkupEscapeHelper" in str(exc)

    # Mapping lookup with %x also fails because dictionary lookup wraps the int in _MarkupEscapeHelper
    try:
        Markup("%(count)x") % {"count": 255}
        raise AssertionError("Expected TypeError for %(count)x")
    except TypeError as exc:
        assert "an integer is required" in str(exc) or "_MarkupEscapeHelper" in str(exc)


def test_string_mutation_auto_escaping() -> None:
    """Prove replace, ljust, and padding methods auto-escape, and HTML fillchar fails with TypeError."""
    # replace() automatically escapes replacement strings unless wrapped in Markup
    base = Markup("<a>foo</a>")
    assert base.replace("foo", "<b>") == Markup("<a>&lt;b&gt;</a>")
    assert base.replace("foo", Markup("<b>")) == Markup("<a><b></a>")

    # Padding methods work with safe 1-character fillchars
    assert Markup("tag").ljust(7, "-") == Markup("tag----")
    assert Markup("tag").rjust(7, "=") == Markup("====tag")
    assert Markup("tag").center(7, "_") == Markup("__tag__")

    # Passing HTML special chars (<, >, &, ', ") to fillchar fails because self.escape() expands to >1 char
    for char in ("<", ">", "&", "'", '"'):
        try:
            Markup("tag").ljust(7, char)
            raise AssertionError(f"Expected TypeError for fillchar '{char}'")
        except TypeError as exc:
            assert "fill character must be exactly one character long" in str(exc)

    # join() escapes plain string elements
    joined = Markup("<br>").join(["<p>", Markup("<b>safe</b>")])
    assert joined == Markup("&lt;p&gt;<br><b>safe</b>")


def test_striptags_and_unescape_return_str() -> None:
    """Prove striptags and unescape return plain str which re-escapes when combined with Markup."""
    source = Markup("<b>&amp;</b>")

    stripped = source.striptags()
    assert type(stripped) is str
    assert not isinstance(stripped, Markup)
    assert stripped == "&"
    # Concatenating plain str into Markup causes re-escaping
    assert Markup("Clean: ") + stripped == Markup("Clean: &amp;")

    unescaped = source.unescape()
    assert type(unescaped) is str
    assert not isinstance(unescaped, Markup)
    assert unescaped == "<b>&</b>"
    assert Markup("Output: ") + unescaped == Markup("Output: &lt;b&gt;&amp;&lt;/b&gt;")


def test_soft_str_and_escape_silent() -> None:
    """Prove soft_str preserves Markup instances and escape_silent handles None."""
    escaped_tag = escape("<div>")

    # str() converts Markup to plain str, leading to double escaping
    plain_str_tag = str(escaped_tag)
    assert type(plain_str_tag) is str
    assert escape(plain_str_tag) == Markup("&amp;lt;div&amp;gt;")

    # soft_str() preserves Markup instance, preventing double escaping
    preserved_tag = soft_str(escaped_tag)
    assert isinstance(preserved_tag, Markup)
    assert escape(preserved_tag) == Markup("&lt;div&gt;")
    assert safe_escape_chain(escaped_tag) == Markup("&lt;div&gt;")

    # escape(None) vs escape_silent(None)
    assert escape(None) == Markup("None")
    assert escape_silent(None) == Markup("")
    assert escape_silent("<span>") == Markup("&lt;span&gt;")


def main() -> None:
    """Run all contract tests."""
    test_html_protocol_format_vs_escape()
    test_format_specifier_rejections()
    test_mod_interpolation_and_helper_limitations()
    test_string_mutation_auto_escaping()
    test_striptags_and_unescape_return_str()
    test_soft_str_and_escape_silent()
    print("All MarkupSafe contract assertions passed successfully.")


if __name__ == "__main__":
    main()