Simple, elegant HTML, XHTML and XML generation.
Constructing your HTML
----------------------
To construct HTML start with an instance of ``html.HTML()``. Add
tags by accessing the tag's attribute on that object. For example:
>>> from html import HTML
>>> h = HTML()
>>> h.p('Hello, world!')
>>> print h # or print(h) in python 3+
<p>Hello, world!</p>
You may supply a tag name and some text contents when creating a HTML
instance:
>>> h = HTML('html', 'text')
>>> print h
<html>text</html>
You may also append text content later using the tag's ``.text()`` method
or using augmented addition ``+=``. Any HTML-specific characters (``<>&"``)
in the text will be escaped for HTML safety as appropriate unless
``escape=False`` is passed. Each of the following examples uses a new
``HTML`` instance:
>>> p = h.p('hello world!\n')
>>> p.br
>>> p.text('more → text', escape=False)
>>> p += ' ... augmented'
>>> h.p
>>> print h
<p>hello, world!<br>more → text ... augmented</p>
<p>
Note also that the top-level ``HTML`` object adds newlines between tags by
default. Finally in the above you'll see an empty paragraph tag - tags with
no contents get no closing tag.
If the tag should have sub-tags you have two options. You may either add
the sub-tags directly on the tag:
>>> l = h.ol
>>> l.li('item 1')
>>> l.li.b('item 2 > 1')
>>> print h
<ol>
<li>item 1</li>
<li><b>item 2 > 1</b></li>
</ol>
Note that the default behavior with lists (and tables) is to add newlines
between sub-tags to generate a nicer output. You can also see in that
example the chaining of tags in ``l.li.b``.
Tag attributes may be passed in as well:
>>> t = h.table(border='1')
>>> for i in range(2):
>>> r = t.tr
>>> r.td('column 1')
>>> r.td('column 2')
>>> print t
<table border="1">
<tr><td>column 1</td><td>column 2</td></tr>
<tr><td>column 1</td><td>column 2</td></tr>
</table>
A variation on the above is to use a tag as a context variable. The
following is functionally identical to the first list construction but
with a slightly different sytax emphasising the HTML structure:
>>> with h.ol as l:
... l.li('item 1')
... l.li.b('item 2 > 1')
You may turn off/on adding newlines by passing ``newlines=False`` or
``True`` to the tag (or ``HTML`` instance) at creation time:
>>> l = h.ol(newlines=False)
>>> l.li('item 1')
>>> l.li('item 2')
>>> print h
<ol><li>item 1</li><li>item 2</li></ol>
Since we can't use ``class`` as a keyword, the library recognises ``klass``
as a substitute:
>>> print h.p(content, klass="styled")
<p class="styled">content</p>
Unicode
-------
``HTML`` will work with either regular strings **or** unicode strings, but
not **both at the same time**.
Obtain the final unicode string by calling ``unicode()`` on the ``HTML``
instance:
>>> h = HTML()
>>> h.p(u'Some Euro: €1.14')
>>> unicode(h)
u'<p>Some Euro: €1.14</p>'
If (under Python 2.x) you add non-unicode strings or attempt to get the
resultant HTML source through any means other than ``unicode()`` then you
will most likely get one of the following errors raised:
UnicodeDecodeError
Probably means you've added non-unicode strings to your HTML.
UnicodeEncodeError
Probably means you're trying to get the resultant HTML using ``print``
or ``str()`` (or ``%s``).
How generation works
--------------------
The HTML document is generated when the ``HTML`` instance is "stringified".
This could be done either by invoking ``str()`` on it, or just printing it.
It may also be returned directly as the "iterable content" from a WSGI app
function.
You may also render any tag or sub-tag at any time by stringifying it.
Tags with no contents (either text or sub-tags) will have no closing tag.
There is no "special list" of tags that must always have closing tags, so
if you need to force a closing tag you'll need to provide some content,
even if it's just a single space character.
Rendering doesn't affect the HTML document's state, so you can add to or
otherwise manipulate the HTML after you've stringified it.
Creating XHTML
--------------
To construct XHTML start with an instance of ``html.XHTML()`` and use it
as you would an ``HTML`` instance. Empty elements will now be rendered
with the appropriate XHTML minimized tag syntax. For example:
>>> from html import XHTML
>>> h = XHTML()
>>> h.p
>>> h.br
>>> print h
<p></p>
<br />
Creating XML
------------
A slight tweak to the ``html.XHTML()`` implementation allows us to generate
arbitrary XML using ``html.XML()``:
>>> from html import XML
>>> h = XML('xml')
>>> h.p
>>> h.br('hi there')
>>> print h
<xml>
<p />
<br>hi there</br>
</xml>
Tags with difficult names
-------------------------
If your tag name isn't a valid Python identifier name, or if it's called
"text" or "raw_text" you can add your tag slightly more manually:
>>> from html import XML
>>> h = XML('xml')
>>> h += XML('some-tag', 'some text')
>>> h += XML('text', 'some text')
>>> print h
<xml>
<some-tag>some text</some-tag>
<text>some text</text>
</xml>
Version History (in Brief)
--------------------------
- 1.16 detect and raise a more useful error when some WSGI frameworks
attempt to call HTML.read(). Also added ability to add new content using
the += operator.
- 1.15 fix Python 3 compatibility (unit tests)
- 1.14 added plain XML support
- 1.13 allow adding (X)HTML instances (tags) as new document content
- 1.12 fix handling of XHTML empty tags when generating unicode
output (thanks Carsten Eggers)
- 1.11 remove setuptools dependency
- 1.10 support plain ol' distutils again
- 1.9 added unicode support for Python 2.x
- 1.8 added Python 3 compatibility
- 1.7 added Python 2.5 compatibility and escape argument to tag
construction
- 1.6 added .raw_text() and and WSGI compatibility
- 1.5 added XHTML support
- 1.3 added more documentation, more tests
- 1.2 added special-case klass / class attribute
- 1.1 added escaping control
- 1.0 was the initial release
----
I would be interested to know whether this module is useful - if you use it
please indicate so at https://www.ohloh.net/p/pyhtml
This code is copyright 2009-2011 eKit.com Inc (http://www.ekit.com/)
See the end of the source file for the license of use.
XHTML support was contributed by Michael Haubenwallner.
Raw data
{
"_id": null,
"home_page": "http://pypi.python.org/pypi/html",
"name": "html",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Richard Jones",
"author_email": "rjones@ekit-inc.com",
"download_url": "https://files.pythonhosted.org/packages/4a/df/0e3d22d50ee43274eb5116f49972a164d853bb3ab305a69a0540b6292252/html-1.16.tar.gz",
"platform": "UNKNOWN",
"description": "Simple, elegant HTML, XHTML and XML generation.\n\nConstructing your HTML\n----------------------\n\nTo construct HTML start with an instance of ``html.HTML()``. Add\ntags by accessing the tag's attribute on that object. For example:\n\n>>> from html import HTML\n>>> h = HTML()\n>>> h.p('Hello, world!')\n>>> print h # or print(h) in python 3+\n<p>Hello, world!</p>\n\nYou may supply a tag name and some text contents when creating a HTML\ninstance:\n\n>>> h = HTML('html', 'text')\n>>> print h\n<html>text</html>\n\nYou may also append text content later using the tag's ``.text()`` method\nor using augmented addition ``+=``. Any HTML-specific characters (``<>&\"``)\nin the text will be escaped for HTML safety as appropriate unless\n``escape=False`` is passed. Each of the following examples uses a new\n``HTML`` instance:\n\n>>> p = h.p('hello world!\\n')\n>>> p.br\n>>> p.text('more → text', escape=False)\n>>> p += ' ... augmented'\n>>> h.p\n>>> print h\n<p>hello, world!<br>more → text ... augmented</p>\n<p>\n\nNote also that the top-level ``HTML`` object adds newlines between tags by\ndefault. Finally in the above you'll see an empty paragraph tag - tags with\nno contents get no closing tag.\n\nIf the tag should have sub-tags you have two options. You may either add\nthe sub-tags directly on the tag:\n\n>>> l = h.ol\n>>> l.li('item 1')\n>>> l.li.b('item 2 > 1')\n>>> print h\n<ol>\n<li>item 1</li>\n<li><b>item 2 > 1</b></li>\n</ol>\n\nNote that the default behavior with lists (and tables) is to add newlines\nbetween sub-tags to generate a nicer output. You can also see in that\nexample the chaining of tags in ``l.li.b``.\n\nTag attributes may be passed in as well:\n\n>>> t = h.table(border='1')\n>>> for i in range(2):\n>>> r = t.tr\n>>> r.td('column 1')\n>>> r.td('column 2')\n>>> print t\n<table border=\"1\">\n<tr><td>column 1</td><td>column 2</td></tr>\n<tr><td>column 1</td><td>column 2</td></tr>\n</table>\n\nA variation on the above is to use a tag as a context variable. The\nfollowing is functionally identical to the first list construction but\nwith a slightly different sytax emphasising the HTML structure:\n\n>>> with h.ol as l:\n... l.li('item 1')\n... l.li.b('item 2 > 1')\n\nYou may turn off/on adding newlines by passing ``newlines=False`` or\n``True`` to the tag (or ``HTML`` instance) at creation time:\n\n>>> l = h.ol(newlines=False)\n>>> l.li('item 1')\n>>> l.li('item 2')\n>>> print h\n<ol><li>item 1</li><li>item 2</li></ol>\n\nSince we can't use ``class`` as a keyword, the library recognises ``klass``\nas a substitute:\n\n>>> print h.p(content, klass=\"styled\")\n<p class=\"styled\">content</p>\n\n\nUnicode\n-------\n\n``HTML`` will work with either regular strings **or** unicode strings, but\nnot **both at the same time**.\n\nObtain the final unicode string by calling ``unicode()`` on the ``HTML``\ninstance:\n\n>>> h = HTML()\n>>> h.p(u'Some Euro: \u20ac1.14')\n>>> unicode(h)\nu'<p>Some Euro: \u20ac1.14</p>'\n\nIf (under Python 2.x) you add non-unicode strings or attempt to get the\nresultant HTML source through any means other than ``unicode()`` then you\nwill most likely get one of the following errors raised:\n\nUnicodeDecodeError\n Probably means you've added non-unicode strings to your HTML.\nUnicodeEncodeError\n Probably means you're trying to get the resultant HTML using ``print``\n or ``str()`` (or ``%s``).\n\n\nHow generation works\n--------------------\n\nThe HTML document is generated when the ``HTML`` instance is \"stringified\".\nThis could be done either by invoking ``str()`` on it, or just printing it.\nIt may also be returned directly as the \"iterable content\" from a WSGI app\nfunction.\n\nYou may also render any tag or sub-tag at any time by stringifying it.\n\nTags with no contents (either text or sub-tags) will have no closing tag.\nThere is no \"special list\" of tags that must always have closing tags, so\nif you need to force a closing tag you'll need to provide some content,\neven if it's just a single space character.\n\nRendering doesn't affect the HTML document's state, so you can add to or\notherwise manipulate the HTML after you've stringified it.\n\n\nCreating XHTML\n--------------\n\nTo construct XHTML start with an instance of ``html.XHTML()`` and use it\nas you would an ``HTML`` instance. Empty elements will now be rendered\nwith the appropriate XHTML minimized tag syntax. For example:\n\n>>> from html import XHTML\n>>> h = XHTML()\n>>> h.p\n>>> h.br\n>>> print h\n<p></p>\n<br />\n\n\nCreating XML\n------------\n\nA slight tweak to the ``html.XHTML()`` implementation allows us to generate\narbitrary XML using ``html.XML()``:\n\n>>> from html import XML\n>>> h = XML('xml')\n>>> h.p\n>>> h.br('hi there')\n>>> print h\n<xml>\n<p />\n<br>hi there</br>\n</xml>\n\n\nTags with difficult names\n-------------------------\n\nIf your tag name isn't a valid Python identifier name, or if it's called\n\"text\" or \"raw_text\" you can add your tag slightly more manually:\n\n>>> from html import XML\n>>> h = XML('xml')\n>>> h += XML('some-tag', 'some text')\n>>> h += XML('text', 'some text')\n>>> print h\n<xml>\n<some-tag>some text</some-tag>\n<text>some text</text>\n</xml>\n\n\nVersion History (in Brief)\n--------------------------\n\n- 1.16 detect and raise a more useful error when some WSGI frameworks\n attempt to call HTML.read(). Also added ability to add new content using\n the += operator.\n- 1.15 fix Python 3 compatibility (unit tests)\n- 1.14 added plain XML support\n- 1.13 allow adding (X)HTML instances (tags) as new document content\n- 1.12 fix handling of XHTML empty tags when generating unicode\n output (thanks Carsten Eggers)\n- 1.11 remove setuptools dependency\n- 1.10 support plain ol' distutils again\n- 1.9 added unicode support for Python 2.x\n- 1.8 added Python 3 compatibility\n- 1.7 added Python 2.5 compatibility and escape argument to tag\n construction\n- 1.6 added .raw_text() and and WSGI compatibility\n- 1.5 added XHTML support\n- 1.3 added more documentation, more tests\n- 1.2 added special-case klass / class attribute\n- 1.1 added escaping control\n- 1.0 was the initial release\n\n----\n\nI would be interested to know whether this module is useful - if you use it\nplease indicate so at https://www.ohloh.net/p/pyhtml\n\nThis code is copyright 2009-2011 eKit.com Inc (http://www.ekit.com/)\nSee the end of the source file for the license of use.\nXHTML support was contributed by Michael Haubenwallner.",
"bugtrack_url": null,
"license": "UNKNOWN",
"summary": "simple, elegant HTML, XHTML and XML generation",
"version": "1.16",
"project_urls": {
"Download": "UNKNOWN",
"Homepage": "http://pypi.python.org/pypi/html"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4adf0e3d22d50ee43274eb5116f49972a164d853bb3ab305a69a0540b6292252",
"md5": "39b9db7cdcc84607828be021172d441f",
"sha256": "ebc768f23b54a71350d731a75f2ef3a4a4dbdad9ae68d58b527664b66088e456"
},
"downloads": -1,
"filename": "html-1.16.tar.gz",
"has_sig": false,
"md5_digest": "39b9db7cdcc84607828be021172d441f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7639,
"upload_time": "2011-06-29T11:29:33",
"upload_time_iso_8601": "2011-06-29T11:29:33.276795Z",
"url": "https://files.pythonhosted.org/packages/4a/df/0e3d22d50ee43274eb5116f49972a164d853bb3ab305a69a0540b6292252/html-1.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2011-06-29 11:29:33",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "html"
}
JSON