third_party/python/MarkupSafe/README.rst

   1 MarkupSafe
   2 ==========
   3
   4 MarkupSafe implements a text object that escapes characters so it is
   5 safe to use in HTML and XML. Characters that have special meanings are
   6 replaced so that they display as the actual characters. This mitigates
   7 injection attacks, meaning untrusted user input can safely be displayed
   8 on a page.
   9
  10
  11 Installing
  12 ----------
  13
  14 Install and update using `pip`_:
  15
  16 .. code-block:: text
  17
  18     pip install -U MarkupSafe
  19
  20 .. _pip: https://pip.pypa.io/en/stable/quickstart/
  21
  22
  23 Examples
  24 --------
  25
  26 .. code-block:: pycon
  27
  28     >>> from markupsafe import Markup, escape
  29
  30     >>> # escape replaces special characters and wraps in Markup
  31     >>> escape("<script>alert(document.cookie);</script>")
  32     Markup('&lt;script&gt;alert(document.cookie);&lt;/script&gt;')
  33
  34     >>> # wrap in Markup to mark text "safe" and prevent escaping
  35     >>> Markup("<strong>Hello</strong>")
  36     Markup('<strong>hello</strong>')
  37
  38     >>> escape(Markup("<strong>Hello</strong>"))
  39     Markup('<strong>hello</strong>')
  40
  41     >>> # Markup is a str subclass
  42     >>> # methods and operators escape their arguments
  43     >>> template = Markup("Hello <em>{name}</em>")
  44     >>> template.format(name='"World"')
  45     Markup('Hello <em>&#34;World&#34;</em>')
  46
  47
  48 Donate
  49 ------
  50
  51 The Pallets organization develops and supports MarkupSafe and other
  52 popular packages. In order to grow the community of contributors and
  53 users, and allow the maintainers to devote more time to the projects,
  54 `please donate today`_.
  55
  56 .. _please donate today: https://palletsprojects.com/donate
  57
  58
  59 Links
  60 -----
  61
  62 -   Documentation: https://markupsafe.palletsprojects.com/
  63 -   Changes: https://markupsafe.palletsprojects.com/changes/
  64 -   PyPI Releases: https://pypi.org/project/MarkupSafe/
  65 -   Source Code: https://github.com/pallets/markupsafe/
  66 -   Issue Tracker: https://github.com/pallets/markupsafe/issues/
  67 -   Website: https://palletsprojects.com/p/markupsafe/
  68 -   Twitter: https://twitter.com/PalletsTeam
  69 -   Chat: https://discord.gg/pallets