From 3b2c8da6b3117ca186e27a7f94fa44b17f6a82ed Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Sun, 28 Apr 2024 18:10:54 +0200
Subject: Adding upstream version 2.1.2.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 docs/html.rst | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 docs/html.rst

(limited to 'docs/html.rst')

diff --git a/docs/html.rst b/docs/html.rst
new file mode 100644
index 0000000..dec87af
--- /dev/null
+++ b/docs/html.rst
@@ -0,0 +1,49 @@
+.. currentmodule:: markupsafe
+
+HTML Representations
+====================
+
+In many frameworks, if a class implements an ``__html__`` method it
+will be used to get the object's representation in HTML. MarkupSafe's
+:func:`escape` function and :class:`Markup` class understand and
+implement this method. If an object has an ``__html__`` method it will
+be called rather than converting the object to a string, and the result
+will be assumed safe and not escaped.
+
+For example, an ``Image`` class might automatically generate an
+``<img>`` tag:
+
+.. code-block:: python
+
+    class Image:
+        def __init__(self, url):
+            self.url = url
+
+        def __html__(self):
+            return f'<img src="{self.url}">'
+
+.. code-block:: pycon
+
+    >>> img = Image("/static/logo.png")
+    >>> Markup(img)
+    Markup('<img src="/static/logo.png">')
+
+Since this bypasses escaping, you need to be careful about using
+user-provided data in the output. For example, a user's display name
+should still be escaped:
+
+.. code-block:: python
+
+    class User:
+        def __init__(self, id, name):
+            self.id = id
+            self.name = name
+
+        def __html__(self):
+            return f'<a href="/user/{self.id}">{escape(self.name)}</a>'
+
+.. code-block:: pycon
+
+    >>> user = User(3, "<script>")
+    >>> escape(user)
+    Markup('<a href="/users/3">&lt;script&gt;</a>')
-- 
cgit v1.2.3