Package: hotmetal
hotmetalA tiny HTML generatorInstallationInstall from PyPIpip install hotmetalWhat is hotmetal?hotmetalis a tiny library that lets you generate HTML directly from Python primitive data structures without using any sort of text-based template language. It is an alternative toJinja,Django templates, etc. It is loosely inspired by ideas fromReact,Mithriland other JavaScript libraries. It is also similar toHyperpython, but it's even simpler. It attempts to stay as close as possible tothe HTML spec.How does it work?First, reada quick introduction to HTML. Go on, it's important.An HTML document represents a tree of nodes. Each node (called an "element") consists of exactly three things: atag name(such asdiv,portitle), a collection ofattributes(a mapping of keys to values) and a list ofchildren(other elements or text nested inside the node).So: that's atag name(a string),attributes(a mapping), andchildren(a list).The simplest way to represent that structure in Python is a tuple of three elements:("",{},[])Here's an example of an anchor element (a link) with a text node inside it:link_element=("a",{"href":"somewhere.html"},["click me!"])Here's an example of a full HTML document (note that theDOCTYPEis missing, we'll come back to that later):document=("html",{"lang":"en"},[("head",{},[("title",{},["Sample page"])]),("body",{},[("h1",{},["Sample page"]),("p",{},["This is a ",("a",{"href":"demo.html"},["simple"])," sample"],),],),],)Once we've created a structure like this, we can usehotmetaltorenderit into a string:>>>fromhotmetalimportrender>>>print(render(document,indent=2))<html lang="en"><head><title>Sample page</title></head><body><h1>Sample page</h1><p>This is a<a href="demo.html">simple</a>sample</p></body></html>In essence,that's it. That's all thathotmetaldoes.ComponentsBut this all looks pretty fiddly, right? If you always needed to painstakingly assemble a huge tree of nested tuples to render every page on your web app, that would be annoyingly verbose and difficult to read.So here's the clever bit: instead,write functions with meaningful names that return element nodes, and build your web app with those. Let's call these functions that return nodescomponents(if you're familiar with React you might see where this is going).defmenu_item(href,text):return("li",{},[("a",{"href":href},[text])])defmenu(items):return("ul",{},[menu_item(href,text)forhref,textinitems])menu_node=menu([("/home/","Home"),("/blog/","Blog"),])... and so on, right down to the<html>.For a good explanation of some useful patterns to use when composing markup in this way, have a read of the React docs onComposition vs Inheritance. The concepts should be directly transferable.FragmentsEarlier, we brushed over the fact that the example we used was missing itsDOCTYPE. That's because the root of an HTML document is really two things: the<html>element itself, and before ittheDOCTYPEpreamble. We can express this structure inhotmetalby using afragment. Again, thesame concept exists in React, but the syntax is simpler inhotmetal. Just use a node with an empty tag name and attributes:fromhotmetalimportsafedocument=("",{},[safe("<!DOCTYPE html>"),("html",{"lang":"en"},[...],# head, body etc),],)When rendering,hotmetalwill "optimise away" the empty node, leaving only the two consecutive child nodes. This is also often useful during component composition: you might create a component that accepts a single child node as an argument, but you can still pass it a list of multiple nodes by wrapping them in a fragment.But what's thatsafething about?EscapingYou have to be careful when generating HTML. If any part of your markup or text content can be supplied by a user (which is common in web applications), you may be vulnerable to cross-site scripting (XSS) attacks. The Django docs havea good explanation of why this is important.By default,hotmetalescapeseverystring it renders using the same approach as Python's built-inhtml.escapefunctionality. So you can add user-generated content to your documents without worrying.If you want to add some raw markup that youknowis safe (some hand-crafted HTML, or the rendered output of another templating system that already escapes unsafe content) then you can wrap those strings in thesafefunction. See the above section for an example.ContextTheReact docs on contextsay:Context provides a way to pass data through the component tree without having to pass props down manually at every level.Exactly the same concept exists inhotmetal, but again the implementation is a little simpler.If you're familiar with the concept of context in Django or Jinja templates, this isnot quite the same thing. In those languages, context is theonlyway to pass variables into a template. Inhotmetalthere's no need to do this: you can just create component functions that accept arguments:defheader(title):return("h1",{},[title])So where would you use context? Just like in React:Context is primarily used when some data needs to be accessible by many components at different nesting levels. Apply it sparingly because it makes component reuse more difficult.A good example might be if you need to access therequestobject or the currently logged in user somewhere deep in your component tree, but you don't want to explicitly pass it down through the component hierarchy from the root.To use context inhotmetal, you pass a dictionary to therenderfunction:render(some_node,context={"logged_in_user_email":"hello@example.com"})To access the context from inside the tree, replace any node in the tree with acallable(a named function or a lambda) that returns that node. During rendering,hotmetalwill call your function, passing thecontextdictionary as its single argument.defcurrent_user_panel():returnlambdacontext:("p",{},[f"Hello,{context['logged_in_user_email']}"],)Indentation controlTherenderfunction takes anindentargument, which is a integer used to control how many spaces are used as indentation in the generated HTML. The default is 0, meaning the entire HTML string will be returned on a single line. You may wish to use (say)indent=2for development, andindent=0for production (essentially minifying your HTML).Generating class namesA function is provided that can be used to generate strings of class names based on various arguments. This is closely based on theclassnamesJavaScript library.fromhotmetal.utils.classnamesimportclassnamesdefheader(title):title_is_green=title.lower()=="green"return("h1",{"class":classnames("title",{"green":title_is_green})},[title])Testing toolsWhen writing tests for components, it's often useful to be able to search through a tree to find particular nodes and make assertions about them. To help with this,hotmetalprovides afindfunction, which takes an iterable of nodes and a predicate callable, and returns a generator that yields nodes that match the predicate (using depth-first pre-order traversal of the nodes, much like the browser'squerySelectorAllfunction).For example, given the following component:defheader(title):return("div",{"class":"header"},[("h1",{},[title])])You could write a test something like this:fromhotmetal.utils.findimportfindfromunittestimportTestCaseclassHeaderTestCase(TestCase):deftest_title_appears_correctly_inside_h1(self):node=header("hello world")h1_elements=list(find([node],lambdanode:isinstance(node,tuple)andnode[0]=="h1"))self.assertEqual(len(h1_elements),1)h1=h1_elements[0]children=node[2]self.assertEqual(children,["hello world"])Here, alambdais being used to match against each node in the tree, which returnsTrueorFalsedepending on whether that node should be included in the results. When writing the predicate, remember that thenodeargument may be a tree node (a tuple), or a text node (a string), or a function (for nodes that requirecontext, see above).As an alternative to writing thepredicatefunction yourself, a selection of functions are provided that address common requirements for finding nodes. Thefindline in the above example can be rewritten like this:h1_elements=list(find([node],tag_is("h1")))A full list of these predicate functions is below:hotmetal.utils.find.tag_is(tag)Returns a predicate function that matches nodes by tag name:find(nodes, tag_is("h1"))hotmetal.utils.find.id_is(id)Returns a predicate function that matches nodes by the value of the ID attribute:find(nodes, id_is("header"))hotmetal.utils.find.has_class(cls)Returns a predicate function that matches nodes by a particular class name within theclassattribute:find(nodes, has_class("someclass"))hotmetal.utils.find.has_attr(attr)Returns a predicate function that matches nodes that have the given attribute, with any value:find(nodes, has_attr("href"))hotmetal.utils.find.has_attr_with_value(attr, value)Returns a predicate function that matches nodes that have the given attribute, and also the value of that attribute is equal to the given value:find(nodes, has_attr_with_value("type", "hidden"))hotmetal.utils.find.attr_value_matches(attr, predicate)Returns a predicate function that matches nodes that have the given attribute, and the value of that attribute matches the given predicate function:find(nodes, attr_value_matches("class", lambda value: "background-" in value))hotmetal.utils.find.text_contains(text)Returns a predicate function that matches text nodes (strings) that contain the given text:find(nodes, text_contains("hello world"))hotmetal.utils.find.any_immediate_child_matches(predicate)Returns a predicate function that matches nodes with at least one direct child node that matches the given predicate:find(nodes, any_immediate_child_matches(text_contains("hello world")))hotmetal.utils.find.or_(*predicates)Given multiple predicate functions, returns a predicate function that matches nodes that match any of the predicates:find(nodes, or_(tag_is("h1"), id_is("title")))hotmetal.utils.find.and_(*predicates)Given multiple predicate functions, returns a predicate function that matches nodes that match all of the predicates:find(nodes, and_(tag_is("input"), has_attr_with_value("type", "text")))hotmetal.utils.find.not_(predicate)Inverts a predicate function:find(nodes, and_(tag_is("input"), not_(has_attr_with_value("type", "hidden")))hotmetal.utils.find.TAGhotmetal.utils.find.ATTRShotmetal.utils.find.CHILDRENThese three constants are simply the indices into a node for each component. They enhance readability: instead ofchildren = node[2]you can saychildren = node[CHILDREN]