Metadata-Version: 2.1
Name: simple-html
Version: 1.1.1
Summary: Template-less html rendering in Python
Home-page: https://github.com/keithasaurus/simple_html
License: MIT
Keywords: html,type hints
Author: Keith Philpott
Author-email: fakekeith@example.org
Requires-Python: >=3.8.1,<4.0.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Description-Content-Type: text/markdown

# simple_html

### Template-less. Type-safe. Minified by default. Fast.

simple_html allows you to create HTML in standard Python. Benefits include:
- typically faster than jinja2 -- up to 15x faster
- typically renders fewer bytes than template-based rendering
- types let your editor and tools help you write correct code faster
- lightweight and framework agnostic
- always renders valid html


### Installation
`pip install simple-html`


### Usage

```python
from simple_html import div, h1, render, p

node = div({},
           h1({"id": "hello"},
              "Hello World!"),
           p({},
             "hooray!"))

render(node)  
# <div><h1 id="hello">Hello World!</h1><p>hooray!</p></div> 
```

There are several ways to render nodes:
```python
from simple_html import br, div, h1, img, render

# raw node
render(br)
# <br/>

# node with attributes only
render(img({"src": "/some/image/url.jpg", "alt": "a great picture"}))
# <img src="/some/image/url.jpg" alt="a great picture"/>

# node with children
render(
    div({},
        h1({},
           "something"))
)
# <div><h1>something</h1></div>'
```

Tag attributes with `None` as the value will only render the attribute name:
```python
from simple_html import div, render

render(
    div({"empty-str-attribute": "", 
         "key-only-attr": None})
)
# <div empty-str-attribute="" key-only-attr></div>
```


Lists and generators are both valid collections of nodes:
```python
from typing import Generator
from simple_html import div, render, Node, br


def get_list_of_nodes() -> list[Node]:
    return ["neat", br]


render(div({}, get_list_of_nodes()))
# <div>neat<br/></div>


def node_generator() -> Generator[Node, None, None]:
    yield "neat"
    yield br


render(
    div({}, node_generator())
)
# <div>neat<br/></div>
```


For convenience, many tags are provided, but you can also create your own:

```python
from simple_html import Tag, render

custom_elem = Tag("custom-elem")

# works the same as any other tag
node = custom_elem(
    {"id": "some-custom-elem-id"},
    "Wow"
)

render(node)  # <custom-elem id="some-custom-elem-id">Wow</custom-elem>
```


Strings are escaped by default, but you can pass in `SafeString`s to avoid escaping.

```python
from simple_html import br, p, SafeString, render

node = p({},
         "Escaped & stuff",
         br,
         SafeString("Not escaped & stuff"))

render(node)  # <p>Escaped &amp; stuff<br/>Not escaped & stuff</p> 
```

Attributes are also escaped -- both names and values. You can use `SafeString` to bypass, if needed.

```python
from simple_html import div, render, SafeString

escaped_attrs_node = div({"<bad>":"</also bad>"})

render(escaped_attrs_node)  # <div &amp;lt;bad&amp;gt;="&amp;lt;/also bad&amp;gt;"></div>

unescaped_attrs_node = div({SafeString("<bad>"): SafeString("</also bad>")})

render(unescaped_attrs_node)  # <div <bad>="</also bad>"></div>
```

