You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
78 lines
2.3 KiB
78 lines
2.3 KiB
.. currentmodule:: markupsafe
|
|
|
|
String Formatting
|
|
=================
|
|
|
|
The :class:`Markup` class can be used as a format string. Objects
|
|
formatted into a markup string will be escaped first.
|
|
|
|
|
|
Format Method
|
|
-------------
|
|
|
|
The ``format`` method extends the standard :meth:`str.format` behavior
|
|
to use an ``__html_format__`` method.
|
|
|
|
#. If an object has an ``__html_format__`` method, it is called as a
|
|
replacement for the ``__format__`` method. It is passed a format
|
|
specifier if it's given. The method must return a string or
|
|
:class:`Markup` instance.
|
|
|
|
#. If an object has an ``__html__`` method, it is called. If a format
|
|
specifier was passed and the class defined ``__html__`` but not
|
|
``__html_format__``, a ``ValueError`` is raised.
|
|
|
|
#. Otherwise Python's default format behavior is used and the result
|
|
is escaped.
|
|
|
|
For example, to implement a ``User`` that wraps its ``name`` in a
|
|
``span`` tag, and adds a link when using the ``"link"`` format
|
|
specifier:
|
|
|
|
.. code-block:: python
|
|
|
|
class User(object):
|
|
def __init__(self, id, name):
|
|
self.id = id
|
|
self.name = name
|
|
|
|
def __html_format__(self, format_spec):
|
|
if format_spec == "link":
|
|
return Markup(
|
|
'<a href="/user/{}">{}</a>'
|
|
).format(self.id, self.__html__())
|
|
elif format_spec:
|
|
raise ValueError("Invalid format spec")
|
|
return self.__html__()
|
|
|
|
def __html__(self):
|
|
return Markup(
|
|
'<span class="user">{0}</span>'
|
|
).format(self.name)
|
|
|
|
|
|
.. code-block:: pycon
|
|
|
|
>>> user = User(3, "<script>")
|
|
>>> escape(user)
|
|
Markup('<span class="user"><script></span>')
|
|
>>> Markup("<p>User: {user:link}").format(user=user)
|
|
Markup('<p>User: <a href="/user/3"><span class="user"><script></span></a>
|
|
|
|
See Python's docs on :ref:`format string syntax <python:formatstrings>`.
|
|
|
|
|
|
printf-style Formatting
|
|
-----------------------
|
|
|
|
Besides escaping, there's no special behavior involved with percent
|
|
formatting.
|
|
|
|
.. code-block:: pycon
|
|
|
|
>>> user = User(3, "<script>")
|
|
>>> Markup('<a href="/user/%d">%s</a>') % (user.id, user.name)
|
|
Markup('<a href="/user/3"><script></a>')
|
|
|
|
See Python's docs on :ref:`printf-style formatting <python:old-string-formatting>`.
|