Tag types

htmltools.Tag

Tag(self, _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	Type	Description
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.
get_dependencies	Get any HTML dependencies.
get_html_string	Get the HTML string representation of the tag.
has_class	Check if the tag has a particular class value.
insert	Insert tag children before a given index.
remove_class	Remove a class value from the HTML class attribute.
render	Get string representation as well as its HTML dependencies.
save_html	Save to a HTML file.
show	Preview as a complete HTML document.
tagify	Convert any tagifiable children to Tag/TagList 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

Type	Description
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

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

Type	Description
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.

get_dependencies

Tag.get_dependencies(dedup=True)

Get any HTML dependencies.

get_html_string

Tag.get_html_string(indent=0, eol='\n')

Get the HTML string representation of the tag.

Parameters

indent: int = 0

The number of spaces to indent the tag.

eol: str = ‘’

The end-of-line character(s).

has_class

Tag.has_class(class_)

Check if the tag has a particular class value.

Parameters

class_: str

The class name to check for.

Returns

Type	Description
bool	True if the tag has the class, False otherwise.

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

Type	Description
TagT	The modified tag.

render

Tag.render()

Get string representation as well as its HTML dependencies.

save_html

Tag.save_html(file, *, libdir='lib', include_version=True)

Save to a HTML file.

Parameters

file: str

The file to save to.

libdir: Optional[str] = ‘lib’

The directory to save the dependencies to.

include_version: bool = True

Whether to include the version number in the dependency folder name.

Returns

Type	Description
The path to the generated HTML file.

show

Tag.show(renderer='auto')

Preview as a complete HTML document.

Parameters

renderer: Literal[‘auto’, ‘ipython’, ‘browser’] = ‘auto’

The renderer to use.

tagify

Tag.tagify()

Convert any tagifiable children to Tag/TagList 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(self, *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.
get_dependencies	Get any dependencies needed to render the HTML.
get_html_string	Return the HTML string for this tag list.
insert	Insert tag children before a given index.
render	Get string representation as well as its HTML dependencies.
save_html	Save to a HTML file.
show	Preview as a complete HTML document.
tagify	Convert any tagifiable children to Tag/TagList objects.

append

TagList.append(*args)

Append tag children to the end of the list.

extend

TagList.extend(x)

Extend the children by appending an iterable of children.

get_dependencies

TagList.get_dependencies(dedup=True)

Get any dependencies needed to render the HTML.

Parameters

dedup: bool = True

Whether to deduplicate the dependencies.

get_html_string

TagList.get_html_string(indent=0, eol='\n', *, add_ws=True, _escape_strings=True)

Return the HTML string for this tag list.

Parameters

indent: int = 0

Number of spaces to indent each line of the HTML.

eol: str = ‘’

End-of-line character(s).

add_ws: bool = True

Whether to add whitespace between the opening tag and the first child. If either this is True, or the child’s add_ws attribute is True, then whitespace will be added; if they are both False, then no whitespace will be added.

insert

TagList.insert(index, x)

Insert tag children before a given index.

render

TagList.render()

Get string representation as well as its HTML dependencies.

save_html

TagList.save_html(file, *, libdir='lib', include_version=True)

Save to a HTML file.

Parameters

file: str

The file to save to.

libdir: Optional[str] = ‘lib’

The directory to save the dependencies to.

include_version: bool = True

Whether to include the version number in the dependency folder name.

Returns

Type	Description
str	The path to the generated HTML file.

show

TagList.show(renderer='auto')

Preview as a complete HTML document.

Parameters

renderer: Literal[‘auto’, ‘ipython’, ‘browser’] = ‘auto’

The renderer to use.

tagify

TagList.tagify()

Convert any tagifiable children to Tag/TagList objects.

htmltools.TagFunction

TagFunction()

htmltools.Tagifiable

Tagifiable()

Objects with tagify() methods are considered Tagifiable. Note that an object returns a TagList, the children of the TagList must also be tagified.

htmltools.MetadataNode

MetadataNode()