Source code
Revision control
Copy as Markdown
Other Tools
import typing as t
from . import Markup
def escape(s: t.Any) -> Markup:
"""Replace the characters ``&``, ``<``, ``>``, ``'``, and ``"`` in
the string with HTML-safe sequences. Use this if you need to display
text that might contain such characters in HTML.
If the object has an ``__html__`` method, it is called and the
return value is assumed to already be safe for HTML.
:param s: An object to be converted to a string and escaped.
:return: A :class:`Markup` string with the escaped text.
"""
if hasattr(s, "__html__"):
return Markup(s.__html__())
return Markup(
str(s)
.replace("&", "&")
.replace(">", ">")
.replace("<", "<")
.replace("'", "'")
.replace('"', """)
)
def escape_silent(s: t.Optional[t.Any]) -> Markup:
"""Like :func:`escape` but treats ``None`` as the empty string.
Useful with optional values, as otherwise you get the string
``'None'`` when the value is ``None``.
>>> escape(None)
Markup('None')
>>> escape_silent(None)
Markup('')
"""
if s is None:
return Markup()
return escape(s)
def soft_str(s: t.Any) -> str:
"""Convert an object to a string if it isn't already. This preserves
a :class:`Markup` string rather than converting it back to a basic
string, so it will still be marked as safe and won't be escaped
again.
>>> value = escape("<User 1>")
>>> value
Markup('<User 1>')
>>> escape(str(value))
Markup('&lt;User 1&gt;')
>>> escape(soft_str(value))
Markup('<User 1>')
"""
if not isinstance(s, str):
return str(s)
return s
def soft_unicode(s: t.Any) -> str:
import warnings
warnings.warn(
"'soft_unicode' has been renamed to 'soft_str'. The old name"
" will be removed in MarkupSafe 2.1.",
DeprecationWarning,
stacklevel=2,
)
return soft_str(s)