diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml
index ef168e4..ee7021d 100644
--- a/.github/workflows/push.yml
+++ b/.github/workflows/push.yml
@@ -6,7 +6,7 @@ jobs:
strategy:
fail-fast: false
matrix:
- python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+ python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
poetry-version: [2.1]
os: [ubuntu-24.04, macos-latest, windows-latest]
runs-on: ${{ matrix.os }}
@@ -26,7 +26,7 @@ jobs:
- name: run bench (pure python)
run: poetry run python -m bench.run
- name: mypyc
- run: poetry run mypyc simple_html/utils.py
+ run: poetry run mypyc simple_html/core.py
- name: run tests
run: poetry run pytest
- name: run bench (compiled)
diff --git a/README.md b/README.md
index e0983d6..aafda70 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
## Why use it?
- clean syntax
- fully-typed
-- speed -- faster even than jinja
+- speed -- often faster than jinja
- zero dependencies
- escaped by default
- usually renders fewer bytes than templating
@@ -18,6 +18,7 @@
```python
from simple_html import h1, render
+
node = h1("Hello World!")
render(node)
@@ -36,6 +37,7 @@ Here's a fuller-featured example:
```python
from simple_html import render, DOCTYPE_HTML5, html, head, title, body, h1, div, p, br, ul, li
+
render(
DOCTYPE_HTML5,
html(
@@ -79,6 +81,7 @@ As you might have noticed, there are several ways to use `Tag`s:
```python
from simple_html import br, div, h1, img, span, render
+
# raw node renders to empty tag
render(br)
#
@@ -106,6 +109,7 @@ escaped by default; `SafeString`s can be used to bypass escaping.
```python
from simple_html import br, p, SafeString, render
+
node = p("Escaped & stuff",
br,
SafeString("Not escaped & stuff"))
@@ -121,6 +125,7 @@ that Tag attributes with `None` as the value will only render the attribute name
```python
from simple_html import div, render
+
node = div({"empty-str-attribute": "",
"key-only-attr": None})
@@ -133,6 +138,7 @@ String attributes are escaped by default -- both keys and values. You can use `S
```python
from simple_html import div, render, SafeString
+
render(
div({"":""})
)
@@ -149,6 +155,7 @@ You can also use `int`, `float`, and `Decimal` instances for attribute values.
from decimal import Decimal
from simple_html import div, render, SafeString
+
render(
div({"x": 1, "y": 2.3, "z": Decimal('3.45')})
)
@@ -161,6 +168,7 @@ You can render inline CSS styles with `render_styles`:
```python
from simple_html import div, render, render_styles
+
styles = render_styles({"min-width": "25px"})
node = div({"style": styles}, "cool")
@@ -184,6 +192,7 @@ You can pass many items as a `Tag`'s children using `*args`, lists or generators
from typing import Generator
from simple_html import div, render, Node, br, p
+
div(
*["neat", br], p("cool")
)
@@ -214,6 +223,7 @@ For convenience, most common 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
@@ -225,3 +235,89 @@ node = custom_elem(
render(node)
# Wow
```
+
+### Optimization
+
+#### `prerender`
+
+`prerender` is a very simple function. It just `render`s a `Node` and puts the resulting string inside
+a `SafeString` (so its contents won't be escaped again). It's most useful for prerendering at the module level,
+which ensures the render operation happens only once. A simple use case might be a website's footer:
+
+```python
+from simple_html import SafeString, prerender, footer, div, a, head, body, title, h1, html, render
+
+
+prerendered_footer: SafeString = prerender(
+ footer(
+ div(a({"href": "/about"}, "About Us")),
+ div(a({"href": "/blog"}, "Blog")),
+ div(a({"href": "/contact"}, "Contact"))
+ )
+)
+
+
+def render_page(page_title: str) -> str:
+ return render(
+ html(
+ head(title(page_title)),
+ body(
+ h1(page_title),
+ prerendered_footer # this is extremely fast to render
+ )
+ )
+ )
+```
+This greatly reduces the amount of work `render` needs to do on the prerendered content when outputting HTML.
+
+#### Caching
+You may want to cache rendered content. This is easy to do; the main thing to keep in
+mind is you'll likely want to return a `SafeString`. For example, here's how you might cache with `lru_cache`:
+
+```python
+from simple_html import prerender, SafeString, h1
+from functools import lru_cache
+
+
+@lru_cache
+def greeting(name: str) -> SafeString:
+ return prerender(
+ h1(f"Hello, {name}")
+ )
+```
+
+One thing to remember is that not all variants of `Node` are hashable, and thus cannot be passed directly to a function
+where the arguments constitute the cache key -- e.g. lists and generators are not hashable, but they can be
+valid `Node`s. Another way to use `prerender` in combination with a caching function is to prerender arguments:
+
+```python
+from simple_html import prerender, SafeString, h1, div, html, body, head, ul, li
+from functools import lru_cache
+
+
+@lru_cache
+def cached_content(children: SafeString) -> SafeString:
+ return prerender(
+ div(
+ h1("This content is cached according to the content of the children"),
+ children,
+ # presumably this function would have a lot more elements for it to be worth
+ # the caching overhead
+ )
+ )
+
+def page(words_to_render: list[str]):
+ return html(
+ head,
+ body(
+ cached_content(
+ prerender(ul([
+ li(word) for word in words_to_render
+ ]))
+ )
+ )
+ )
+```
+Keep in mind that using `prerender` on dynamic content -- not at the module level -- still incurs all the overhead
+of `render` each time that content is rendered, so, for this approach to make sense, the prerendered content should
+be a small portion of the full content of the `cached_content` function.
\ No newline at end of file
diff --git a/bench/simple.py b/bench/simple.py
index 6b92e29..cda1ca8 100644
--- a/bench/simple.py
+++ b/bench/simple.py
@@ -22,6 +22,7 @@
nav, a, main, section, article, aside, footer, span, img, time,
blockquote, code, pre, form, label, input_, textarea, button, table, thead, tbody, tr, th, td
)
+from simple_html.core import Node, prerender
def hello_world_empty(objs: List[None]) -> None:
@@ -29,22 +30,31 @@ def hello_world_empty(objs: List[None]) -> None:
render(h1("Hello, World!"))
+def _basic_html(list_items: list[Node]) -> Node:
+ return html(
+ head(title("A Great Web page!")),
+ body(
+ h1({"class": "great header",
+ "id": "header1",
+ "other_attr": "5"},
+ "Welcome!"),
+ div(
+ p("What a great web page!!!", br, br),
+ ul(list_items)
+ )
+ )
+ )
+
+
def basic(objs: List[Tuple[str, str, List[str]]]) -> None:
for title_, content, oks in objs:
- render(
- DOCTYPE_HTML5,
- html(
- head(title("A Great Web page!")),
- body(
- h1({"class": "great header",
- "id": "header1",
- "other_attr": "5"},
- "Welcome!"),
- div(
- p("What a great web page!!!", br, br),
- ul([
- li({"class": "item-stuff"}, SafeString(ss))
- for ss in oks])))))
+ render(DOCTYPE_HTML5,
+ _basic_html(
+ [
+ li({"class": "item-stuff"}, SafeString(ss))
+ for ss in oks
+ ]
+ ))
def basic_long(objs: List[Tuple[str, str, List[str]]]) -> None:
@@ -95,45 +105,62 @@ def basic_long(objs: List[Tuple[str, str, List[str]]]) -> None:
)
+def _lorem_html(title_: str) -> Node:
+ return html(
+ {"lang": "en"},
+ head(
+ meta({"charset": "UTF-8"}),
+ meta(
+ {
+ "name": "viewport",
+ "content": "width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0",
+ }
+ ),
+ meta({"http-equiv": "X-UA-Compatible", "content": "ie=edge"}),
+ title(title_),
+ ),
+ body(
+ "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
+ ),
+ )
+
+
def lorem_ipsum(titles: List[str]) -> None:
for t in titles:
- render(
- html(
- {"lang": "en"},
- head(
- meta({"charset": "UTF-8"}),
- meta(
- {
- "name": "viewport",
- "content": "width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0",
- }
- ),
- meta({"http-equiv": "X-UA-Compatible", "content": "ie=edge"}),
- title(t),
- ),
- body(
- "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
- ),
- )
- )
+ render(_lorem_html(t))
-def large_page(titles: list[str]) -> None:
- for t in titles:
- render(
- DOCTYPE_HTML5,
- html({"lang": "en"},
- head(
- meta({"charset": "UTF-8"}),
- meta({"name": "viewport", "content": "width=device-width, initial-scale=1.0"}),
- meta({"name": "description",
- "content": "Tech Insights - Your source for the latest in web development, AI, and programming trends"}),
- meta({"name": "keywords",
- "content": "web development, programming, AI, JavaScript, Python, tech news"}),
- title(t),
- link({"rel": "stylesheet", "href": "/static/css/main.css"}),
- link({"rel": "icon", "type": "image/x-icon", "href": "/favicon.ico"}),
- style("""
+def _article(heading: str,
+ published_date_iso: str,
+ published_data_readable,
+ author: str,
+ read_time_minutes: str,
+ content: list[Node],
+ is_featured: bool = False):
+ return article(
+ {"class": "post" + ("featured-post" if is_featured else ""), },
+ h2(heading),
+ p({"class": "post-meta"},
+ "Published on ", time({"datetime": published_date_iso}, published_data_readable),
+ " by ", span({"class": "author"}, author),
+ " | ", span({"class": "read-time"}, read_time_minutes, " min read")
+ ),
+ content
+ )
+
+
+def _get_head(title_: str) -> Node:
+ return head(
+ meta({"charset": "UTF-8"}),
+ meta({"name": "viewport", "content": "width=device-width, initial-scale=1.0"}),
+ meta({"name": "description",
+ "content": "Tech Insights - Your source for the latest in web development, AI, and programming trends"}),
+ meta({"name": "keywords",
+ "content": "web development, programming, AI, JavaScript, Python, tech news"}),
+ title(title_),
+ link({"rel": "stylesheet", "href": "/static/css/main.css"}),
+ link({"rel": "icon", "type": "image/x-icon", "href": "/favicon.ico"}),
+ style("""
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 0; }
.container { max-width: 1200px; margin: 0 auto; padding: 0 20px; }
.site-header { background: #2c3e50; color: white; padding: 1rem 0; }
@@ -150,318 +177,341 @@ def large_page(titles: list[str]) -> None:
.stats-table th, .stats-table td { padding: 0.5rem; border: 1px solid #ddd; text-align: left; }
.stats-table th { background: #f0f0f0; }
""")
- ),
- body(
- header({"class": "site-header"},
- div({"class": "container"},
- h1({"class": "site-title"}, "Tech Insights"),
- nav(
- ul({"class": "nav-menu"},
- li(a({"href": "/"}, "Home")),
- li(a({"href": "/tutorials"}, "Tutorials")),
- li(a({"href": "/articles"}, "Articles")),
- li(a({"href": "/reviews"}, "Reviews")),
- li(a({"href": "/resources"}, "Resources")),
- li(a({"href": "/about"}, "About")),
- li(a({"href": "/contact"}, "Contact"))
+ )
+
+_footer = prerender(
+ footer({"class": "site-footer"},
+ div({"class": "container"},
+ div({"class": "footer-content"},
+ div({"class": "footer-section"},
+ h4("About Tech Insights"),
+ p("Your go-to resource for web development tutorials, programming guides, and the latest technology trends. We help developers stay current with industry best practices.")
+ ),
+ div({"class": "footer-section"},
+ h4("Quick Links"),
+ ul(
+ li(a({"href": "/privacy"}, "Privacy Policy")),
+ li(a({"href": "/terms"}, "Terms of Service")),
+ li(a({"href": "/sitemap"}, "Sitemap")),
+ li(a({"href": "/advertise"}, "Advertise"))
)
- )
- )
- ),
- main({"class": "container main-content"},
- section({"class": "content-area"},
- article({"class": "post featured-post"},
- h2("Complete Guide to Modern Web Development in 2024"),
- p({"class": "post-meta"},
- "Published on ", time({"datetime": "2024-03-15"}, "March 15, 2024"),
- " by ", span({"class": "author"}, "Sarah Johnson"),
- " | ", span({"class": "read-time"}, "12 min read")
- ),
- img({"src": "/images/web-dev-2024.jpg",
- "alt": "Modern web development tools and frameworks",
- "style": "width: 100%; height: 300px; object-fit: cover; border-radius: 8px;"}),
- p(
- "Web development has evolved significantly in recent years, transforming from simple static pages ",
- "to complex, interactive applications that power our digital world. The landscape continues to change ",
- "rapidly, driven by new technologies, frameworks, and methodologies that promise to make development ",
- "faster, more efficient, and more accessible."
- ),
- h3("Key Technologies Shaping the Future"),
- p("The modern web development ecosystem is built around several core technologies:"),
- ul(
- li("**Component-based frameworks** like React, Vue, and Angular that promote reusable UI components"),
- li("**Progressive Web Apps (PWAs)** that bridge the gap between web and native applications"),
- li("**Serverless architectures** using AWS Lambda, Vercel Functions, and Netlify Functions"),
- li("**JAMstack** (JavaScript, APIs, Markup) for better performance and security"),
- li("**GraphQL** for more efficient data fetching and API design"),
- li("**TypeScript** for type-safe JavaScript development"),
- li("**Edge computing** for reduced latency and improved user experience")
- ),
- h3("Framework Comparison"),
- table({"class": "stats-table"},
- thead(
- tr(
- th("Framework"),
- th("Learning Curve"),
- th("Performance"),
- th("Community"),
- th("Use Case")
- )
- ),
- tbody(
- tr(
- td("React"),
- td("Medium"),
- td("High"),
- td("Very Large"),
- td("Complex UIs, SPAs")
- ),
- tr(
- td("Vue.js"),
- td("Easy"),
- td("High"),
- td("Large"),
- td("Rapid prototyping, SME apps")
- ),
- tr(
- td("Angular"),
- td("Steep"),
- td("High"),
- td("Large"),
- td("Enterprise applications")
- ),
- tr(
- td("Svelte"),
- td("Easy"),
- td("Very High"),
- td("Growing"),
- td("Performance-critical apps")
- )
- )
- ),
- h3("Code Example: Modern Component"),
- p("Here's an example of a modern React component using hooks and TypeScript:"),
- pre({"class": "code-block"},
- code("""
- interface User {
- id: number;
- name: string;
- email: string;
- }
-
- const UserProfile: React.FC<{ userId: number }> = ({ userId }) => {
- const [user, setUser] = useState(null);
- const [loading, setLoading] = useState(true);
-
- useEffect(() => {
- fetchUser(userId)
- .then(setUser)
- .finally(() => setLoading(false));
- }, [userId]);
-
- if (loading) return Loading...
;
- if (!user) return User not found
;
-
- return (
-
-
{user.name}
-
{user.email}
-
Loading...
;
+ if (!user) return User not found
;
+
+ return (
+
+
{user.name}
+
{user.email}
+