skip to navigation
skip to content

Not Logged In

htmltag 1.7

Python HTML tag interface

Package Documentation

The htmltag module
==================
.. note::

The latest, complete documentation of htmltag can be found here:
http://liftoff.github.io/htmltag/

The latest version of this module can be obtained from Github:
https://github.com/LiftoffSoftware/htmltag

htmltag.py - A Python (2 *and* 3) module for wrapping whatever strings you want
in HTML tags. Example::

>>> from htmltag import strong
>>> print(strong("SO STRONG!"))
SO STRONG!

What tags are supported? All of them! An important facet of modern web
programming is the ability to use your own custom tags. For example::

>>> from htmltag import foobar
>>> foobar('Custom tag example')
'<foobar>Custom tag example</foobar>'

To add attributes inside your tag just pass them as keyword arguments::

>>> from htmltag import a
>>> print(a('awesome software', href='http://liftoffsoftware.com/'))
awesome software

To work around the problem of reserved words as keyword arguments (i.e. can't
have 'class="foo"') just prefix the keyword with an underscore like so::

>>> from htmltag import div
>>> print(div("example", _class="someclass"))
example


Another option--which is useful for things like 'data-\*' attributes--is to pass
keyword arguments as a dict using the `\*\* operator
<http: docs.python.org="" 2="" tutorial="" controlflow.html#unpacking-argument-lists="">`_
like so::

>>> from htmltag import li
>>> print(li("CEO", **{"class": "user", "data-name": "Dan McDougall"}))
  • CEO


  • If you want to use upper-case tags just import them in caps:

    >>> from htmltag import STRONG
    >>> print(STRONG('whatever'))
    whatever

    Combining Tags and Content
    --------------------------
    You can combine multiple tags to create a larger HTML string like so::

    >>> from htmltag import table, tr, td
    >>> print(table(
    ... tr(td('100'), td('200'), id="row1"),
    ... tr(td('150'), td('250'), id="row2"),
    ... ))
    100200
    150250


    **NOTE:** If you're going to do something like the above please use a *real*
    template language/module instead of `htmltag`. You're *probably* "doing it
    wrong" if you end up with something like the above in your code. For example,
    try `Tornado's template engine
    <http: www.tornadoweb.org="" en="" stable="" template.html="">`_.

    Special Characters
    ------------------
    Special characters that cause trouble like, '<', '>', and '&' will be
    automatically converted into HTML entities. If you don't want that to happen
    just wrap your string in :class:`htmltag.HTML` like so::

    >>> from htmltag import HTML, a
    >>> txt = HTML("I am already HTML. Don't escape me!")
    >>> a(txt, href="http://liftoffsoftware.com/")
    'I am already HTML. Don\'t escape me!'

    Since Python doesn't allow modules to have dashes (-) in their names, if you
    need to create a tag like that just use an underscore and change its 'tagname'
    attribute::

    >>> from htmltag import foo_bar
    >>> print(foo_bar('baz')) # Before
    '<foo_bar>baz</foo_bar>'
    >>> foo_bar.tagname = 'foo-bar'
    >>> print(foo_bar('baz')) # Before
    '<foo-bar>baz</foo-bar>'

    By default self-closing HTML tags like '' will not include an ending slash.
    To change this behavior (i.e. for XHTML) just set 'ending_slash' to `True`::

    >>> from htmltag import img
    >>> img.ending_slash = True
    >>> img(src="http://somehost/images/image.png")
    ''
    >>> img.ending_slash = False # Reset for later doctests

    Protections Against Cross-Site Scripting (XSS)
    ----------------------------------------------
    By default all unsafe (XSS) content in HTML tags will be removed::

    >>> from htmltag import a, img
    >>> a(img(src="javascript:alert('pwned!')"), href="http://hacker/")
    '(removed)'

    If you want to change this behavior set the tag's 'safe_mode' attribute like
    so::

    >>> from htmltag import a, img
    >>> a.safe_mode = False
    >>> img.safe_mode = False
    >>> a(img(src="javascript:alert('pwned!')"), href="http://hacker/")
    ''
    >>> a.safe_mode = True # Reset for later doctests
    >>> img.safe_mode = True # Ditto

    You may also change the replacement text if you like::

    >>> from htmltag import a, img
    >>> img.replacement = "No no no!"
    >>> a(img(src="javascript:alert('pwned!')"), href="http://hacker/")
    'No no no!'

    If you set 'replacement' to 'entities' the rejected HTML will be converted to
    character entities like so::

    >>> from htmltag import a, img
    >>> a.replacement = "entities"
    >>> img.replacement = "entities"
    >>> a(img(src="javascript:alert('pwned!')"), href="http://hacker/")
    ''

    It is also possible to create a whitelist of allowed tags. All other tags
    contained therein will automatically be replaced::

    >>> from htmltag import span
    >>> whitelist = ['span', 'b', 'i', 'strong']
    >>> span.whitelist = whitelist
    >>> span(HTML('This is bold new lib is <script>awesome();</script>'))
    'This is bold new lib is (removed)awesome();(removed)'

    Lastly, all strings returned by `htmltag` are actually a subclass of `str`:
    `~htmltag.HTML`. It has a useful `escaped` property:

    >>> from htmltag import address
    >>> address.safe_mode = False # Turn off so we have a dangerous example ;)
    >>> html = address('1 Hacker Ln., Nowhere, USA')
    >>> print(html)
    <address>1 Hacker Ln., Nowhere, USA</address>
    >>> print(html.escaped)
    <address>1 Hacker Ln., Nowhere, USA</address>

    This can be extremely useful if you want to be double-sure that no executable
    stuff ends up in your program's output.


    Functions and Classes
    =====================  
    File Type Py Version Uploaded on Size
    htmltag-1.7.tar.gz (md5) Source 2014-08-07 12KB
    • Downloads (All Versions):
    • 4 downloads in the last day
    • 29 downloads in the last week
    • 140 downloads in the last month