11Metadata-Version: 1.1
22Name: MarkupSafe
3- Version: 0.18
3+ Version: 0.23
44Summary: Implements a XML/HTML/XHTML Markup safe string for Python
55Home-page: http://github.com/mitsuhiko/markupsafe
66Author: Armin Ronacher
@@ -29,6 +29,9 @@ Description: MarkupSafe
2929 >>> soft_unicode(Markup('foo'))
3030 Markup(u'foo')
3131
32+ HTML Representations
33+ --------------------
34+
3235 Objects can customize their HTML markup equivalent by overriding
3336 the `__html__` function:
3437
@@ -41,6 +44,9 @@ Description: MarkupSafe
4144 >>> Markup(Foo())
4245 Markup(u'<strong>Nice</strong>')
4346
47+ Silent Escapes
48+ --------------
49+
4450 Since MarkupSafe 0.10 there is now also a separate escape function
4551 called `escape_silent` that returns an empty string for `None` for
4652 consistency with other systems that return empty strings for `None`
@@ -58,6 +64,48 @@ Description: MarkupSafe
5864 def escape(cls, s):
5965 return cls(escape(s))
6066
67+ New-Style String Formatting
68+ ---------------------------
69+
70+ Starting with MarkupSafe 0.21 new style string formats from Python 2.6 and
71+ 3.x are now fully supported. Previously the escape behavior of those
72+ functions was spotty at best. The new implementations operates under the
73+ following algorithm:
74+
75+ 1. if an object has an ``__html_format__`` method it is called as
76+ replacement for ``__format__`` with the format specifier. It either
77+ has to return a string or markup object.
78+ 2. if an object has an ``__html__`` method it is called.
79+ 3. otherwise the default format system of Python kicks in and the result
80+ is HTML escaped.
81+
82+ Here is how you can implement your own formatting::
83+
84+ class User(object):
85+
86+ def __init__(self, id, username):
87+ self.id = id
88+ self.username = username
89+
90+ def __html_format__(self, format_spec):
91+ if format_spec == 'link':
92+ return Markup('<a href="/user/{0}">{1}</a>').format(
93+ self.id,
94+ self.__html__(),
95+ )
96+ elif format_spec:
97+ raise ValueError('Invalid format spec')
98+ return self.__html__()
99+
100+ def __html__(self):
101+ return Markup('<span class=user>{0}</span>').format(self.username)
102+
103+ And to format that user:
104+
105+ >>> user = User(1, 'foo')
106+ >>> Markup('<p>User: {0:link}').format(user)
107+ Markup(u'<p>User: <a href="/user/1"><span class=user>foo</span></a>')
108+
61109Platform: UNKNOWN
62110Classifier: Development Status :: 5 - Production/Stable
63111Classifier: Environment :: Web Environment
0 commit comments