https://github.com/LiftoffSoftware/htmltag

A Python (2 *and* 3) module for wrapping whatever strings you want in HTML tags.
https://github.com/LiftoffSoftware/htmltag

Last synced: 5 months ago
JSON representation

A Python (2 *and* 3) module for wrapping whatever strings you want in HTML tags.

• Host: GitHub
• URL: https://github.com/LiftoffSoftware/htmltag
• Owner: LiftoffSoftware
• License: apache-2.0
• Created: 2013-04-12T20:35:57.000Z (about 12 years ago)
• Default Branch: master
• Last Pushed: 2019-07-26T02:52:59.000Z (over 5 years ago)
• Last Synced: 2024-11-06T14:46:00.387Z (5 months ago)
• Language: Python
• Size: 3.63 MB
• Stars: 22
• Watchers: 6
• Forks: 4
• Open Issues: 2
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE.txt

Awesome Lists containing this project

• awesome-python-html - LiftoffSoftware/htmltag
• awesome-python-html - LiftoffSoftware/htmltag

README

        
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')

    'Custom tag example'

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

`_

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"),

    ... ))

    100200150250

**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

`_.

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

    'baz'

    >>> foo_bar.tagname = 'foo-bar'

    >>> print(foo_bar('baz')) # Before

    'baz'

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/")

    '<img src="javascript:alert(\'pwned!\')">'

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 awesome();'))

    '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)

    
1 Hacker Ln., Nowhere, USA

    >>> 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

=====================