Tag types

htmltools.Tag

Tag(_name, *args, _add_ws=True, **kwargs)

The HTML tag class.

A Tag object consists of a name, attributes, and children. The name is a string, the attributes are held in a TagAttrDict object, and the children are held in a TagList object.

This class usually should not be instantiated directly. Instead, use the tag wrapper functions in htmltools.tags, like div() or a().

Parameters

**_name** : str

The tag’s name.

*args : TagChild | TagAttrs = ()

Children for the tag.

**_add_ws** : TagAttrValue = True

A bool indicating whether to add whitespace surrounding the tag (see Note for details).

**kwargs : TagAttrValue = {}

Attributes for the tag.

Attributes

name : str

The tag’s name.

attrs : TagAttrDict

The tag’s attributes.

children : ‘TagList’

The tag’s children.

Note

The _add_ws parameter controls whether whitespace is added around the tag. Inline tags (like span() and a()) default to False and block tags (like div() and p()) default to True.

When a tag with _add_ws=True is rendered to HTML, whitespace (including indentation) is added before the opening tag (like <div>), after the closing tag (like </div>), and also between the opening tag and its first child. This usually results in formatting that is easier to read.

The only times that whitespace is not added around tags is when two sibling tags have _add_ws=False, or when a tag and its first child both have _add_ws=False. Bare strings are treated as children with _add_ws=False.

If you need fine control over whitespace in the output HTML, you can create tags with _add_ws=False and manually add whitespace, like div("\n", span("a"), _add_ws=False).

Examples

>>> from htmltools import div
>>> x = div("hello", id="foo", class_="bar")
>>> x
<div id="foo" class="bar">hello</div>
>>> x.show()

Methods

Name	Description
add_class	Add a class value to the HTML class attribute.
add_style	Add a style value(s) to the HTML style attribute.
append	Append tag children to the end of the list.
extend	Extend the children by appending an iterable of children.
insert	Insert tag children before a given index.
remove_class	Remove a class value from the HTML class attribute.
tagify	Convert any tagifiable children to TagifiedTag/TagifiedTagList objects.

add_class

Tag.add_class(class_, *, prepend=False)

Add a class value to the HTML class attribute.

Parameters

class_ : str

The class name to add.

prepend : bool = False

Bool that determines if the class is added to the beginning or end of the class attribute.

Returns

: TagT

The modified tag.

add_style

Tag.add_style(style, *, prepend=False)

Add a style value(s) to the HTML style attribute.

Parameters

style : str | HTML

CSS properties and values already properly formatted. Each should already contain trailing semicolons.

prepend : bool = False

Bool that determines if the style is added to the beginning or end of the style attribute.

See Also

css

Returns

: TagT

The modified tag.

append

Tag.append(*args)

Append tag children to the end of the list.

extend

Tag.extend(x)

Extend the children by appending an iterable of children.

insert

Tag.insert(index, x)

Insert tag children before a given index.

remove_class

Tag.remove_class(class_)

Remove a class value from the HTML class attribute.

Parameters

class_ : str

The class name to remove.

Returns

: TagT

The modified tag.

tagify

Tag.tagify()

Convert any tagifiable children to TagifiedTag/TagifiedTagList objects.

htmltools.TagAttrs

TagAttrs

For dictionaries of tag attributes (e.g., {"id": "foo"}), which can be passed as unnamed arguments to Tag functions like div().

htmltools.TagAttrValue

TagAttrValue

Types that can be passed in as attributes to Tag functions. These values will be converted to strings before being stored as tag attributes.

htmltools.TagChild

TagChild

Types of objects that can be passed as children to Tag functions like div(). The Tag functions and the TagList() constructor can accept these as unnamed arguments; they will be flattened and normalized to TagNode objects.

htmltools.TagList

TagList(*args)

Create an HTML tag list (i.e., a fragment of HTML)

Parameters

*args : TagChild = ()

The tag children to add to the list.

Examples

>>> from htmltools import TagList, div
>>> TagList("hello", div(id="foo", class_="bar"))
hello
<div id="foo" class="bar"></div>

Methods

Name	Description
append	Append tag children to the end of the list.
extend	Extend the children by appending an iterable of children.
insert	Insert tag children before a given index.
tagify	Convert any tagifiable children to TagifiedTag/TagifiedTagList objects.

append

TagList.append(item, *args)

Append tag children to the end of the list.

extend

TagList.extend(other)

Extend the children by appending an iterable of children.

insert

TagList.insert(i, item)

Insert tag children before a given index.

tagify

TagList.tagify()

Convert any tagifiable children to TagifiedTag/TagifiedTagList objects.

Raises

: TypeError

If a child’s .tagify() returned a TagList containing an un-tagified Tagifiable object — i.e. the recursion was not done all the way down. The error names the offending class and slot index so the broken .tagify() is easy to find.

htmltools.TagFunction

TagFunction()

htmltools.Tagifiable

Tagifiable()

Objects with tagify() methods are considered Tagifiable. The return value must be Tagified — i.e. fully tagified all the way down. See TagifiedNode / TagifiedTagList.

htmltools.MetadataNode

MetadataNode()