Coming from Hiccup

Hyccup can be considered as Hiccup ported to Hy and Python. However, some API elements must adapted to Python’s mindset. This page shows the main difference between this library and Hiccup.


As keywords are not a Python concept and as Hy is very close to Python, they cannot be used efficiently. Thus, we rely on strings or symbols instead.

That is to say,

[:div#an-id {:class "a-class"} "some text"]

must be changed to

["div#an-id" {"class" "a-class"} "some text"] ;; with strings
['div#an-id {'class "a-class"} "some text"] ;; with symbols

HTML Options

Instead of passing options in a dictionary as the first argument:

(html {:mode "xhtml" :espace-strings? true} [:p "example"])

Pass them as keyword arguments (or use unpacking):

(html ['p "example"] :mode "xhtml" :espace-strings True)
(html ['p "example"] #** {'mode "xhtml" 'espace-strings True})
(html ['p "example"] (unpack-mapping {'mode "xhtml" 'espace-strings True}))

Note that the escape flag argument has no ? suffix in Hyccup.


The following form is valid in Hiccup:

(html (list [:p "some text"] [:p "another p"]))

In Hyccup, just chain the elements or use unpacking (as we already use lists to represent elements, where Hiccup use Clojure vectors).

(html ['p "some text"] ['p "another p"]))
(html #* [['p "some text"] ['p "another p"]]))
(html (unpack-iterable [['p "some text"] ['p "another p"]])))

You can also use iterators:

(html (iter [['p "some text"] ['p "another p"]]))

with-* macros

with-base-url and with-encoding are replaced by context managers.


=> (with-base-url "/foo/"
     (to-str (to-uri "/bar")))
=> (with-encoding "UTF-8"
     (url-encode {:iroha "いろは"}))


=> (with [(base-url "/foo/")]
     (to-str (to-uri "/bar")))
=> (with [(encoding "UTF-8")]
     (url-encode {'iroha "いろは"}))

defhtml and defelem

defhtml and defelem macros from Hiccup is available in two modules, macros for Hy and decorators for Python:

=> (require [hyccup.defmacros [defhtml defelem]])
=> (defelem link-to [link text]
...  ['a {'href link} text])
=> (link-to {'class "some-class"} "" "Pycolore" )
['a {'href "" 'class "some-class"} "Pycolore"]
=> (defhtml linked-section-html [link text content]
...  ['section
...    ['h1 (link-to link text)]
...    ['p content]])
=> (linked-section-html "" "Pycolore" "Lorem Ipsum")
   <a href="">Pycolore</a>
   Lorem Ipsum
=> (defhtml {"mode" "xml"} ;; you can pass HTML options as first form to defhtml
     some-html []
=> (some-html)
"<p />"
>>> from hyccup.defdecos import defelem, defhtml
>>> @defhtml # pass output of function to html()
... @defelem # merge first arg dict with attributes
... def link_to(link: str, text: str):
...     return ["a", {"href": link}, text]
>>> link_to({"class": "some-class"}, "", "Pycolore")
'<a class="some-class" href="">Pycolore</a>'
>>> @defhtml(mode="html") # it is possible to pass HTML options to defhtml
... def paragraph(content=""):
...     return ["p", content]
>>> paragraph()