kemmering API

class kemmering.tag(tag, **attrs)

An XML tag.

tag is the name of the tag. Add a trailing forward slash (/) character to create a self-closing tag. attrs are the attributes for tag. The tag itself is callable. Call the tag to add children.

>>> from kemmering import tag
>>> str(tag('a', b='c')('d'))
'<a b="c">d</a>'
>>> str(tag('e/'))
'<e/>'

class kemmering.notag(*children)

Used to represent a set of sibling elements with no enclosing parent tag.

children is a sequence of elements.

notag is particularly useful with defer and any of the template helpers which are based on defer.

>>> from kemmering import notag, tag
>>> str(tag('a')(
...   tag('b/'),
...   notag(
...      tag('c/'),
...      tag('d/')
...   )
... ))
'<a><b/><c/><d/></a>'

class kemmering.defer(f)

Defer the realization of a part of a template until a later time.

Use of a deferred function in a snippet comprised of tag objects, turns that snippet into a template. That template is said to be realized when bind is called on the snippet, which generates a concrete snippet based on the template and a context passed in via bind.

f is a function with the signature:

def deferred(context):
    "Return a `tag`, `notag`, or string."

The function will be called at realization time when bind is called on the containing snippet and passed the context object. Most template helpers assume the context is a dictionary.

Instances of defer may be used as children of tag objects or as values of tag atrributes. When used as a child of a tag, the return value should be either another tag instance or a string for a text element. When used as an attribute value, the return value should be a string or None. Setting an attribute to None causes it to be omitted from the realized template.

Most use cases for defer are actually covered by more specific helpers based on defer, described below.

kemmering.bind(template, context)

Realize a template by binding it to a context.

template is a tag instance which should contain some instances of defer in its structure. context is the context object that is passed to deferred functions in the template. Most template helpers assume the context is a dictionary.

Returns new tag instance that is a copy of the template with any deferred elements replaced by the return values of their deferred functions.

Template Helpers

class kemmering.from_context(key, default=notag)

This specialization of defer simply returns a value from the bind context.

key is the name to look up in the bind context dictionary. Whatever is the value in the bind context is returned. If default is specified and key is not found in the bind context, default is returned instead.

>>> from kemmering import bind, from_context, tag
>>> template = tag('a')(from_context('b', 'c'))
>>> str(bind(template, {'b': 'd'}))
'<a>d</a>'
>>> str(bind(template, {}))
'<a>c</a>'

class kemmering.in_context(keys, default=notag)

This specialization of defer looks up a value in the bind context by traversing the context using a sequence of keys where the bind context is presumed to be a structure of nested dictionaries.

keys is a sequence of names to look up, in order, in the bind context. If default is specified and a value is not found in the bind context for the given keys, default is returned instead.

>>> from kemmering import bind, in_context, tag
>>> template = tag('a')(in_context(['b', 'c'], 'd'))
>>> str(bind(template, {'b': {'c': 'e'}}))
'<a>e</a>'
>>> str(bind(template, {}))
'<a>d</a>'

class kemmering.format_context(s)

This specialization of defer uses the bind context to perform Python string formatting on a format string.

s is the format string. The return value is the equivalent of s.format(**context).

>>> from kemmering import bind, format_context, tag
>>> template = tag('a')(format_context('{b} {c}'))
>>> str(bind(template, {'b': 'd', 'c': 'e'}))
'<a>d e</a>'

class kemmering.cond(condition, affirmative, negative=notag)

This specialization of defer conditionally includes an element based on the bind context.

condition is a function which accepts a single argument, context and returns a boolean. condition may optionally be a string, in which case it is used as a key for performing a dictionary lookup in the bind context, the value of which will be treated as a boolean.

affirmative is the return value if the condition is True. negative is the return value of the condition is False. If the condition is False and no negative value is given, this element is elided from the realized snippet.

>>> from kemmering import bind, cond, tag
>>> def has_b(context):
...     return 'b' in context
>>> template = tag('a')(cond(has_b, 'b'))
>>> str(bind(template, {'b': ''}))
'<a>b</a>'
>>> str(bind(template, {}))
'<a></a>'
>>> template = tag('a')(cond('b', 'c', 'd'))
>>> str(bind(template, {'b': True}))
'<a>c</a>'
>>> str(bind(template, {}))
'<a>d</a>'

class kemmering.loop(key, seq, template)

This specialization of defer repeats a snippet while iterating over a sequence.

key is the name of a key that will be added to the context on each iteration whose value is the current item in the sequence. This makes the current item available to deferred functions in the repeated snippet. key may optionally be a list or tuple of string key names, in which case the sequence values, which should be sequences of equal length, will be unpacked into those keys.

seq is a function which accepts a single argument, context, and returns an iterable sequence. Alternatively, seq can be the name of a key in the current context whose value is an iterable sequence.

template is the snippet to be repeated.

>>> from kemmering import bind, from_context, loop, tag
>>> def fruits(context):
...     return ['apple', 'pear', 'banana']
>>> template = tag('ul')(
...     loop('fruit', fruits, tag('li')(from_context('fruit'))))
>>> str(bind(template, {'fruit': 'hamburger'}))
'<ul><li>apple</li><li>pear</li><li>banana</li></ul>'
>>> template = tag('ul')(
...     loop('fruit', 'fruits', tag('li')(from_context('fruit'))))
>>> str(bind(template, {'fruits': ['apple', 'pear', 'banana']}))
'<ul><li>apple</li><li>pear</li><li>banana</li></ul>'

And an example which uses unpacking:

>>> from kemmering import cond
>>> from kemmering.html import pretty
>>> def fruits(context):
...     return enumerate(['apple', 'pear', 'banana'])
>>> def is_even(context):
...     return context['i'] % 2 == 0
>>> template = tag('ul')(
...     loop(('i', 'fruit'), fruits,
...         tag('li', class_=cond(is_even, 'even', 'odd'))(
...             from_context('fruit'))))
>>> print(pretty(bind(template, {})))
<ul>
  <li class="even">apple</li>
  <li class="odd">pear</li>
  <li class="even">banana</li>
</ul>

kemmering.html API

HTML tags

Reference: http://www.html-5-tutorial.com/all-html-tags.htm

class kemmering.html.doc(*children)

Top level HTML5 document, includes doctype declaration.

>>> from kemmering.html import doc, html
>>> print(doc(html()))
<!DOCTYPE html>

<html></html>

class kemmering.html.style(*args)

HTML tag <style></style>.

Each positional argument should be a tuple of (selector, style) where selector is the CSS selector and style is a dictionary containing the CSS styles for that selector. Calling the resulting object uses the same signature and adds those styles to this tag.

>>> from kemmering.html import style
>>> print(style(
...     ('a', {'b': 'c', }),
...     ('d', {'e': 'f'})))

<style>
  a {
    b: c;
  }
  d {
    e: f;
  }
</style>

kemmering.html.pretty(snippet)

Render a snippet of HTML as a string with line breaks and indentation. This is not necessarily a particularly fast implementation, but it can be useful for debugging.

>>> from kemmering import tag
>>> from kemmering.html import pretty
>>> print(pretty(tag('a')(tag('b')(tag('c/')))))
<a>
  <b>
    <c/>
  </b>
</a>

kemmering.html.a(**attrs)

HTML tag <a></a>

kemmering.html.abbr(**attrs)

HTML tag <abbr></abbr>

kemmering.html.address(**attrs)

HTML tag <address></address>

kemmering.html.area(**attrs)

HTML tag <area/>

kemmering.html.article(**attrs)

HTML tag <article></article>

kemmering.html.aside(**attrs)

HTML tag <aside></aside>

kemmering.html.audio(**attrs)

HTML tag <audio></audio>

kemmering.html.b(**attrs)

HTML tag <b></b>

kemmering.html.base(**attrs)

HTML tag <base/>

kemmering.html.bdi(**attrs)

HTML tag <bdi></bdi>

kemmering.html.bdo(**attrs)

HTML tag <bdo></bdo>

kemmering.html.blockquote(**attrs)

HTML tag <blockquote></blockquote>

kemmering.html.body(**attrs)

HTML tag <body></body>

kemmering.html.br(**attrs)

HTML tag <br/>

kemmering.html.button(**attrs)

HTML tag <button></button>

kemmering.html.canvas(**attrs)

HTML tag <canvas></canvas>

kemmering.html.caption(**attrs)

HTML tag <caption></caption>

kemmering.html.cite(**attrs)

HTML tag <cite></cite>

kemmering.html.code(**attrs)

HTML tag <code></code>

kemmering.html.col(**attrs)

HTML tag <col/>

kemmering.html.colgroup(**attrs)

HTML tag <colgroup></colgroup>

kemmering.html.datalist(**attrs)

HTML tag <datalist></datalist>

kemmering.html.dd(**attrs)

HTML tag <dd></dd>

kemmering.html.del_(**attrs)

HTML tag <del></del>

kemmering.html.details(**attrs)

HTML tag <details></details>

kemmering.html.dfn(**attrs)

HTML tag <dfn></dfn>

kemmering.html.div(**attrs)

HTML tag <div></div>

kemmering.html.dl(**attrs)

HTML tag <dl></dl>

kemmering.html.dt(**attrs)

HTML tag <dt></dt>

kemmering.html.em(**attrs)

HTML tag <em></em>

kemmering.html.embed(**attrs)

HTML tag <embed/>

kemmering.html.fieldset(**attrs)

HTML tag <fieldset></fieldset>

kemmering.html.figcaption(**attrs)

HTML tag <figcaption></figcaption>

kemmering.html.figure(**attrs)

HTML tag <figure></figure>

kemmering.html.footer(**attrs)

HTML tag <footer></footer>

kemmering.html.form(**attrs)

HTML tag <form></form>

kemmering.html.h1(**attrs)

HTML tag <h1></h1>

kemmering.html.h2(**attrs)

HTML tag <h2></h2>

kemmering.html.h3(**attrs)

HTML tag <h3></h3>

kemmering.html.h4(**attrs)

HTML tag <h4></h4>

kemmering.html.h5(**attrs)

HTML tag <h5></h5>

kemmering.html.h6(**attrs)

HTML tag <h6></h6>

kemmering.html.head(**attrs)

HTML tag <head></head>

kemmering.html.header(**attrs)

HTML tag <header></header>

kemmering.html.hgroup(**attrs)

HTML tag <hgroup></hgroup>

kemmering.html.hr(**attrs)

HTML tag <hr/>

kemmering.html.html(**attrs)

HTML tag <html></html>

kemmering.html.i(**attrs)

HTML tag <i></i>

kemmering.html.iframe(**attrs)

HTML tag <iframe></iframe>

kemmering.html.img(**attrs)

HTML tag <img/>

kemmering.html.input(**attrs)

HTML tag <input/>

kemmering.html.ins(**attrs)

HTML tag <ins></ins>

kemmering.html.kbd(**attrs)

HTML tag <kbd></kbd>

kemmering.html.keygen(**attrs)

HTML tag <keygen></keygen>

kemmering.html.label(**attrs)

HTML tag <label></label>

kemmering.html.legend(**attrs)

HTML tag <legend></legend>

kemmering.html.li(**attrs)

HTML tag <li></li>

kemmering.html.link(**attrs)

HTML tag <link/>

kemmering.html.map(**attrs)

HTML tag <map></map>

kemmering.html.mark(**attrs)

HTML tag <mark></mark>

kemmering.html.menu(**attrs)

HTML tag <menu></menu>

kemmering.html.meta(**attrs)

HTML tag <meta/>

kemmering.html.meter(**attrs)

HTML tag <meter></meter>

kemmering.html.nav(**attrs)

HTML tag <nav></nav>

kemmering.html.noscript(**attrs)

HTML tag <noscript></noscript>

kemmering.html.object(**attrs)

HTML tag <object></object>

kemmering.html.ol(**attrs)

HTML tag <ol></ol>

kemmering.html.optgroup(**attrs)

HTML tag <optgroup></optgroup>

kemmering.html.option(**attrs)

HTML tag <option></option>

kemmering.html.output(**attrs)

HTML tag <output></output>

kemmering.html.p(**attrs)

HTML tag <p></p>

kemmering.html.param(**attrs)

HTML tag <param/>

kemmering.html.pre(**attrs)

HTML tag <pre></pre>

kemmering.html.progress(**attrs)

HTML tag <progress></progress>

kemmering.html.q(**attrs)

HTML tag <q></q>

kemmering.html.rp(**attrs)

HTML tag <rp></rp>

kemmering.html.rt(**attrs)

HTML tag <rt></rt>

kemmering.html.ruby(**attrs)

HTML tag <ruby></ruby>

kemmering.html.s(**attrs)

HTML tag <s></s>

kemmering.html.samp(**attrs)

HTML tag <samp></samp>

kemmering.html.script(**attrs)

HTML tag <script></script>

kemmering.html.section(**attrs)

HTML tag <section></section>

kemmering.html.select(**attrs)

HTML tag <select></select>

kemmering.html.small(**attrs)

HTML tag <small></small>

kemmering.html.source(**attrs)

HTML tag <source/>

kemmering.html.span(**attrs)

HTML tag <span></span>

kemmering.html.strong(**attrs)

HTML tag <strong></strong>

kemmering.html.sub(**attrs)

HTML tag 

kemmering.html.summary(**attrs)

HTML tag <summary></summary>

kemmering.html.sup(**attrs)

HTML tag 

kemmering.html.table(**attrs)

HTML tag <table></table>

kemmering.html.tbody(**attrs)

HTML tag <tbody></tbody>

kemmering.html.td(**attrs)

HTML tag <td></td>

kemmering.html.textarea(**attrs)

HTML tag <textarea></textarea>

kemmering.html.tfoot(**attrs)

HTML tag <tfoot></tfoot>

kemmering.html.th(**attrs)

HTML tag <th></th>

kemmering.html.thead(**attrs)

HTML tag <thead></thead>

kemmering.html.time(**attrs)

HTML tag <time></time>

kemmering.html.title(**attrs)

HTML tag <title></title>

kemmering.html.tr(**attrs)

HTML tag <tr></tr>

kemmering.html.track(**attrs)

HTML tag <track/>

kemmering.html.u(**attrs)

HTML tag <u></u>

kemmering.html.ul(**attrs)

HTML tag <ul></ul>

kemmering.html.var(**attrs)

HTML tag <var></var>

kemmering.html.video(**attrs)

HTML tag <video></video>

kemmering.html.wbr(**attrs)

HTML tag <wbr></wbr>