ptag

generate html/svg tags hierarchy with context manager

---

Note

The repository has been archived. Initially, using a context manager to construct the DOM structure seemed "Pythonic" syntactically. However, I later discovered that this approach introduced an additional layer of complexity and negatively impacted performance at a larger scale. As a result, I developed tagit, a much simpler and more performant DOM library. It exclusively handles string inputs and outputs without complex features, while still managing the DOM structure purely within Python code.

• use ⭐️ context manager ⭐️ to create tag hierarchy
• create value-less(boolean) attributes with positional argument
  • handy for using with UnoCSS attributify mode
• all standard html and svg elements are exported as functions
• pure python, no external dependencies
• high test coverage

Quick Start

• Installation: pip install ptag
• base signature
  • element(content = None, *args, **kwargs) -> Tag

# common elements
from ptag import div, img, p, ul, li, label, input_,
# for creating custom element
from ptag import Tag  
# for pretty print
from ptag import prettify  

# empty tag
print(div())
# <div />

# None content is ignored
print(div(None))
# <div />

# empty string content creates closing tag
print(div(""))
# <div></div>

# tag as content
print(div(img(src="url"), id="bar"))  
# <div id="bar"><img src="url"/></div>

# content mix with strings and tags
print(div(["foo", img(src="url"), "bar")])
# <div>foo<img src="url"/>bar</div>

• use with context manager

with ul() as bullets:
    li("foo")
    li("bar")

print(bullets)
# <ul><li>foo</li><li>bar</li></ul>

• pretty print

print(bullets.prettify())
# <ul>
#     <li>foo</li>
#     <li>bar</li>
# </ul>

• use trailing underscore to work around python keyword and built-in functions
• attributes:
  • class_ -> class
  • for_ -> for
• elements:
  • del_ -> del
  • input_ -> input
  • map_ -> map
  • object_ -> object

print(label("foo", for_="bar"))
# <label for="bar">foo</label>

print(input_(None, class_="foo", name="bar", type="checkbox", value="baz"))
# <input name="bar" type="checkbox" value="baz"/>

• position args -> value-less attribute.
  • boolean attribute: eg. checked, disabled, selected
  • assign tailwind classes with UnoCSS attributify mode

print(div("foo", "clear-both", "m-2", "rounded", id="baz"))
# <div clear-both m-2 rounded id="baz">foo</div>

• keyword argument with value None is ignored

tag = div(None, "m-2", "rounded", id="baz", style=None) 
print(tag)  
# <div m-2 rounded id="baz" />

• append content and attributes to existing tag

tag = div()
tag.affix(p("bar"), "m-2", "rounded", id="baz") 
print(tag)  
# <div m-2 rounded id="baz"><p>bar</p></div>

• create custom element
• signature:
  • Tag(name: str, content = None, *args, **kwargs) -> str

my_tag = Tag("MyTag", "foo", "bar", "corge", id="baz", class_="qux")
print(my_tag)  
# <MyTag bar corge id="baz" class="qux">foo</MyTag>

• more examples could be found in tests package

Limitations

• prettify() method doesn't support attribute without value
  • use kwargs instead of positional args if prettifying is needed
  • eg. selected -> selected=""

Need Help?

• github issue
• x.com posts
• contact the author