Skip to main content

An intuitive, high performance HTML rendering framework

Project description

htmldoom

An intuitive, high performance HTML rendering framework

PyPI version PyPI version Build Status codecov Code style: black

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:

Python syntax

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

YAML Syntax

# path/to/components.yml
paras:
  awesome:
  - p:
    - - "{x}"
  - p:
    - - Another {x}
>>> from htmldoom import renders
>>> from htmldoom.yaml_loader import loadyaml as ly
>>> 
>>> @renders(ly("path/to/components.yml", "paras.awesome"))
... def render_paras(data):
...     return {"x": data["x"]}
... 
>>> print(render_paras({"x": "awesome paragraph &"}))
<p>awesome paragraph &amp;</p><p>another awesome paragraph &amp;</p>

HTML Syntax (using the raw file loader)

<!-- path/to/components.html -->
<p>{x}</p><p>another {x}</p>
>>> from htmldoom import renders, loadraw as lr
>>> 
>>> @renders(lr("path/to/components.html"))
... def render_paras(data):
...     return {"x": data["x"]}
... 
>>> print(render_paras({"x": "awesome paragraph &"}))
<p>awesome paragraph &amp;</p><p>another awesome paragraph &amp;</p>

NOTE: The code inside the `@renders` decorator is executed during the module load time. Hence it doesn't add and performance overhead at runtime.

renders( ...pre-rendered template... )( ...runtime rendering logic... )
The more elements you pre-render as template, the faster it gets at runtime.

WARNING: It performs a "{rendered_elements}".format(**returned_data). So each `{` or `}` in the pre-rendered template needs to be escaped with `{{` or `}}`. If you are using file loaders such as `loadraw()`, `loadtxt()`, `loadyaml()` etc, consider passing `static=True` in them to auto escape the curly braces.

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's been given a very high priority. 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 and reuse it.
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

Contributing

Check out the contributing guidelines.

NOTE: This file was generated using this script.

Project details


Download files

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

Source Distribution

htmldoom-0.8.0.tar.gz (12.8 kB view hashes)

Uploaded Source

Built Distribution

htmldoom-0.8.0-py3-none-any.whl (14.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page