Metadata-Version: 2.1
Name: artless-template
Version: 0.1.0
Summary: Artless and small template library for server-side rendering.
Author-email: Peter Bro <p3t3rbr0@gmail.com>
Project-URL: Homepage, https://github.com/p3t3rbr0/py3-artless-template
Project-URL: Documentation, https://github.com/p3t3rbr0/py3-artless-template/blob/master/README.md
Project-URL: Repository, https://github.com/p3t3rbr0/py3-artless-template.git
Project-URL: Issues, https://github.com/p3t3rbr0/py3-artless-template/issues
Project-URL: Changelog, https://github.com/p3t3rbr0/py3-artless-template/blob/master/CHANGELOG.md
Keywords: artless-template,template engine,text processing,utility
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: benchmarks
Requires-Dist: Django ==5.0.6 ; extra == 'benchmarks'
Requires-Dist: Jinja2 ==3.1.4 ; extra == 'benchmarks'
Requires-Dist: Mako ==1.3.5 ; extra == 'benchmarks'
Provides-Extra: build
Requires-Dist: build ==1.2.1 ; extra == 'build'
Requires-Dist: twine ==5.0.0 ; extra == 'build'
Provides-Extra: dev
Requires-Dist: coverage ==7.5.1 ; extra == 'dev'
Requires-Dist: mypy ==1.10.0 ; extra == 'dev'
Requires-Dist: isort ==5.13.2 ; extra == 'dev'
Requires-Dist: flake8 ==7.0.0 ; extra == 'dev'
Requires-Dist: black ==24.4.2 ; extra == 'dev'
Requires-Dist: pydocstyle ==6.3.0 ; extra == 'dev'

# artless-template

Artless and small template library for server-side rendering.

Artless-template allows to generate HTML, using template files or/and natively Python objects. The library encourages approaches like HTMX and No-JS.

**Features**:
* Small and simple code base (less than 200 LOC).
* No third party dependencies (standart library only).

**Table of Contents**:
* [Install](#install)
* [Usage](#usage)
  * [Template and tags usage](#usage-tags)
  * [Template and components usage](#usage-components)
* [Performance](#performance)

<a id="install"></a>
## Install

``` shellsession
$ pip install artless-template
```

<a id="usage"></a>
## Usage

Basically, you can create any tag with any name, attributes, text and child tags:

``` python
from artless_template import Tag as t

div = t("div")
print(div)
<div></div>

div = t("div", {"class": "some-class"}, "Some text")
print(div)
<div class="some-class">Some text</div>

div = t("div", {"class": "some-class"}, "Div text", [t(span, None, "Span 1 text"), t(span, None, "Span 2 text")])
print(div)
<div class="some-class"><span>Span 1 text</span><span>Span 2 text</span>Div text</div>

button = t("button", {"onclick": "function() {alert('hello');}"}, "Say Hello")
print(button)
<button onclick="function() {alert('hello');}">Say Hello</button>
```

<a id="usage-tags"></a>
### Template and tags usage

Create `templates/index.html` with contents:

``` html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>$(title)</title>
  </head>
  <body>
    <main>
        <section>
            <h1>$(header)</h1>
            <table>
                <thead>
                    <tr>
                        <th>Name</th>
                        <th>Email</th>
                        <th>Admin</th>
                    </tr>
                </thead>
                $(users)
            </table>
        </section>
    </main>
  </body>
</html>
```

``` python
from typing import final
from pathlib import Path
from random import randint
from dataclasses import dataclass
from artless_template import read_template, Tag as t

TEMPLATES_DIR: Path = Path(__file__).resolve().parent / "templates"

@final
@dataclass(frozen=True, slots=True, kw_only=True)
class UserModel:
    name: str
    email: str
    is_admin: bool


users = [
    UserModel(
        name=f"User_{_}", email=f"user_{_}@gmail.com", is_admin=bool(randint(0, 1))
    )
    for _ in range(10_000)
]


users_markup = t(
    "tbody",
    None,
    None,
    [
        t(
            "tr",
            None,
            None,
            [
                t("td", None, user.name),
                t("td", None, user.email),
                t("td", None, "+" if user.is_admin else "-"),
            ],
        )
        for user in users
    ],
)

context = {
    "title": "Artless-template example",
    "header": "Users list",
    "users": users_markup,
}

template = read_template(TEMPLATES_DIR / "index.html").render(context)
```

<a id="usage-components"></a>
### Template and components usage

``` html
<!DOCTYPE html>
<html lang="en">
  ...
  <body>
    <main>
      $(main)
    </main>
  </body>
</html>
```

``` python
from artless_template import read_template, Component, Tag as t

...

class UsersTableComponent:
    def __init__(self, count: int):
        self.users = [
            UserModel(
                name=f"User_{_}", email=f"user_{_}@gmail.com", is_admin=bool(randint(0, 1))
            )
            for _ in range(count)
        ]

    def view(self):
        return t(
            "table",
            None,
            None,
            [
                t(
                    "thead",
                    None,
                    None,
                    [
                        t(
                            "tr",
                            None,
                            None,
                            [
                                t("th", None, "Name"),
                                t("th", None, "Email"),
                                t("th", None, "Admin"),
                            ]
                        )
                    ]
                ),
                t(
                    "tbody",
                    None,
                    None,
                    [
                        t(
                            "tr",
                            None,
                            None,
                            [
                                t("td", None, user.name),
                                t("td", None, user.email),
                                t("td", None, "+" if user.is_admin else "-"),
                            ],
                        )
                        for user in self.users
                    ]
                )
            ]
        )

template = read_template(TEMPLATES_DIR / "index.html").render(main=UsersTableComponent(100500))
```

<a id="performance"></a>
## Performance

Performance comparison of the most popular template engines and artless-template library.
The benchmark render a HTML document with table of 10 thousand user models.

Run benchmark:

``` shellsession
$ python -m bemchmarks
```

Sorted results on i5 laptop (smaller is better):

``` python
{'mako': 0.011, 'jinja': 0.035, 'artless': 0.048, 'dtl': 0.158}
```

1. [Mako](https://www.makotemplates.org/) (0.011 sec.)
2. [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/) (0.035 sec.)
3. **Artless-template (0.048 sec.)**
4. [Django templates](https://docs.djangoproject.com/en/5.0/ref/templates/) (0.158 sec.)

The performance of `artless-template` is better than the `Django template engine`, but worse than `Jinja2` and `Mako`.
