Skip to main content

katagami: a simple xml/html template library

Project description

This library is one of many Python templating libraries.

Features

Example

Setup:

>>> def _(html, encoding='utf-8'):
...     print(render(io.BytesIO(html)).decode(encoding))

Make a HTML string with inline expression and Python’s for (Block structure):

>>> _(b'''<html>
... <body>
...     <? for name in ['world']: {?>
...         <p>hello, <?=name?></p>
...     <?}?>
... </body>
... </html>''')
<html>
<body>
<BLANKLINE>
        <p>hello, world</p>
<BLANKLINE>
</body>
</html>

Inline expression

This feature evaluates your inline expression and output to result:

>>> _(b'''<html><body>
...     <?='hello, world'?>
... </body></html>''')
<html><body>
    hello, world
</body></html>

By the default, this example raises an exception, evaluated expression must be str (unicode in Python 2):

>>> _(b'''<html><body>
...     <?=1?>
... </body></html>''')
Traceback (most recent call last):
...
TypeError: Can't convert 'int' object to str implicitly

Set the cast_string feature:

>>> _(b'''<html><body>
...     <?=feature cast_string="True"?>
...     <?=1?>
... </body></html>''')
<html><body>
<BLANKLINE>
    1
</body></html>

Also set the trap_exceptions feature:

>>> _(b'''<html><body>
...     <?=feature trap_exceptions="True"?>
...     <?=1?>
... </body></html>''')
<html><body>
<BLANKLINE>
    Can't convert 'int' object to str implicitly
</body></html>

Note

  • You can use cast_string and trap_exceptions simultaneously.
  • You can handle cast_string and trap_exceptions by defining the function __str__. By the default, __str__ is str in Python 3 (unicode in Python 2).
  • Spaces on the both sides of the expression will be stripped. But ‘<?= feature’ is a bad.
  • You can insert a comment.

Example:

>>> _(b'''<html><body>
... <?py
...     def __str__(o):
...         return '__str__(%s)' % o
... ?>
...     <?=feature cast_string="True" trap_exceptions="True"?>
...     <?= 1 ?>
...     <?= notfound # get an error ?>
... </body></html>''')
<html><body>
<BLANKLINE>
<BLANKLINE>
    __str__(1)
    __str__(name 'notfound' is not defined)
</body></html>

Embed script

All indentation will be arranged automatically:

>>> _(b'''<html>
... <?py
...     # It is a top level here. This works fine.
...     if 1:
...         msg = 'message from indented script'
... ?>
... <body>
...     <p><?=msg?></p>
...     <?py msg = 'message from single line script' # This works fine too. ?>
...     <p><?=msg?></p>
...     <? if 1: {?>
... <?py
... # Is is nested here. This also works fine.
... msg = 'message from nested indented script'
... ?>
...     <p><?=msg?></p>
...     <?}?>
... </body>
... </html>''')
<html>
<BLANKLINE>
<body>
    <p>message from indented script</p>
<BLANKLINE>
    <p>message from single line script</p>
<BLANKLINE>
<BLANKLINE>
    <p>message from nested indented script</p>
<BLANKLINE>
</body>
</html>

Block structure

Indentation with C-style block structure:

>>> _(b'''<html>
... <body>
...     <p>hello,&nbsp;
...     <? try: {?>
...         <?=name?>
...     <?} except NameError: {?>
...         NameError
...     <?} else: {?>
...         never output here
...     <?}?>
...     </p>
... </body>
... </html>''')
<html>
<body>
    <p>hello,&nbsp;
<BLANKLINE>
<BLANKLINE>
        NameError
<BLANKLINE>
    </p>
</body>
</html>

Note

  • ‘<? }’ and ‘{ ?>’ are wrong. Don’t insert space. ‘<?}’ and ‘{?>’ are correct.
  • Ending colon (‘:’) is required.
  • Block closing ‘<?}?>’ is required.

Encoding detection

Encoding will be detected automatically:

>>> _(b'''<html>
... <head><meta charset="shift-jis"></head>
... <body>\x93\xfa\x96{\x8c\xea</body>
... </html>''', 'shift-jis')
<html>
<head><meta charset="shift-jis"></head>
<body>\u65e5\u672c\u8a9e</body>
</html>

Supported formats:

  • <?xml encoding=”ENCODING”?>
  • <meta charset=”ENCODING”>
  • <meta http-equiv=”Content-Type” content=”MIMETYPE; ENCODING”>

API

katagami.render

katagami.render(__file__, __encoding__=None, **locals)

  • __file__file-like object (use io.BytesIO for string input) or filename.
  • __encoding__ – Set encoding of __file__ and the return value. Automatically detect the encoding if None.
  • locals – local and global namespace values for template script.
  • returnbytes in Python 3, str in Python 2. The return value is encoded by __encoding__ or automatically detected encoding.

Rendering template flow:

  1. detect encoding
  2. decode to str in Python 3 (unicode in Python 2)
  3. translate template to Python script
  4. compile and exec the script
  5. encode result to bytes in Python 3 (str in Python 2)

History

  • 1.0.1 fix bugs, docs, speed
  • 1.0.0 remove backward compatibility

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for katagami, version 1.0.1
Filename, size File type Python version Upload date Hashes
Filename, size katagami-1.0.1.zip (7.7 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page