diff options
Diffstat (limited to 'lib/spack/external/markupsafe/README.rst')
-rw-r--r-- | lib/spack/external/markupsafe/README.rst | 138 |
1 files changed, 47 insertions, 91 deletions
diff --git a/lib/spack/external/markupsafe/README.rst b/lib/spack/external/markupsafe/README.rst index 360a0877a4..3548b8d1f7 100644 --- a/lib/spack/external/markupsafe/README.rst +++ b/lib/spack/external/markupsafe/README.rst @@ -1,113 +1,69 @@ MarkupSafe ========== -Implements a unicode subclass that supports HTML strings: +MarkupSafe implements a text object that escapes characters so it is +safe to use in HTML and XML. Characters that have special meanings are +replaced so that they display as the actual characters. This mitigates +injection attacks, meaning untrusted user input can safely be displayed +on a page. -.. code-block:: python - >>> from markupsafe import Markup, escape - >>> escape("<script>alert(document.cookie);</script>") - Markup(u'<script>alert(document.cookie);</script>') - >>> tmpl = Markup("<em>%s</em>") - >>> tmpl % "Peter > Lustig" - Markup(u'<em>Peter > Lustig</em>') - -If you want to make an object unicode that is not yet unicode -but don't want to lose the taint information, you can use the -``soft_unicode`` function. (On Python 3 you can also use ``soft_str`` which -is a different name for the same function). - -.. code-block:: python - - >>> from markupsafe import soft_unicode - >>> soft_unicode(42) - u'42' - >>> soft_unicode(Markup('foo')) - Markup(u'foo') - -HTML Representations --------------------- - -Objects can customize their HTML markup equivalent by overriding -the ``__html__`` function: +Installing +---------- -.. code-block:: python +Install and update using `pip`_: - >>> class Foo(object): - ... def __html__(self): - ... return '<strong>Nice</strong>' - ... - >>> escape(Foo()) - Markup(u'<strong>Nice</strong>') - >>> Markup(Foo()) - Markup(u'<strong>Nice</strong>') +.. code-block:: text -Silent Escapes --------------- + pip install -U MarkupSafe -Since MarkupSafe 0.10 there is now also a separate escape function -called ``escape_silent`` that returns an empty string for ``None`` for -consistency with other systems that return empty strings for ``None`` -when escaping (for instance Pylons' webhelpers). +.. _pip: https://pip.pypa.io/en/stable/quickstart/ -If you also want to use this for the escape method of the Markup -object, you can create your own subclass that does that: -.. code-block:: python +Examples +-------- - from markupsafe import Markup, escape_silent as escape +.. code-block:: pycon - class SilentMarkup(Markup): - __slots__ = () - - @classmethod - def escape(cls, s): - return cls(escape(s)) - -New-Style String Formatting ---------------------------- - -Starting with MarkupSafe 0.21 new style string formats from Python 2.6 and -3.x are now fully supported. Previously the escape behavior of those -functions was spotty at best. The new implementations operates under the -following algorithm: - -1. if an object has an ``__html_format__`` method it is called as - replacement for ``__format__`` with the format specifier. It either - has to return a string or markup object. -2. if an object has an ``__html__`` method it is called. -3. otherwise the default format system of Python kicks in and the result - is HTML escaped. - -Here is how you can implement your own formatting: + >>> from markupsafe import Markup, escape + >>> # escape replaces special characters and wraps in Markup + >>> escape('<script>alert(document.cookie);</script>') + Markup(u'<script>alert(document.cookie);</script>') + >>> # wrap in Markup to mark text "safe" and prevent escaping + >>> Markup('<strong>Hello</strong>') + Markup('<strong>hello</strong>') + >>> escape(Markup('<strong>Hello</strong>')) + Markup('<strong>hello</strong>') + >>> # Markup is a text subclass (str on Python 3, unicode on Python 2) + >>> # methods and operators escape their arguments + >>> template = Markup("Hello <em>%s</em>") + >>> template % '"World"' + Markup('Hello <em>"World"</em>') -.. code-block:: python - class User(object): +Donate +------ - def __init__(self, id, username): - self.id = id - self.username = username +The Pallets organization develops and supports MarkupSafe and other +libraries that use it. In order to grow the community of contributors +and users, and allow the maintainers to devote more time to the +projects, `please donate today`_. - def __html_format__(self, format_spec): - if format_spec == 'link': - return Markup('<a href="/user/{0}">{1}</a>').format( - self.id, - self.__html__(), - ) - elif format_spec: - raise ValueError('Invalid format spec') - return self.__html__() +.. _please donate today: https://palletsprojects.com/donate - def __html__(self): - return Markup('<span class=user>{0}</span>').format(self.username) -And to format that user: +Links +----- -.. code-block:: python +* Website: https://palletsprojects.com/p/markupsafe/ +* Documentation: https://markupsafe.palletsprojects.com/ +* License: `BSD-3-Clause <https://github.com/pallets/markupsafe/blob/master/LICENSE.rst>`_ +* Releases: https://pypi.org/project/MarkupSafe/ +* Code: https://github.com/pallets/markupsafe +* Issue tracker: https://github.com/pallets/markupsafe/issues +* Test status: - >>> user = User(1, 'foo') - >>> Markup('<p>User: {0:link}').format(user) - Markup(u'<p>User: <a href="/user/1"><span class=user>foo</span></a>') + * Linux, Mac: https://travis-ci.org/pallets/markupsafe + * Windows: https://ci.appveyor.com/project/pallets/markupsafe -Markupsafe supports Python 2.6, 2.7 and Python 3.3 and higher. +* Test coverage: https://codecov.io/gh/pallets/markupsafe |