diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 16:10:54 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 16:10:54 +0000 |
commit | 3b2c8da6b3117ca186e27a7f94fa44b17f6a82ed (patch) | |
tree | d8d343b76ef070019c69531e4bd0f0964804e4d4 /docs/html.rst | |
parent | Initial commit. (diff) | |
download | markupsafe-3b2c8da6b3117ca186e27a7f94fa44b17f6a82ed.tar.xz markupsafe-3b2c8da6b3117ca186e27a7f94fa44b17f6a82ed.zip |
Adding upstream version 2.1.2.upstream/2.1.2upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | docs/html.rst | 49 |
1 files changed, 49 insertions, 0 deletions
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"><script></a>') |