From 91dee6e6852c5fc64a533992a44a1b49843f4fa1 Mon Sep 17 00:00:00 2001
From: Andreas Pelme <andreas@pelme.se>
Date: Mon, 20 May 2024 20:53:30 +0200
Subject: [PATCH] Deployed b439335 with MkDocs version: 1.5.3

---
 references/index.html    |  15 ++++++++++++++-
 search/search_index.json |   2 +-
 sitemap.xml.gz           | Bin 127 -> 127 bytes
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/references/index.html b/references/index.html
index c59a9f4..0c7f673 100644
--- a/references/index.html
+++ b/references/index.html
@@ -408,6 +408,15 @@
     </label>
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
+        <li class="md-nav__item">
+  <a href="#projects-that-use-htpy" class="md-nav__link">
+    <span class="md-ellipsis">
+      Projects that use htpy
+    </span>
+  </a>
+  
+</li>
+      
         <li class="md-nav__item">
   <a href="#similar-libraries-and-tools" class="md-nav__link">
     <span class="md-ellipsis">
@@ -453,8 +462,12 @@
 
 
 <h1 id="references">References<a class="headerlink" href="#references" title="Permanent link">&para;</a></h1>
-<p>htpy was heavily inspired by many other libraries and articles. This page lists some of them.</p>
+<h2 id="projects-that-use-htpy">Projects that use htpy<a class="headerlink" href="#projects-that-use-htpy" title="Permanent link">&para;</a></h2>
+<ul>
+<li><a href="https://voterbowl.org">voterbowl.org</a> - College students win prizes by checking if they are registered to vote: <a href="https://github.com/front-seat/voterbowl/tree/main/server/vb/components">Github repository</a>.</li>
+</ul>
 <h2 id="similar-libraries-and-tools">Similar libraries and tools<a class="headerlink" href="#similar-libraries-and-tools" title="Permanent link">&para;</a></h2>
+<p>htpy was heavily inspired by many other libraries that came before it.</p>
 <ul>
 <li><a href="https://legacy.reactjs.org/docs/introducing-jsx.html">JSX/React</a> - Made writing HTML in a programming language popular.</li>
 <li><a href="https://github.com/dropbox/pyxl">pyxl</a>, <a href="https://github.com/gvanrossum/pyxl3">pyxl3</a>, <a href="https://github.com/pyxl4/pyxl4">pyxl4</a> - Write HTML in Python with JSX-like syntax. Not actively maintained.</li>
diff --git a/search/search_index.json b/search/search_index.json
index cbf07af..7ce39a4 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":""},{"location":"#htpy-html-in-python","title":"htpy - HTML in Python","text":"<p>htpy is a library that makes writing HTML in plain Python fun and efficient, without a template language.</p> <p>Define HTML in Python: <pre><code>from htpy import body, h1, head, html, li, title, ul\n\nmenu = [\"egg+bacon\", \"bacon+spam\", \"eggs+spam\"]\n\nprint(\n    html[\n        head[title[\"Todays menu\"]],\n        body[\n            h1[\"Menu\"],\n            ul(\".menu\")[(li[item] for item in menu)],\n        ],\n    ]\n)\n</code></pre></p> <p>And get HTML: <pre><code>&lt;!DOCTYPE html&gt;\n&lt;html&gt;\n  &lt;head&gt;\n    &lt;title&gt;Todays menu&lt;/title&gt;\n  &lt;/head&gt;\n  &lt;body&gt;\n    &lt;h1&gt;Menu&lt;/h1&gt;\n    &lt;ul class=\"menu\"&gt;\n      &lt;li&gt;egg+bacon&lt;/li&gt;\n      &lt;li&gt;bacon+spam&lt;/li&gt;\n      &lt;li&gt;eggs+spam&lt;/li&gt;\n    &lt;/ul&gt;\n  &lt;/body&gt;\n&lt;/html&gt;\n</code></pre></p>"},{"location":"#motivation-for-this-project","title":"Motivation for this project","text":"<p>At Personalkollen, where htpy was originally developed we often found ourselves hitting walls when using classic templates. htpy was created to improve the productiveness and experience of generating HTML from a Python backend.</p>"},{"location":"#key-features","title":"Key features","text":"<ul> <li> <p>Leverage static types: Use mypy or pyright to type check your code.</p> </li> <li> <p>Great debugging: Avoid cryptic stack traces from templates. Use your favorite Python debugger.</p> </li> <li> <p>Easy to extend: There is no special way to define template tags/filters. Just call regular functions.</p> </li> <li> <p>Works with existing Python web framework: Works great with Django, Flask or any other Python web framework!</p> </li> <li> <p>Works great with htmx: htpy makes for a great experience when writing server rendered partials/components.</p> </li> <li> <p>Create reusable components: Define components, snippets, complex layouts/pages as regular Python variables or functions.</p> </li> <li> <p>Familiar concepts from React: React helped make it popular writing HTML with a programming language. htpy uses a lot of similar constructs.</p> </li> </ul>"},{"location":"#philosophy","title":"Philosophy","text":"<p>htpy generates HTML elements and attributes and provide a few helpers.</p> <p>htpy does not enforce any particular pattern or style to organize your pages, components and layouts. That does not mean that htpy cannot be used to build sophisticated web pages or applications.</p> <p>Rather the opposite: you are encouraged the leverage the power of Python to structure your project. Use modules, classes, functions, decorators, list comprehension, generators, conditionals, static typing and any other feature of Python to organize your components. This gives you a lot of power and makes htpy scale from a single small Flask project to bigger applications.</p> <p>Common patterns can give you some ideas that you can build upon yourself.</p>"},{"location":"#the-syntax","title":"The syntax","text":"<p>Child elements are specified using the <code>[]</code> syntax. This may look strange at first but it has some nice benefits. This clearly separates attributes from children elements and makes the code more readable. It is implemented using the <code>__getitem__</code> method, just like lists or dicts.</p>"},{"location":"#installation","title":"Installation","text":"<p>htpy is available on PyPI. You may install the latest version using pip: <pre><code>pip install htpy\n</code></pre></p>"},{"location":"#documentation","title":"Documentation","text":"<p>The full documentation is available at https://htpy.dev:  - Usage  - Common patterns  - Static typing  - Usage with Django  - Streaming of contents  - FAQ  - References</p>"},{"location":"common-patterns/","title":"Common patterns","text":"<p>htpy itself is a library that does not impose any particular structure for your code. You have the full power of Python functions, classes and modules at your disposal.</p> <p>General programming practices on how to structure modules, functions and classes apply to HTML generation with htpy.</p> <p>This page describes common scenarios and patterns that may help you structure your own project in a good way.</p>"},{"location":"common-patterns/#filemodule-structure","title":"File/module structure","text":"<p>It is generally a good idea to keep your HTML pages/components separate from HTTP request handling and \"business logic\".</p> <p>In Django, this means that the view function should not directly generate the HTML.</p> <p>Using a file named <code>components.py</code> can be a good idea. If you have many components, you may create a <code>components</code> package instead.</p> <p>Your component functions can accept arbitrary argument with the required data. It is a good idea to only use keyword arguments (put a <code>*</code> in the argument list to force keyword arguments):</p> views.py<pre><code>from django.http import HttpRequest, HttpResponse\n\nfrom .components import greeting_page\n\ndef greeting(request: HttpRequest) -&gt; HttpResponse:\n    return HttpResponse(greeting_page(\n        name=request.GET.get(\"name\", \"anonymous\"),\n    ))\n</code></pre> components.py<pre><code>from htpy import html, body, h1\n\ndef greeting_page(*, name: str) -&gt; Element:\n    return html[body[h1[f\"hi {name}!\"]]]\n</code></pre>"},{"location":"common-patterns/#using-a-base-layout","title":"Using a base layout","text":"<p>A common feature of template languages is to \"extend\" a base/parent template and specify placeholders. This can be achieved with a <code>base_layout</code> function:</p> components.py<pre><code>import datetime\n\nfrom htpy import body, div, h1, head, html, p, title, Node, Element\n\n\ndef base_page(*,\n    page_title: str | None = None,\n    extra_head: Node = None,\n    content: Node = None,\n    body_class: str | None = None,\n) -&gt; Element:\n    return html[\n        head[title[page_title], extra_head],\n        body(class_=body_class)[\n            content,\n            div(\"#footer\")[f\"Copyright {datetime.date.today().year} by Foo Inc.\"],\n        ],\n    ]\n\n\ndef index_page() -&gt; Element:\n    return base_page(\n        page_title=\"Welcome!\",\n        body_class=\"green\",\n        content=[\n            h1[\"Welcome to my site!\"],\n            p[\"Hello and welcome!\"],\n        ],\n    )\n\n\ndef about_page() -&gt; Element:\n    return base_page(\n        page_title=\"About us\",\n        content=[\n            h1[\"About us\"],\n            p[\"We love creating web sites!\"],\n        ],\n    )\n</code></pre>"},{"location":"common-patterns/#ui-components","title":"UI components","text":"<p>Creating higher level wrappers for common UI components can be a good idea to reduce repetition.</p> <p>Wrapping Bootstrap Modal could be achieved with a function like this:</p> Creating wrapper for Bootstrap Modal<pre><code>from markupsafe import Markup\n\nfrom htpy import Element, Node, button, div, h5, span\n\n\ndef bootstrap_modal(*, title: str, body: Node = None, footer: Node = None) -&gt; Element:\n    return div(\".modal\", tabindex=\"-1\", role=\"dialog\")[\n        div(\".modal-dialog\", role=\"document\")[\n            div(\".modal-content\")[\n                div(\".modal-header\")[\n                    div(\".modal-title\")[\n                        h5(\".modal-title\")[title],\n                        button(\n                            \".close\",\n                            type=\"button\",\n                            data_dismiss=\"modal\",\n                            aria_label=\"Close\",\n                        )[span(aria_hidden=\"true\")[Markup(\"&amp;times;\")]],\n                    ]\n                ],\n                div(\".modal-body\")[body],\n                footer and div(\".modal-footer\")[footer],\n            ]\n        ]\n    ]\n</code></pre> <p>You would then use it like this: <pre><code>from htpy import button, p\n\nprint(\n    bootstrap_modal(\n        title=\"Modal title\",\n        body=p[\"Modal body text goes here.\"],\n        footer=[\n            button(\".btn.btn-primary\", type=\"button\")[\"Save changes\"],\n            button(\".btn.btn-secondary\", type=\"button\")[\"Close\"],\n        ],\n    )\n)\n</code></pre></p>"},{"location":"django/","title":"Usage with Django","text":"<p>htpy is not tied to any specific web framework. Nonetheless, htpy works great when combined with Django. This page contains information and useful techniques on how to combine htpy and Django.</p>"},{"location":"django/#returning-a-htpy-response","title":"Returning a htpy response","text":"<p>htpy elements can be passed directly to <code>HttpResponse</code>:</p> views.py<pre><code>from django.http import HttpResponse\nfrom htpy import html, body, div\n\ndef my_view(request):\n    return HttpResponse(html[body[div[\"Hi Django!\"]]])\n</code></pre>"},{"location":"django/#using-htpy-as-part-of-an-existing-django-template","title":"Using htpy as part of an existing Django template","text":"<p>htpy elements are marked as \"safe\" and can be injected directly into Django templates. This can be useful if you want to start using htpy gradually in an existing template based Django project:</p> base.html<pre><code>&lt;html&gt;\n    &lt;head&gt;\n        &lt;title&gt;My Django Site&lt;/title&gt;\n    &lt;/head&gt;\n    &lt;body&gt;{{ content }}&lt;/body&gt;\n&lt;/html&gt;\n</code></pre> views.py<pre><code>from django.shortcuts import render\n\nfrom htpy import h1\n\n\ndef index(request):\n    return render(request, \"base.html\", {\n        \"content\": h1[\"Welcome to my site!\"],\n    })\n</code></pre>"},{"location":"django/#render-a-django-form","title":"Render a Django form","text":"<p>CSRF token, form widgets and errors can be directly used within htpy elements:</p> forms.py<pre><code>from django import forms\n\n\nclass MyForm(forms.Form):\n    name = forms.CharField()\n</code></pre> views.py<pre><code>from django.http import HttpRequest, HttpResponse\n\nfrom .components import my_form_page, my_form_success_page\nfrom .forms import MyForm\n\n\ndef my_form(request: HttpRequest) -&gt; HttpResponse:\n    form = MyForm(request.POST or None)\n    if form.is_valid():\n        return HttpResponse(my_form_success_page())\n\n    return HttpResponse(my_form_page(request, my_form=form))\n</code></pre> components.py<pre><code>from django.http import HttpRequest\nfrom django.template.backends.utils import csrf_input\n\nfrom htpy import Element, Node, body, button, form, h1, head, html, title\n\nfrom .forms import MyForm\n\n\ndef base_page(page_title: str, content: Node) -&gt; Element:\n    return html[\n        head[title[page_title]],\n        body[content],\n    ]\n\n\ndef my_form_page(request: HttpRequest, *, my_form: MyForm) -&gt; Element:\n    return base_page(\n        \"My form\",\n        form(method=\"post\")[\n            csrf_input(request),\n            my_form.errors,\n            my_form[\"name\"],\n            button[\"Submit!\"],\n        ],\n    )\n\n\ndef my_form_success_page() -&gt; Element:\n    return base_page(\n        \"Success!\",\n        h1[\"Success! The form was valid!\"],\n    )\n</code></pre>"},{"location":"django/#implement-custom-form-widgets-with-htpy","title":"Implement custom form widgets with htpy","text":"<p>You can implement a custom form widget directly with htpy like this:</p> widgets.py<pre><code>from django.forms import widgets\n\nfrom htpy import sl_input\n\n\nclass ShoelaceInput(widgets.Widget):\n    \"\"\"\n    A form widget using Shoelace's &lt;sl-input&gt; element.\n    More info: https://shoelace.style/components/input\n    \"\"\"\n\n    def render(self, name, value, attrs=None, renderer=None):\n        return str(sl_input(attrs, name=name, value=value))\n</code></pre>"},{"location":"faq/","title":"FAQ","text":""},{"location":"faq/#how-does-htpy-performance-compare-to-django-or-jinja-templates","title":"How does htpy performance compare to Django or Jinja templates?","text":"<p>The performance of HTML rendering is rarely the bottleneck in most web application. It is usually fast enough regardless of what method of constructing the HTML is being used.</p> <p>Given that it has been fast enough, there has not been much effort in optimizing htpy. It should be possible to significantly increase the effectiveness and we are open to contributions with benchmarks and speed improvements.</p> <p>That said, htpy is currently on par with Django templates when it comes to speed. Jinja2 is currently significantly faster than both Django templates and htpy. There is a small benchmark script in the repo that generates a table with 50 000 rows.</p>"},{"location":"faq/#can-htpy-generate-xmlxhtml","title":"Can htpy generate XML/XHTML?","text":"<p>No. Generating XML/XHTML is out of scope for this project. Use a XML library if you are looking to generate XML.</p> <p>htpy generates HTML, therefore \"void elements\" such as <code>&lt;br&gt;</code> does not include a trailing <code>/</code>.</p> <p>If you are looking to generate generic XML, <code>lxml.builder</code> could be a good alternative.</p>"},{"location":"faq/#does-not-generating-html-from-python-mean-mixing-concerns-between-presentation-and-business-logic","title":"Does not generating HTML from Python mean mixing concerns between presentation and business logic?","text":"<p>With a template language, putting HTML markup in separate files is enforced by design. Avoiding logic in the presentation layer is also mostly done by making the language very restrictive.</p> <p>It takes a little bit of planning and effort, but it is possible to have a nicely separated presentation layer that is free from logic. See Common patterns for more details on how you can structure your project.</p>"},{"location":"faq/#what-kind-of-black-magic-makes-from-htpy-import-whatever_element-work","title":"What kind of black magic makes <code>from htpy import whatever_element</code> work?","text":"<p>htpy uses the module level <code>__getattr__</code>. It was introduced in Python 3.7. It allows creating <code>Element</code> instances for any elements that are imported.</p>"},{"location":"faq/#why-does-htpy-not-provide-html-like-tag-syntax-with-angle-brackets-like-pyxl-and-jsx","title":"Why does htpy not provide HTML like tag syntax with angle brackets like pyxl and JSX?","text":"<p>htpy must be compatible with standard Python code formatters, editors and static type checkers. Unfortunately, it is not possible to support those workflows with a custom syntax without a massive effort to change those tools to support that syntax.</p>"},{"location":"references/","title":"References","text":"<p>htpy was heavily inspired by many other libraries and articles. This page lists some of them.</p>"},{"location":"references/#similar-libraries-and-tools","title":"Similar libraries and tools","text":"<ul> <li>JSX/React - Made writing HTML in a programming language popular.</li> <li>pyxl, pyxl3, pyxl4 - Write HTML in Python with JSX-like syntax. Not actively maintained.</li> <li>htbuilder - Very similar to htpy but does not currently support automatic escaping.</li> <li>nevow.stan - Probably the earliest use of <code>[]</code> syntax for specifying children. Not actively maintained.</li> <li>breve - Another early implementation of HTML in Python,  Using getattr <code>[]</code> syntax for children. Not actively maintained.</li> <li>hyperscript - JavaScript library that also uses CSS selector-like syntax for specifying id and classes.</li> <li>hyperpython - A Python interpretation of hyperscript. Not actively maintained.</li> <li>h by Adam Johnson - Similar to htpy, uses call syntax (<code>()</code>) for attributes and getitem (<code>[]</code>) for children.</li> <li>lxml.builder - lxml's <code>E</code> allows creating XML/XHTML documents from Python.</li> </ul>"},{"location":"references/#articles-about-html-generation-without-templates","title":"Articles about HTML generation without templates","text":"<ul> <li>Jeff Atwood - You're Doing It Wrong - Stack Overflow co-founder Jeff Atwood</li> <li>Tavis Rudd - Throw out your templates - Tavis Rudd, creator of Python template language \"Cheetah\" argues for creating HTML without templates.</li> <li>David Ford - 80% of my coding is doing this (or why templates are dead) - Discusses various techniques for rendering HTML.</li> </ul>"},{"location":"static-typing/","title":"Static typing","text":"<p>htpy was designed to be used with static typing. Since you define all your own data/components with regular Python, a static type checker like mypy will catch errors like this:</p> <pre><code>class User:\n    def __init__(self, name: str):\n        self.name = name\n\n\ndef greeting(user: User) -&gt; Element:\n    return h1[f\"Hi {user.first_name.capitalize()}!]\n#                        ^^^^^^^^^^\n# mypy: error: \"User\" has no attribute \"first_name\"  [attr-defined]\n</code></pre>"},{"location":"static-typing/#autocompletion-of-html-elements","title":"Autocompletion of HTML elements","text":"<p>htpy ships with type annotations for all HTML elements. If your editor supports it, it will show you useful auto completions:</p> <p></p>"},{"location":"static-typing/#element-and-voidelement-classes","title":"<code>Element</code> and <code>VoidElement</code> classes","text":"<p>The base types/classes in htpy are <code>Element</code> and <code>VoidElement</code>. <code>Element</code> are all regular HTML elements that can have children such as <code>&lt;div&gt;</code>, <code>&lt;span&gt;</code> and <code>&lt;table&gt;</code>. <code>VoidElement</code> are HTML void element which cannot have children such as <code>&lt;img&gt;</code>, <code>&lt;input&gt;</code> and <code>&lt;br&gt;</code>.</p> <p>Use <code>Element</code> as the return type when you want to always return an element.</p> <pre><code>from typing import Literal\n\nfrom htpy import Element, span\n\n\ndef bootstrap_badge(\n    text: str,\n    style: Literal[\"primary\", \"success\", \"danger\"] = \"primary\",\n) -&gt; Element:\n    return span(f\".badge.text-bg-{style}\")[text]\n</code></pre>"},{"location":"static-typing/#node","title":"Node","text":"<p><code>Node</code> is a type alias for all possible objects that can be used as a child node. See the source for the exact definition that defines all kinds of nodes that can be children of an element. This is a wider type than <code>Element</code> since child nodes can be str, markup, None, iterables or callables.</p> <p>Use <code>Node</code> when you want to create a wrapper function to be flexible with what you accept. This function will accept both a str or some other element to be passed as <code>contents</code>:</p> <pre><code>from htpy import Element, Node, div\n\ndef bootstrap_alert(contents: Node) -&gt; Element:\n    return div(\".alert\", role=\"alert\")[contents]\n</code></pre>"},{"location":"streaming/","title":"Streaming of contents","text":"<p>Internally, htpy is built with generators. Most of the time, you would render the full page with <code>str()</code>, but htpy can also incrementally generate pages which can then be streamed to the browser. If your page uses a database or other services to retrieve data, you can sending the first part of the page to the client while the page is being generated.</p> <p>Note</p> <p>Streaming requires a bit of discipline and care to get right. You need to ensure to avoid doing too much work up front and use lazy constructs such as generators and callables. Most of the time, rendering the page without streaming will be the easiest way to get going. Streaming can give you improved user experience from faster pages/rendering.</p> <p>This video shows what it looks like in the browser to generate a HTML table with Django StreamingHttpResponse (source code):</p> <p>This example simulates a (very) slow fetch of data and shows the power of streaming: The browser loads CSS and gradually shows the contents. By loading CSS files in the <code>&lt;head&gt;</code> tag before dynamic content, the browser can start working on loading the CSS and styling the page while the server keeps generating the rest of the page.</p>"},{"location":"streaming/#using-generators-and-callables-as-children","title":"Using generators and callables as children","text":"<p>Django's querysets are lazily evaluated. They will not execute a database query before their value is actually needed.</p> <p>This example shows how this property of Django querysets can be used to create a page that streams objects: <pre><code>from django.http import StreamingHttpResponse\nfrom htpy import ul, li\n\nfrom myapp.models import Article\n\ndef article_list(request):\n    return StreamingHttpResponse(ul[\n        (li[article.title] for article in Article.objects.all())\n    ])\n</code></pre></p>"},{"location":"streaming/#using-callables-to-delay-evalutation","title":"Using callables to delay evalutation","text":"<p>Pass a callable that does not accept any arguements as child to delay the evaluation.</p> <p>This example shows how the page starts rendering and outputs the <code>&lt;h1&gt;</code> tag and then calls <code>calculate_magic_number</code>.</p> <pre><code>import time\nfrom htpy import div, h1\n\ndef calculate_magic_number() -&gt; str:\n    time.sleep(1)\n    print(\"  (running the complex calculation...)\")\n    return \"42\"\n\nelement = div[\n    h1[\"Welcome to my page\"],\n    \"The magic number is \",\n    calculate_magic_number,\n]\n\nfor chunk in element:\n    print(chunk)\n</code></pre> <p>Output: <pre><code>&lt;div&gt;\n&lt;h1&gt;\nWelcome to my page\n&lt;/h1&gt;\nThe magic number is\n42    # &lt;-- Appears after 3 seconds\n&lt;/div&gt;\n</code></pre></p> <p>You may use <code>lambda</code> to create a function without arguments to make a an expression lazy:</p> <pre><code>from htpy import div, h1\n\n\ndef fib(n: int) -&gt; int:\n    if n == 0:\n        return 0\n    elif n == 1:\n        return 1\n    else:\n        return fib(n - 1) + fib(n - 2)\n\n\nprint(\n    div[\n        h1[\"Fibonacci!\"],\n        \"fib(20)=\",\n        lambda: str(fib(20)),\n    ]\n)\n# output: &lt;div&gt;&lt;h1&gt;Fibonacci!&lt;/h1&gt;fib(12)=6765&lt;/div&gt;\n</code></pre>"},{"location":"usage/","title":"Usage","text":"<p>Elements are imported directly from the <code>htpy</code> module as their name. HTML attributes are specified by parenthesis (<code>()</code> / \"call\"). Children are specified using square brackets (<code>[]</code> / \"getitem\").</p> <pre><code>&gt;&gt;&gt; from htpy import div\n&gt;&gt;&gt; print(div(id=\"hi\")[\"Hello!\"])\n&lt;div id=\"hi\"&gt;Hello!&lt;/div&gt;\n</code></pre>"},{"location":"usage/#elements","title":"Elements","text":"<p>Children can be strings, markup, other elements or lists/iterators.</p> <p>Elements can be arbitrarily nested: Nested elements<pre><code>&gt;&gt;&gt; from htpy import article, section, p\n&gt;&gt;&gt; print(section[article[p[\"Lorem ipsum\"]]])\n&lt;section&gt;&lt;article&gt;&lt;p&gt;Lorem ipsum&lt;/p&gt;&lt;/article&gt;&lt;/section&gt;\n</code></pre></p>"},{"location":"usage/#textstrings","title":"Text/strings","text":"<p>It is possible to pass a string directly: Using a string as children<pre><code>&gt;&gt;&gt; from htpy import h1\n&gt;&gt;&gt; print(h1[\"Welcome to my site!\"])\n&lt;h1&gt;Welcome to my site!&lt;/h1&gt;\n</code></pre></p> <p>Strings are automatically escaped to avoid XSS vulnerabilities. It is convenient and safe to directly insert variable data via f-strings:</p> <pre><code>&gt;&gt;&gt; from htpy import h1\n&gt;&gt;&gt; user_supplied_name = \"bobby &lt;/h1&gt;\"\n&gt;&gt;&gt; print(h1[f\"hello {user_supplied_name}\"])\n&lt;h1&gt;hello bobby &amp;lt;/h1&amp;gt;&lt;/h1&gt;\n</code></pre>"},{"location":"usage/#conditional-rendering","title":"Conditional rendering","text":"<p><code>None</code> will not render anything. This can be useful to conditionally render some content.</p> Conditional rendering<pre><code>&gt;&gt;&gt; from htpy import div, b\n&gt;&gt;&gt; error = None\n\n&gt;&gt;&gt; # No &lt;b&gt; tag will be rendered since error is None\n&gt;&gt;&gt; print(div[error and b[error]])\n&lt;div&gt;&lt;/div&gt;\n\n&gt;&gt;&gt; error = 'Enter a valid email address.'\n&gt;&gt;&gt; print(div[error and b[error]])\n&lt;div&gt;&lt;b&gt;Enter a valid email address.&lt;/b&gt;&lt;/div&gt;\n\n# Inline if/else can also be used:\n&gt;&gt;&gt; print(div[b[error] if error else None])\n&lt;div&gt;&lt;b&gt;Enter a valid email address.&lt;/b&gt;&lt;/div&gt;\n</code></pre>"},{"location":"usage/#loops-iterating-over-children","title":"Loops / iterating over children","text":"<p>You can pass a list, tuple or generator to generate multiple children:</p> Iterate over a generator<pre><code>&gt;&gt;&gt; from htpy import ul, li\n&gt;&gt;&gt; print(ul[(li[letter] for letter in \"abc\")])\n&lt;ul&gt;&lt;li&gt;a&lt;/li&gt;&lt;li&gt;b&lt;/li&gt;&lt;li&gt;c&lt;/li&gt;&lt;/ul&gt;\n</code></pre> <p>Note</p> <p>The generator will be lazily evaluated when rendering the element, not directly when the element is constructed. See Streaming for more information.</p> <p>A <code>list</code> can be used similar to a JSX fragment:</p> Render a list of child elements<pre><code>&gt;&gt;&gt; from htpy import div, img\n&gt;&gt;&gt; my_images = [img(src=\"a.jpg\"), img(src=\"b.jpg\")]\n&gt;&gt;&gt; print(div[my_images])\n&lt;div&gt;&lt;img src=\"a.jpg\"&gt;&lt;img src=\"b.jpg\"&gt;&lt;/div&gt;\n</code></pre>"},{"location":"usage/#custom-elements-web-components","title":"Custom elements / web components","text":"<p>Custom elements / web components are HTML elements that contains at least one dash (<code>-</code>). Since <code>-</code> cannot be used in Python identifiers, use underscore (<code>_</code>) instead:</p> Using custom elements<pre><code>&gt;&gt;&gt; from htpy import my_custom_element\n&gt;&gt;&gt; print(my_custom_element['hi!'])\n&lt;my-custom-element&gt;hi!&lt;/my-custom-element&gt;\n</code></pre>"},{"location":"usage/#injecting-markup","title":"Injecting markup","text":"<p>If you have HTML markup that you want to insert without further escaping, wrap it in <code>Markup</code> from the markupsafe library. markupsafe is a dependency of htpy and is automatically installed:</p> Injecting markup<pre><code>&gt;&gt;&gt; from htpy import div\n&gt;&gt;&gt; from markupsafe import Markup\n&gt;&gt;&gt; print(div[Markup(\"&lt;foo&gt;&lt;/foo&gt;\")])\n&lt;div&gt;&lt;foo&gt;&lt;/foo&gt;&lt;/div&gt;\n</code></pre> <p>If you are generate Markdown and want to insert it into an element, use <code>Markup</code>: Injecting generated markdown<pre><code>&gt;&gt;&gt; from markdown import markdown\n&gt;&gt;&gt; from markupsafe import Markup\n&gt;&gt;&gt; from htpy import div\n&gt;&gt;&gt; print(div[Markup(markdown('# Hi'))])\n&lt;div&gt;&lt;h1&gt;Hi&lt;/h1&gt;&lt;/div&gt;\n</code></pre></p>"},{"location":"usage/#html-doctype","title":"HTML Doctype","text":"<p>The HTML doctype is automatically prepended to the <code>&lt;html&gt;</code> tag:</p> <pre><code>&gt;&gt;&gt; from htpy import html\n&gt;&gt;&gt; print(html)\n&lt;!doctype html&gt;&lt;html&gt;&lt;/html&gt;\n</code></pre>"},{"location":"usage/#attributes","title":"Attributes","text":"<p>HTML attributes are defined by calling the element. They can be specified in a couple of different ways.</p>"},{"location":"usage/#elements-without-attributes","title":"Elements without attributes","text":"<p>Some elements do not have attributes, they can be specified by just the element itself:</p> <pre><code>&gt;&gt;&gt; from htpy import hr\n&gt;&gt;&gt; print(hr)\n&lt;hr&gt;\n</code></pre>"},{"location":"usage/#keyword-arguments","title":"Keyword arguments","text":"<p>Attributes can be specified via keyword arguments:</p> <pre><code>&gt;&gt;&gt; from htpy import img\n&gt;&gt;&gt; print(img(src=\"picture.jpg\"))\n&lt;img src=\"picture.jpg\"&gt;\n</code></pre> <p>In Python, <code>class</code> and <code>for</code> cannot be used as keyword arguments. Instead, they can be specified as <code>class_</code> or <code>for_</code> when using keyword arguments:</p> <pre><code>&gt;&gt;&gt; from htpy import label\n&gt;&gt;&gt; print(label(for_=\"myfield\"))\n&lt;label for=\"myfield\"&gt;&lt;/label&gt;\n</code></pre> <p>Attributes that contains dashes <code>-</code> can be specified using underscores: <pre><code>&gt;&gt;&gt; from htpy import form\n&gt;&gt;&gt; print(form(hx_post=\"/foo\"))\n&lt;form hx-post=\"/foo\"&gt;&lt;/form&gt;\n</code></pre></p>"},{"location":"usage/#idclass-shorthand","title":"id/class shorthand","text":"<p>Defining <code>id</code> and <code>class</code> attributes is common when writing HTML. A string shorthand that looks like a CSS selector can be used to quickly define id and classes:</p> Define id<pre><code>&gt;&gt;&gt; from htpy import div\n&gt;&gt;&gt; print(div(\"#myid\"))\n&lt;div id=\"myid\"&gt;&lt;/div&gt;\n</code></pre> Define multiple classes<pre><code>&gt;&gt;&gt; from htpy import div\n&gt;&gt;&gt; print(div(\".foo.bar\"))\n&lt;div id=\"foo bar\"&gt;&lt;/div&gt;\n</code></pre> Combining both id and classes<pre><code>&gt;&gt;&gt; from htpy import div\n&gt;&gt;&gt; print(div(\"#myid.foo.bar\"))\n&lt;div id=\"myid\" class=\"foo bar\"&gt;&lt;/div&gt;\n</code></pre>"},{"location":"usage/#attributes-as-dict","title":"Attributes as dict","text":"<p>Attributes can also be specified as a <code>dict</code>. This is useful when using attributes that are reserved Python keywords (like <code>for</code> or <code>class</code>), when the attribute name contains a dash (<code>-</code>) or when you want to define attributes dynamically.</p> Using an attribute with a dash<pre><code>&gt;&gt;&gt; from htpy import div\n&gt;&gt;&gt; print(div({\"data-foo\": \"bar\"}))\n&lt;div data-foo=\"bar\"&gt;&lt;/div&gt;\n</code></pre> Using an attribute with a reserved keyword<pre><code>&gt;&gt;&gt; from htpy import label\n&gt;&gt;&gt; print(label({\"for\": \"myfield\"}))\n&lt;label for=\"myfield\"&gt;&lt;/label&gt;\n</code></pre>"},{"location":"usage/#boolean-attributes","title":"Boolean attributes","text":"<p>In HTML, boolean attributes such as <code>disabled</code> are considered \"true\" when they exist. Specifying an attribute as <code>True</code> will make it appear (without a value). <code>False</code> will make it hidden. This is useful and brings the semantics of <code>bool</code> to HTML.</p> True bool attribute<pre><code>&gt;&gt;&gt; from htpy import button\n&gt;&gt;&gt; print(button(disabled=True))\n&lt;button disabled&gt;&lt;/button&gt;\n</code></pre> False bool attribute<pre><code>&gt;&gt;&gt; from htpy import button\n&gt;&gt;&gt; print(button(disabled=False))\n&lt;button&gt;&lt;/button&gt;\n</code></pre>"},{"location":"usage/#conditionally-mixing-css-classes","title":"Conditionally mixing CSS classes","text":"<p>To make it easier to mix CSS classes, the <code>class</code> attribute accepts a list of class names or a dict. Falsey values will be ignored.</p> <pre><code>&gt;&gt;&gt; from htpy import button\n&gt;&gt;&gt; is_primary = True\n&gt;&gt;&gt; print(button(class_=[\"btn\", {\"btn-primary\": is_primary}]))\n&lt;button class=\"btn btn-primary\"&gt;&lt;/button&gt;\n&gt;&gt;&gt; is_primary = False\n&gt;&gt;&gt; print(button(class_=[\"btn\", {\"btn-primary\": is_primary}]))\n&lt;button class=\"btn\"&gt;&lt;/button&gt;\n&gt;&gt;&gt;\n</code></pre>"},{"location":"usage/#combining-modes","title":"Combining modes","text":"<p>Attributes via id/class shorthand, keyword arguments and dictionary can be combined:</p> Specifying attribute via multiple arguments<pre><code>&gt;&gt;&gt; from htyp import label\n&gt;&gt;&gt; print(label(\"#myid.foo.bar\", {'for': \"somefield\"}, name=\"myname\",))\n&lt;label id=\"myid\" class=\"foo bar\" for=\"somefield\" name=\"myname\"&gt;&lt;/label&gt;\n</code></pre>"},{"location":"usage/#iterating-of-the-output","title":"Iterating of the output","text":"<p>Iterating over a htpy element will yield the resulting contents in chunks as they are rendered:</p> <pre><code>&gt;&gt;&gt; from htpy import ul, li\n&gt;&gt;&gt; for chunk in ul[li[\"a\", \"b\"]]:\n...     print(f\"got a chunk: {chunk!r}\")\n...\ngot a chunk: '&lt;ul&gt;'\ngot a chunk: '&lt;li&gt;'\ngot a chunk: 'a'\ngot a chunk: 'b'\ngot a chunk: '&lt;/li&gt;'\ngot a chunk: '&lt;/ul&gt;'\n</code></pre>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":""},{"location":"#htpy-html-in-python","title":"htpy - HTML in Python","text":"<p>htpy is a library that makes writing HTML in plain Python fun and efficient, without a template language.</p> <p>Define HTML in Python: <pre><code>from htpy import body, h1, head, html, li, title, ul\n\nmenu = [\"egg+bacon\", \"bacon+spam\", \"eggs+spam\"]\n\nprint(\n    html[\n        head[title[\"Todays menu\"]],\n        body[\n            h1[\"Menu\"],\n            ul(\".menu\")[(li[item] for item in menu)],\n        ],\n    ]\n)\n</code></pre></p> <p>And get HTML: <pre><code>&lt;!DOCTYPE html&gt;\n&lt;html&gt;\n  &lt;head&gt;\n    &lt;title&gt;Todays menu&lt;/title&gt;\n  &lt;/head&gt;\n  &lt;body&gt;\n    &lt;h1&gt;Menu&lt;/h1&gt;\n    &lt;ul class=\"menu\"&gt;\n      &lt;li&gt;egg+bacon&lt;/li&gt;\n      &lt;li&gt;bacon+spam&lt;/li&gt;\n      &lt;li&gt;eggs+spam&lt;/li&gt;\n    &lt;/ul&gt;\n  &lt;/body&gt;\n&lt;/html&gt;\n</code></pre></p>"},{"location":"#motivation-for-this-project","title":"Motivation for this project","text":"<p>At Personalkollen, where htpy was originally developed we often found ourselves hitting walls when using classic templates. htpy was created to improve the productiveness and experience of generating HTML from a Python backend.</p>"},{"location":"#key-features","title":"Key features","text":"<ul> <li> <p>Leverage static types: Use mypy or pyright to type check your code.</p> </li> <li> <p>Great debugging: Avoid cryptic stack traces from templates. Use your favorite Python debugger.</p> </li> <li> <p>Easy to extend: There is no special way to define template tags/filters. Just call regular functions.</p> </li> <li> <p>Works with existing Python web framework: Works great with Django, Flask or any other Python web framework!</p> </li> <li> <p>Works great with htmx: htpy makes for a great experience when writing server rendered partials/components.</p> </li> <li> <p>Create reusable components: Define components, snippets, complex layouts/pages as regular Python variables or functions.</p> </li> <li> <p>Familiar concepts from React: React helped make it popular writing HTML with a programming language. htpy uses a lot of similar constructs.</p> </li> </ul>"},{"location":"#philosophy","title":"Philosophy","text":"<p>htpy generates HTML elements and attributes and provide a few helpers.</p> <p>htpy does not enforce any particular pattern or style to organize your pages, components and layouts. That does not mean that htpy cannot be used to build sophisticated web pages or applications.</p> <p>Rather the opposite: you are encouraged the leverage the power of Python to structure your project. Use modules, classes, functions, decorators, list comprehension, generators, conditionals, static typing and any other feature of Python to organize your components. This gives you a lot of power and makes htpy scale from a single small Flask project to bigger applications.</p> <p>Common patterns can give you some ideas that you can build upon yourself.</p>"},{"location":"#the-syntax","title":"The syntax","text":"<p>Child elements are specified using the <code>[]</code> syntax. This may look strange at first but it has some nice benefits. This clearly separates attributes from children elements and makes the code more readable. It is implemented using the <code>__getitem__</code> method, just like lists or dicts.</p>"},{"location":"#installation","title":"Installation","text":"<p>htpy is available on PyPI. You may install the latest version using pip: <pre><code>pip install htpy\n</code></pre></p>"},{"location":"#documentation","title":"Documentation","text":"<p>The full documentation is available at https://htpy.dev:  - Usage  - Common patterns  - Static typing  - Usage with Django  - Streaming of contents  - FAQ  - References</p>"},{"location":"common-patterns/","title":"Common patterns","text":"<p>htpy itself is a library that does not impose any particular structure for your code. You have the full power of Python functions, classes and modules at your disposal.</p> <p>General programming practices on how to structure modules, functions and classes apply to HTML generation with htpy.</p> <p>This page describes common scenarios and patterns that may help you structure your own project in a good way.</p>"},{"location":"common-patterns/#filemodule-structure","title":"File/module structure","text":"<p>It is generally a good idea to keep your HTML pages/components separate from HTTP request handling and \"business logic\".</p> <p>In Django, this means that the view function should not directly generate the HTML.</p> <p>Using a file named <code>components.py</code> can be a good idea. If you have many components, you may create a <code>components</code> package instead.</p> <p>Your component functions can accept arbitrary argument with the required data. It is a good idea to only use keyword arguments (put a <code>*</code> in the argument list to force keyword arguments):</p> views.py<pre><code>from django.http import HttpRequest, HttpResponse\n\nfrom .components import greeting_page\n\ndef greeting(request: HttpRequest) -&gt; HttpResponse:\n    return HttpResponse(greeting_page(\n        name=request.GET.get(\"name\", \"anonymous\"),\n    ))\n</code></pre> components.py<pre><code>from htpy import html, body, h1\n\ndef greeting_page(*, name: str) -&gt; Element:\n    return html[body[h1[f\"hi {name}!\"]]]\n</code></pre>"},{"location":"common-patterns/#using-a-base-layout","title":"Using a base layout","text":"<p>A common feature of template languages is to \"extend\" a base/parent template and specify placeholders. This can be achieved with a <code>base_layout</code> function:</p> components.py<pre><code>import datetime\n\nfrom htpy import body, div, h1, head, html, p, title, Node, Element\n\n\ndef base_page(*,\n    page_title: str | None = None,\n    extra_head: Node = None,\n    content: Node = None,\n    body_class: str | None = None,\n) -&gt; Element:\n    return html[\n        head[title[page_title], extra_head],\n        body(class_=body_class)[\n            content,\n            div(\"#footer\")[f\"Copyright {datetime.date.today().year} by Foo Inc.\"],\n        ],\n    ]\n\n\ndef index_page() -&gt; Element:\n    return base_page(\n        page_title=\"Welcome!\",\n        body_class=\"green\",\n        content=[\n            h1[\"Welcome to my site!\"],\n            p[\"Hello and welcome!\"],\n        ],\n    )\n\n\ndef about_page() -&gt; Element:\n    return base_page(\n        page_title=\"About us\",\n        content=[\n            h1[\"About us\"],\n            p[\"We love creating web sites!\"],\n        ],\n    )\n</code></pre>"},{"location":"common-patterns/#ui-components","title":"UI components","text":"<p>Creating higher level wrappers for common UI components can be a good idea to reduce repetition.</p> <p>Wrapping Bootstrap Modal could be achieved with a function like this:</p> Creating wrapper for Bootstrap Modal<pre><code>from markupsafe import Markup\n\nfrom htpy import Element, Node, button, div, h5, span\n\n\ndef bootstrap_modal(*, title: str, body: Node = None, footer: Node = None) -&gt; Element:\n    return div(\".modal\", tabindex=\"-1\", role=\"dialog\")[\n        div(\".modal-dialog\", role=\"document\")[\n            div(\".modal-content\")[\n                div(\".modal-header\")[\n                    div(\".modal-title\")[\n                        h5(\".modal-title\")[title],\n                        button(\n                            \".close\",\n                            type=\"button\",\n                            data_dismiss=\"modal\",\n                            aria_label=\"Close\",\n                        )[span(aria_hidden=\"true\")[Markup(\"&amp;times;\")]],\n                    ]\n                ],\n                div(\".modal-body\")[body],\n                footer and div(\".modal-footer\")[footer],\n            ]\n        ]\n    ]\n</code></pre> <p>You would then use it like this: <pre><code>from htpy import button, p\n\nprint(\n    bootstrap_modal(\n        title=\"Modal title\",\n        body=p[\"Modal body text goes here.\"],\n        footer=[\n            button(\".btn.btn-primary\", type=\"button\")[\"Save changes\"],\n            button(\".btn.btn-secondary\", type=\"button\")[\"Close\"],\n        ],\n    )\n)\n</code></pre></p>"},{"location":"django/","title":"Usage with Django","text":"<p>htpy is not tied to any specific web framework. Nonetheless, htpy works great when combined with Django. This page contains information and useful techniques on how to combine htpy and Django.</p>"},{"location":"django/#returning-a-htpy-response","title":"Returning a htpy response","text":"<p>htpy elements can be passed directly to <code>HttpResponse</code>:</p> views.py<pre><code>from django.http import HttpResponse\nfrom htpy import html, body, div\n\ndef my_view(request):\n    return HttpResponse(html[body[div[\"Hi Django!\"]]])\n</code></pre>"},{"location":"django/#using-htpy-as-part-of-an-existing-django-template","title":"Using htpy as part of an existing Django template","text":"<p>htpy elements are marked as \"safe\" and can be injected directly into Django templates. This can be useful if you want to start using htpy gradually in an existing template based Django project:</p> base.html<pre><code>&lt;html&gt;\n    &lt;head&gt;\n        &lt;title&gt;My Django Site&lt;/title&gt;\n    &lt;/head&gt;\n    &lt;body&gt;{{ content }}&lt;/body&gt;\n&lt;/html&gt;\n</code></pre> views.py<pre><code>from django.shortcuts import render\n\nfrom htpy import h1\n\n\ndef index(request):\n    return render(request, \"base.html\", {\n        \"content\": h1[\"Welcome to my site!\"],\n    })\n</code></pre>"},{"location":"django/#render-a-django-form","title":"Render a Django form","text":"<p>CSRF token, form widgets and errors can be directly used within htpy elements:</p> forms.py<pre><code>from django import forms\n\n\nclass MyForm(forms.Form):\n    name = forms.CharField()\n</code></pre> views.py<pre><code>from django.http import HttpRequest, HttpResponse\n\nfrom .components import my_form_page, my_form_success_page\nfrom .forms import MyForm\n\n\ndef my_form(request: HttpRequest) -&gt; HttpResponse:\n    form = MyForm(request.POST or None)\n    if form.is_valid():\n        return HttpResponse(my_form_success_page())\n\n    return HttpResponse(my_form_page(request, my_form=form))\n</code></pre> components.py<pre><code>from django.http import HttpRequest\nfrom django.template.backends.utils import csrf_input\n\nfrom htpy import Element, Node, body, button, form, h1, head, html, title\n\nfrom .forms import MyForm\n\n\ndef base_page(page_title: str, content: Node) -&gt; Element:\n    return html[\n        head[title[page_title]],\n        body[content],\n    ]\n\n\ndef my_form_page(request: HttpRequest, *, my_form: MyForm) -&gt; Element:\n    return base_page(\n        \"My form\",\n        form(method=\"post\")[\n            csrf_input(request),\n            my_form.errors,\n            my_form[\"name\"],\n            button[\"Submit!\"],\n        ],\n    )\n\n\ndef my_form_success_page() -&gt; Element:\n    return base_page(\n        \"Success!\",\n        h1[\"Success! The form was valid!\"],\n    )\n</code></pre>"},{"location":"django/#implement-custom-form-widgets-with-htpy","title":"Implement custom form widgets with htpy","text":"<p>You can implement a custom form widget directly with htpy like this:</p> widgets.py<pre><code>from django.forms import widgets\n\nfrom htpy import sl_input\n\n\nclass ShoelaceInput(widgets.Widget):\n    \"\"\"\n    A form widget using Shoelace's &lt;sl-input&gt; element.\n    More info: https://shoelace.style/components/input\n    \"\"\"\n\n    def render(self, name, value, attrs=None, renderer=None):\n        return str(sl_input(attrs, name=name, value=value))\n</code></pre>"},{"location":"faq/","title":"FAQ","text":""},{"location":"faq/#how-does-htpy-performance-compare-to-django-or-jinja-templates","title":"How does htpy performance compare to Django or Jinja templates?","text":"<p>The performance of HTML rendering is rarely the bottleneck in most web application. It is usually fast enough regardless of what method of constructing the HTML is being used.</p> <p>Given that it has been fast enough, there has not been much effort in optimizing htpy. It should be possible to significantly increase the effectiveness and we are open to contributions with benchmarks and speed improvements.</p> <p>That said, htpy is currently on par with Django templates when it comes to speed. Jinja2 is currently significantly faster than both Django templates and htpy. There is a small benchmark script in the repo that generates a table with 50 000 rows.</p>"},{"location":"faq/#can-htpy-generate-xmlxhtml","title":"Can htpy generate XML/XHTML?","text":"<p>No. Generating XML/XHTML is out of scope for this project. Use a XML library if you are looking to generate XML.</p> <p>htpy generates HTML, therefore \"void elements\" such as <code>&lt;br&gt;</code> does not include a trailing <code>/</code>.</p> <p>If you are looking to generate generic XML, <code>lxml.builder</code> could be a good alternative.</p>"},{"location":"faq/#does-not-generating-html-from-python-mean-mixing-concerns-between-presentation-and-business-logic","title":"Does not generating HTML from Python mean mixing concerns between presentation and business logic?","text":"<p>With a template language, putting HTML markup in separate files is enforced by design. Avoiding logic in the presentation layer is also mostly done by making the language very restrictive.</p> <p>It takes a little bit of planning and effort, but it is possible to have a nicely separated presentation layer that is free from logic. See Common patterns for more details on how you can structure your project.</p>"},{"location":"faq/#what-kind-of-black-magic-makes-from-htpy-import-whatever_element-work","title":"What kind of black magic makes <code>from htpy import whatever_element</code> work?","text":"<p>htpy uses the module level <code>__getattr__</code>. It was introduced in Python 3.7. It allows creating <code>Element</code> instances for any elements that are imported.</p>"},{"location":"faq/#why-does-htpy-not-provide-html-like-tag-syntax-with-angle-brackets-like-pyxl-and-jsx","title":"Why does htpy not provide HTML like tag syntax with angle brackets like pyxl and JSX?","text":"<p>htpy must be compatible with standard Python code formatters, editors and static type checkers. Unfortunately, it is not possible to support those workflows with a custom syntax without a massive effort to change those tools to support that syntax.</p>"},{"location":"references/","title":"References","text":""},{"location":"references/#projects-that-use-htpy","title":"Projects that use htpy","text":"<ul> <li>voterbowl.org - College students win prizes by checking if they are registered to vote: Github repository.</li> </ul>"},{"location":"references/#similar-libraries-and-tools","title":"Similar libraries and tools","text":"<p>htpy was heavily inspired by many other libraries that came before it.</p> <ul> <li>JSX/React - Made writing HTML in a programming language popular.</li> <li>pyxl, pyxl3, pyxl4 - Write HTML in Python with JSX-like syntax. Not actively maintained.</li> <li>htbuilder - Very similar to htpy but does not currently support automatic escaping.</li> <li>nevow.stan - Probably the earliest use of <code>[]</code> syntax for specifying children. Not actively maintained.</li> <li>breve - Another early implementation of HTML in Python,  Using getattr <code>[]</code> syntax for children. Not actively maintained.</li> <li>hyperscript - JavaScript library that also uses CSS selector-like syntax for specifying id and classes.</li> <li>hyperpython - A Python interpretation of hyperscript. Not actively maintained.</li> <li>h by Adam Johnson - Similar to htpy, uses call syntax (<code>()</code>) for attributes and getitem (<code>[]</code>) for children.</li> <li>lxml.builder - lxml's <code>E</code> allows creating XML/XHTML documents from Python.</li> </ul>"},{"location":"references/#articles-about-html-generation-without-templates","title":"Articles about HTML generation without templates","text":"<ul> <li>Jeff Atwood - You're Doing It Wrong - Stack Overflow co-founder Jeff Atwood</li> <li>Tavis Rudd - Throw out your templates - Tavis Rudd, creator of Python template language \"Cheetah\" argues for creating HTML without templates.</li> <li>David Ford - 80% of my coding is doing this (or why templates are dead) - Discusses various techniques for rendering HTML.</li> </ul>"},{"location":"static-typing/","title":"Static typing","text":"<p>htpy was designed to be used with static typing. Since you define all your own data/components with regular Python, a static type checker like mypy will catch errors like this:</p> <pre><code>class User:\n    def __init__(self, name: str):\n        self.name = name\n\n\ndef greeting(user: User) -&gt; Element:\n    return h1[f\"Hi {user.first_name.capitalize()}!]\n#                        ^^^^^^^^^^\n# mypy: error: \"User\" has no attribute \"first_name\"  [attr-defined]\n</code></pre>"},{"location":"static-typing/#autocompletion-of-html-elements","title":"Autocompletion of HTML elements","text":"<p>htpy ships with type annotations for all HTML elements. If your editor supports it, it will show you useful auto completions:</p> <p></p>"},{"location":"static-typing/#element-and-voidelement-classes","title":"<code>Element</code> and <code>VoidElement</code> classes","text":"<p>The base types/classes in htpy are <code>Element</code> and <code>VoidElement</code>. <code>Element</code> are all regular HTML elements that can have children such as <code>&lt;div&gt;</code>, <code>&lt;span&gt;</code> and <code>&lt;table&gt;</code>. <code>VoidElement</code> are HTML void element which cannot have children such as <code>&lt;img&gt;</code>, <code>&lt;input&gt;</code> and <code>&lt;br&gt;</code>.</p> <p>Use <code>Element</code> as the return type when you want to always return an element.</p> <pre><code>from typing import Literal\n\nfrom htpy import Element, span\n\n\ndef bootstrap_badge(\n    text: str,\n    style: Literal[\"primary\", \"success\", \"danger\"] = \"primary\",\n) -&gt; Element:\n    return span(f\".badge.text-bg-{style}\")[text]\n</code></pre>"},{"location":"static-typing/#node","title":"Node","text":"<p><code>Node</code> is a type alias for all possible objects that can be used as a child node. See the source for the exact definition that defines all kinds of nodes that can be children of an element. This is a wider type than <code>Element</code> since child nodes can be str, markup, None, iterables or callables.</p> <p>Use <code>Node</code> when you want to create a wrapper function to be flexible with what you accept. This function will accept both a str or some other element to be passed as <code>contents</code>:</p> <pre><code>from htpy import Element, Node, div\n\ndef bootstrap_alert(contents: Node) -&gt; Element:\n    return div(\".alert\", role=\"alert\")[contents]\n</code></pre>"},{"location":"streaming/","title":"Streaming of contents","text":"<p>Internally, htpy is built with generators. Most of the time, you would render the full page with <code>str()</code>, but htpy can also incrementally generate pages which can then be streamed to the browser. If your page uses a database or other services to retrieve data, you can sending the first part of the page to the client while the page is being generated.</p> <p>Note</p> <p>Streaming requires a bit of discipline and care to get right. You need to ensure to avoid doing too much work up front and use lazy constructs such as generators and callables. Most of the time, rendering the page without streaming will be the easiest way to get going. Streaming can give you improved user experience from faster pages/rendering.</p> <p>This video shows what it looks like in the browser to generate a HTML table with Django StreamingHttpResponse (source code):</p> <p>This example simulates a (very) slow fetch of data and shows the power of streaming: The browser loads CSS and gradually shows the contents. By loading CSS files in the <code>&lt;head&gt;</code> tag before dynamic content, the browser can start working on loading the CSS and styling the page while the server keeps generating the rest of the page.</p>"},{"location":"streaming/#using-generators-and-callables-as-children","title":"Using generators and callables as children","text":"<p>Django's querysets are lazily evaluated. They will not execute a database query before their value is actually needed.</p> <p>This example shows how this property of Django querysets can be used to create a page that streams objects: <pre><code>from django.http import StreamingHttpResponse\nfrom htpy import ul, li\n\nfrom myapp.models import Article\n\ndef article_list(request):\n    return StreamingHttpResponse(ul[\n        (li[article.title] for article in Article.objects.all())\n    ])\n</code></pre></p>"},{"location":"streaming/#using-callables-to-delay-evalutation","title":"Using callables to delay evalutation","text":"<p>Pass a callable that does not accept any arguements as child to delay the evaluation.</p> <p>This example shows how the page starts rendering and outputs the <code>&lt;h1&gt;</code> tag and then calls <code>calculate_magic_number</code>.</p> <pre><code>import time\nfrom htpy import div, h1\n\ndef calculate_magic_number() -&gt; str:\n    time.sleep(1)\n    print(\"  (running the complex calculation...)\")\n    return \"42\"\n\nelement = div[\n    h1[\"Welcome to my page\"],\n    \"The magic number is \",\n    calculate_magic_number,\n]\n\nfor chunk in element:\n    print(chunk)\n</code></pre> <p>Output: <pre><code>&lt;div&gt;\n&lt;h1&gt;\nWelcome to my page\n&lt;/h1&gt;\nThe magic number is\n42    # &lt;-- Appears after 3 seconds\n&lt;/div&gt;\n</code></pre></p> <p>You may use <code>lambda</code> to create a function without arguments to make a an expression lazy:</p> <pre><code>from htpy import div, h1\n\n\ndef fib(n: int) -&gt; int:\n    if n == 0:\n        return 0\n    elif n == 1:\n        return 1\n    else:\n        return fib(n - 1) + fib(n - 2)\n\n\nprint(\n    div[\n        h1[\"Fibonacci!\"],\n        \"fib(20)=\",\n        lambda: str(fib(20)),\n    ]\n)\n# output: &lt;div&gt;&lt;h1&gt;Fibonacci!&lt;/h1&gt;fib(12)=6765&lt;/div&gt;\n</code></pre>"},{"location":"usage/","title":"Usage","text":"<p>Elements are imported directly from the <code>htpy</code> module as their name. HTML attributes are specified by parenthesis (<code>()</code> / \"call\"). Children are specified using square brackets (<code>[]</code> / \"getitem\").</p> <pre><code>&gt;&gt;&gt; from htpy import div\n&gt;&gt;&gt; print(div(id=\"hi\")[\"Hello!\"])\n&lt;div id=\"hi\"&gt;Hello!&lt;/div&gt;\n</code></pre>"},{"location":"usage/#elements","title":"Elements","text":"<p>Children can be strings, markup, other elements or lists/iterators.</p> <p>Elements can be arbitrarily nested: Nested elements<pre><code>&gt;&gt;&gt; from htpy import article, section, p\n&gt;&gt;&gt; print(section[article[p[\"Lorem ipsum\"]]])\n&lt;section&gt;&lt;article&gt;&lt;p&gt;Lorem ipsum&lt;/p&gt;&lt;/article&gt;&lt;/section&gt;\n</code></pre></p>"},{"location":"usage/#textstrings","title":"Text/strings","text":"<p>It is possible to pass a string directly: Using a string as children<pre><code>&gt;&gt;&gt; from htpy import h1\n&gt;&gt;&gt; print(h1[\"Welcome to my site!\"])\n&lt;h1&gt;Welcome to my site!&lt;/h1&gt;\n</code></pre></p> <p>Strings are automatically escaped to avoid XSS vulnerabilities. It is convenient and safe to directly insert variable data via f-strings:</p> <pre><code>&gt;&gt;&gt; from htpy import h1\n&gt;&gt;&gt; user_supplied_name = \"bobby &lt;/h1&gt;\"\n&gt;&gt;&gt; print(h1[f\"hello {user_supplied_name}\"])\n&lt;h1&gt;hello bobby &amp;lt;/h1&amp;gt;&lt;/h1&gt;\n</code></pre>"},{"location":"usage/#conditional-rendering","title":"Conditional rendering","text":"<p><code>None</code> will not render anything. This can be useful to conditionally render some content.</p> Conditional rendering<pre><code>&gt;&gt;&gt; from htpy import div, b\n&gt;&gt;&gt; error = None\n\n&gt;&gt;&gt; # No &lt;b&gt; tag will be rendered since error is None\n&gt;&gt;&gt; print(div[error and b[error]])\n&lt;div&gt;&lt;/div&gt;\n\n&gt;&gt;&gt; error = 'Enter a valid email address.'\n&gt;&gt;&gt; print(div[error and b[error]])\n&lt;div&gt;&lt;b&gt;Enter a valid email address.&lt;/b&gt;&lt;/div&gt;\n\n# Inline if/else can also be used:\n&gt;&gt;&gt; print(div[b[error] if error else None])\n&lt;div&gt;&lt;b&gt;Enter a valid email address.&lt;/b&gt;&lt;/div&gt;\n</code></pre>"},{"location":"usage/#loops-iterating-over-children","title":"Loops / iterating over children","text":"<p>You can pass a list, tuple or generator to generate multiple children:</p> Iterate over a generator<pre><code>&gt;&gt;&gt; from htpy import ul, li\n&gt;&gt;&gt; print(ul[(li[letter] for letter in \"abc\")])\n&lt;ul&gt;&lt;li&gt;a&lt;/li&gt;&lt;li&gt;b&lt;/li&gt;&lt;li&gt;c&lt;/li&gt;&lt;/ul&gt;\n</code></pre> <p>Note</p> <p>The generator will be lazily evaluated when rendering the element, not directly when the element is constructed. See Streaming for more information.</p> <p>A <code>list</code> can be used similar to a JSX fragment:</p> Render a list of child elements<pre><code>&gt;&gt;&gt; from htpy import div, img\n&gt;&gt;&gt; my_images = [img(src=\"a.jpg\"), img(src=\"b.jpg\")]\n&gt;&gt;&gt; print(div[my_images])\n&lt;div&gt;&lt;img src=\"a.jpg\"&gt;&lt;img src=\"b.jpg\"&gt;&lt;/div&gt;\n</code></pre>"},{"location":"usage/#custom-elements-web-components","title":"Custom elements / web components","text":"<p>Custom elements / web components are HTML elements that contains at least one dash (<code>-</code>). Since <code>-</code> cannot be used in Python identifiers, use underscore (<code>_</code>) instead:</p> Using custom elements<pre><code>&gt;&gt;&gt; from htpy import my_custom_element\n&gt;&gt;&gt; print(my_custom_element['hi!'])\n&lt;my-custom-element&gt;hi!&lt;/my-custom-element&gt;\n</code></pre>"},{"location":"usage/#injecting-markup","title":"Injecting markup","text":"<p>If you have HTML markup that you want to insert without further escaping, wrap it in <code>Markup</code> from the markupsafe library. markupsafe is a dependency of htpy and is automatically installed:</p> Injecting markup<pre><code>&gt;&gt;&gt; from htpy import div\n&gt;&gt;&gt; from markupsafe import Markup\n&gt;&gt;&gt; print(div[Markup(\"&lt;foo&gt;&lt;/foo&gt;\")])\n&lt;div&gt;&lt;foo&gt;&lt;/foo&gt;&lt;/div&gt;\n</code></pre> <p>If you are generate Markdown and want to insert it into an element, use <code>Markup</code>: Injecting generated markdown<pre><code>&gt;&gt;&gt; from markdown import markdown\n&gt;&gt;&gt; from markupsafe import Markup\n&gt;&gt;&gt; from htpy import div\n&gt;&gt;&gt; print(div[Markup(markdown('# Hi'))])\n&lt;div&gt;&lt;h1&gt;Hi&lt;/h1&gt;&lt;/div&gt;\n</code></pre></p>"},{"location":"usage/#html-doctype","title":"HTML Doctype","text":"<p>The HTML doctype is automatically prepended to the <code>&lt;html&gt;</code> tag:</p> <pre><code>&gt;&gt;&gt; from htpy import html\n&gt;&gt;&gt; print(html)\n&lt;!doctype html&gt;&lt;html&gt;&lt;/html&gt;\n</code></pre>"},{"location":"usage/#attributes","title":"Attributes","text":"<p>HTML attributes are defined by calling the element. They can be specified in a couple of different ways.</p>"},{"location":"usage/#elements-without-attributes","title":"Elements without attributes","text":"<p>Some elements do not have attributes, they can be specified by just the element itself:</p> <pre><code>&gt;&gt;&gt; from htpy import hr\n&gt;&gt;&gt; print(hr)\n&lt;hr&gt;\n</code></pre>"},{"location":"usage/#keyword-arguments","title":"Keyword arguments","text":"<p>Attributes can be specified via keyword arguments:</p> <pre><code>&gt;&gt;&gt; from htpy import img\n&gt;&gt;&gt; print(img(src=\"picture.jpg\"))\n&lt;img src=\"picture.jpg\"&gt;\n</code></pre> <p>In Python, <code>class</code> and <code>for</code> cannot be used as keyword arguments. Instead, they can be specified as <code>class_</code> or <code>for_</code> when using keyword arguments:</p> <pre><code>&gt;&gt;&gt; from htpy import label\n&gt;&gt;&gt; print(label(for_=\"myfield\"))\n&lt;label for=\"myfield\"&gt;&lt;/label&gt;\n</code></pre> <p>Attributes that contains dashes <code>-</code> can be specified using underscores: <pre><code>&gt;&gt;&gt; from htpy import form\n&gt;&gt;&gt; print(form(hx_post=\"/foo\"))\n&lt;form hx-post=\"/foo\"&gt;&lt;/form&gt;\n</code></pre></p>"},{"location":"usage/#idclass-shorthand","title":"id/class shorthand","text":"<p>Defining <code>id</code> and <code>class</code> attributes is common when writing HTML. A string shorthand that looks like a CSS selector can be used to quickly define id and classes:</p> Define id<pre><code>&gt;&gt;&gt; from htpy import div\n&gt;&gt;&gt; print(div(\"#myid\"))\n&lt;div id=\"myid\"&gt;&lt;/div&gt;\n</code></pre> Define multiple classes<pre><code>&gt;&gt;&gt; from htpy import div\n&gt;&gt;&gt; print(div(\".foo.bar\"))\n&lt;div id=\"foo bar\"&gt;&lt;/div&gt;\n</code></pre> Combining both id and classes<pre><code>&gt;&gt;&gt; from htpy import div\n&gt;&gt;&gt; print(div(\"#myid.foo.bar\"))\n&lt;div id=\"myid\" class=\"foo bar\"&gt;&lt;/div&gt;\n</code></pre>"},{"location":"usage/#attributes-as-dict","title":"Attributes as dict","text":"<p>Attributes can also be specified as a <code>dict</code>. This is useful when using attributes that are reserved Python keywords (like <code>for</code> or <code>class</code>), when the attribute name contains a dash (<code>-</code>) or when you want to define attributes dynamically.</p> Using an attribute with a dash<pre><code>&gt;&gt;&gt; from htpy import div\n&gt;&gt;&gt; print(div({\"data-foo\": \"bar\"}))\n&lt;div data-foo=\"bar\"&gt;&lt;/div&gt;\n</code></pre> Using an attribute with a reserved keyword<pre><code>&gt;&gt;&gt; from htpy import label\n&gt;&gt;&gt; print(label({\"for\": \"myfield\"}))\n&lt;label for=\"myfield\"&gt;&lt;/label&gt;\n</code></pre>"},{"location":"usage/#boolean-attributes","title":"Boolean attributes","text":"<p>In HTML, boolean attributes such as <code>disabled</code> are considered \"true\" when they exist. Specifying an attribute as <code>True</code> will make it appear (without a value). <code>False</code> will make it hidden. This is useful and brings the semantics of <code>bool</code> to HTML.</p> True bool attribute<pre><code>&gt;&gt;&gt; from htpy import button\n&gt;&gt;&gt; print(button(disabled=True))\n&lt;button disabled&gt;&lt;/button&gt;\n</code></pre> False bool attribute<pre><code>&gt;&gt;&gt; from htpy import button\n&gt;&gt;&gt; print(button(disabled=False))\n&lt;button&gt;&lt;/button&gt;\n</code></pre>"},{"location":"usage/#conditionally-mixing-css-classes","title":"Conditionally mixing CSS classes","text":"<p>To make it easier to mix CSS classes, the <code>class</code> attribute accepts a list of class names or a dict. Falsey values will be ignored.</p> <pre><code>&gt;&gt;&gt; from htpy import button\n&gt;&gt;&gt; is_primary = True\n&gt;&gt;&gt; print(button(class_=[\"btn\", {\"btn-primary\": is_primary}]))\n&lt;button class=\"btn btn-primary\"&gt;&lt;/button&gt;\n&gt;&gt;&gt; is_primary = False\n&gt;&gt;&gt; print(button(class_=[\"btn\", {\"btn-primary\": is_primary}]))\n&lt;button class=\"btn\"&gt;&lt;/button&gt;\n&gt;&gt;&gt;\n</code></pre>"},{"location":"usage/#combining-modes","title":"Combining modes","text":"<p>Attributes via id/class shorthand, keyword arguments and dictionary can be combined:</p> Specifying attribute via multiple arguments<pre><code>&gt;&gt;&gt; from htyp import label\n&gt;&gt;&gt; print(label(\"#myid.foo.bar\", {'for': \"somefield\"}, name=\"myname\",))\n&lt;label id=\"myid\" class=\"foo bar\" for=\"somefield\" name=\"myname\"&gt;&lt;/label&gt;\n</code></pre>"},{"location":"usage/#iterating-of-the-output","title":"Iterating of the output","text":"<p>Iterating over a htpy element will yield the resulting contents in chunks as they are rendered:</p> <pre><code>&gt;&gt;&gt; from htpy import ul, li\n&gt;&gt;&gt; for chunk in ul[li[\"a\", \"b\"]]:\n...     print(f\"got a chunk: {chunk!r}\")\n...\ngot a chunk: '&lt;ul&gt;'\ngot a chunk: '&lt;li&gt;'\ngot a chunk: 'a'\ngot a chunk: 'b'\ngot a chunk: '&lt;/li&gt;'\ngot a chunk: '&lt;/ul&gt;'\n</code></pre>"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index 3a126bf864f25669e271137ac713f7204077d3cb..0a3cb06f8d5b11e4d038735987c442e409be0842 100644
GIT binary patch
delta 13
Ucmb=gXP58h;Lw`mJ(0Zv02;po;Q#;t

delta 13
Ucmb=gXP58h;NZ2<o5)@P02jRjM*si-