htmldoom 0.6.6

An intuitive, high performance HTML rendering framework

htmldoom

An intuitive, high performance HTML rendering framework

    

Usage

A basic tag

>>> from htmldoom import render, elements as e
>>> 
>>> print(render(
...     e.textarea("required", class_="input")("text")
... ))
<textarea required class="input">text</textarea>

A custom tag

>>> from htmldoom import render, composite_tag
>>> 
>>> clipboard_copy = composite_tag("clipboard-copy")
>>> print(render(clipboard_copy(value="foo")("Copy Me")))
<clipboard-copy value="foo">Copy Me</clipboard-copy>

A fast dynamic elements rendering mechanism

Choose whichever syntax suits you:

Syntax 1

>>> from htmldoom import renders, elements as e
>>> 
>>> @renders(
...     e.p()("{x}"),
...     e.p()("another {x}"),
... )
... def render_paras(data: dict) -> dict:
...     return {"x": data["x"]}
>>> 
>>> render_paras({"x": "awesome paragraph"})
<p>awesome paragraph</p><p>another awesome paragraph</p>

Syntax 2

>>> from htmldoom import renders, elements as e
>>> 
>>> render_paras = renders(
...     e.p()("{x}"),
...     e.p()("another {x}"),
... )(lambda data: {"x": data["x"]})
>>> 
>>> render_paras({"x": "awesome paragraph"})
<p>awesome paragraph</p><p>another awesome paragraph</p>

NOTE: This mechanism compiles the template when the file loads and reuse it.

renders( ...compile-time code... )( ...runtime code... )

The more execution you move from runtime to compile-time, the faster it gets.
If you properly use this mechanism and refractor your dynamic pages into smaller components, it might surpass the performance of traditional template rendering engines.

WARNING: It performs a "{rendered_elements}".format(**returned_data). So each `{` or `}` in the compile-time code needs to be escaped with `{{` or `}}`.

A functional style foreach loop with a switch case (probably useless)

>>> from htmldoom import elements as e
>>> from htmldoom import functions as fn
>>> 
>>> tuple(fn.foreach(["good", "bad", "evil"])(
...     lambda x: fn.switch({
...         x == "good": lambda: e.span(style="color: green")(f"this is {x}"),
...         x == "bad": lambda: e.span(style="color: yellow")(f"this is {x}"),
...         x == "evil": lambda: e.span(style="color: red")(f"this is {x}"),
...         fn.Case.DEFAULT: lambda: fn.Error.throw(ValueError(x)),
...     })
... ))
(b'<span style="color: green">this is good</span>',
 b'<span style="color: yellow">this is bad</span>',
 b'<span style="color: red">this is evil</span>')

Find more examples here

Q/A

What is the goal here?

The primary goal is to make writing dynamic HTML pages cleaner, easier, safer and intuitive in Python.

What about performance?

Although performance is not the primary goal here, it should not be a roadblock. htmldoom uses pure functions with hashable input parameters as elements. Hence, it makes effective use of caching internally. It also offers a friendly mechanism to pre-render the static parts of the page using the @renders decorator when it compiles to bytecode.
Also since it helps you (probably forces you) to refactor the webpage into multiple render functions, you are free to use whatever optimisation you prefer. Try putting an @lru_cache in a render function?

Is there any benchmark?

Refer to the benchmarks here.

Plugins and ecosystem

• moodlmth: Convert raw HTML pages into python source code

• Flask-Htmldoom: htmldoom integration for Flask

• pyramid_htmldoom: htmldoom rendering library plugin for Pyramid

Contributing

Check out the contributing guidelines.

NOTE: This file was generated using this script.