API Reference

API documentation for the Hyperpython module.

Basic types

class hyperpython.Element(tag: str, attrs: dict, children: list, is_void=False, requires=())

Represents an HTML element.

add_child(value)

Add child element to data structure.

Caveat: Hyperpython do not enforce immutability, but it is a good practice to keep HTML data structures immutable.

add_class(cls, first=False)

Add class or group of classes to the class list.

copy()

Return a copy of object.

dump(file)

Dumps HTML data into file.

json()

JSON-compatible representation of object.

pretty(**kwargs)

Render a pretty printed HTML.

This method is less efficient than .render(), but is useful for debugging

render()

Renders object as string.

set_class(cls=())

Replace all current classes by the new ones.

walk()

Walk over all elements in the object tree, including Elements and Text fragments.

walk_tags()

Walk over all elements in the object tree, excluding Text fragments.

class hyperpython.Text(data, escape=None)

It extends the Markup object with a Element-compatible API.

dump(file)

Dump contents of element in the given file.

render()

Renders object as string.

unescaped

Convert all named and numeric character references (e.g. >, >, &x3e;) in the string s to the corresponding unicode characters. This function uses the rules defined by the HTML 5 standard for both valid and invalid character references, and the list of HTML 5 named character references defined in html.entities.html5.

class hyperpython.Block(children, requires=())

Represents a list of elements not wrapped in a tag.

dump(file)

Dump contents of element in the given file.

Functions

The generic entry point is the h() function. It also has functions with same names of all HTML tags.

hyperpython.h(tag, *args, children=None, **attrs)

Creates a tag.

It has many different signatures:

h(‘h1’, ‘content’)

Content can be a string, a child node or a list of children.

h(‘h1’, {‘class’: ‘title’}, ‘content’)

If the second argument is a dictionary, it is interpreted as tag attributes.

h(‘h1’, ‘title’, class_=’title’)

Keyword arguments are also interpreted a attributes. The h function makes a few changes: underscores are converted to dashes and trailing underscores after Python keywords such as class_, for_, etc are ignored.

h(‘h1’, class_=’title’)[‘content’]

Children can also be specified using squared brackets. It understands strings, other tags, and lists of tags.

h(‘h1’, class_=’title’, children=[‘content’])

Optionally, the list of children nodes can be specified as a keyword argument.

Creation of HTML elements for Python objects

hyperpython.html(obj, role=None, **kwargs)

Convert object into a hyperpython structure.

Parameters:

• obj – Input object.
• role – Optional description
• context variables for the rendering process can be passed as (Additional) –
• arguments. (keyword) –

Returns:

A hyperpython object.

hyperpython.render(obj, role=None, **kwargs)

Like render(), but return a string of HTML code instead of a Hyperpython object.

hyperpython.fragment(path, **kwargs)

Compute the Hyperpython element for the given fragment path.

Parameters:path (str) – Argument path.

Examples

>>> fragment('page.header', user='me!')                  
h('header', ['Hello me!'])

Hyperpython components

All functions bellow belongs to the hyperpython.components module.

Hyperlinks

hyperpython.components.hyperlink(obj, href=None, **attrs) → hyperpython.core.Element

Converts object to an anchor (<a>) tags.

It implements some common use cases:

str:

Renders string as content inside the <a>…</a> tags. Additional options including href can be passed as keyword arguments. If no href is given, it tries to parse a string of “Value <link>” and uses href=’#’ if no link is found.

dict or mapping:

Most keys are interpreted as attributes. The visible content of the link must be stored in the ‘content’ key:

>>> hyperlink({'href': 'www.python.com', 'content': 'Python'})
<a href="www.python.com">Python</a>

django model:

It must define a get_absolute_url() method. This function uses this result as the href field and str(model) as its content.

>>> from django.contrib.auth import get_user_model
>>> user_model = get_user_model()
>>> hyperlink(user_model(first_name='Joe', username='joe123'))
<a href="/users/joe123">Joe</a>

In order to support other types, use the lazy_singledispatch mechanism:

@hyperlink.registerPlugin(MyFancyType)
def _(x, **kwargs):
    return safe(render_object_as_safe_html(x))

See also

hyperpython.helpers.attrs(): See this function for an exact

explanation of how keyword arguments are translated into HTML attributes.

hyperpython.components.url(obj)

Returns a url for the given object.

hyperpython.components.a_or_p(*args, href=None, **kwargs)

Return a or p tag depending if href is defined or not.

hyperpython.components.a_or_span(*args, href=None, **kwargs)

Return a or span tag depending if href is defined or not.

hyperpython.components.breadcrumbs(links, class_='breadcrumbs')

Component that Receives a list of links and return a breadcrumbs element.

HTML data structures

Those functions convert Python data structures to their natural HTML representations.

hyperpython.components.html_list(data, role=None, ordered=False, **kwargs)

Convert a Python iterable into an HTML list element.

Parameters:

• data – Sequence data.
• ordered – If True, returns an ordered list (<ol>) element.
• role – Role passed to render each item in the sequence.
• keyword arguments are passed to the root element. (Additional) –

Examples

>>> doc = html_list([1, 2, 3])
>>> print(doc.pretty())
<ul>
    <li>1</li>
    <li>2</li>
    <li>3</li>
</ul>'

hyperpython.components.html_map(data, role=None, key_role=None, **kwargs)

Renders mapping as a description list using dt as keys and dt as values.

Parameters:

• data – Sequence data.
• role – Role passed to the dd (values) elements of the description list.
• key_role – Role passed to the dt (keys) elements of the description list.
• keyword arguments are passed to the root element. (Additional) –

Examples

>>> doc = html_map({'answer': 42, 'universe': True})
>>> print(doc.pretty())
<dl>
    <dt>answer</dt>
    <dd>42</dd>
    <dt>universe</dt>
    <dd>True</dd>
</dl>

hyperpython.components.html_table(data, role=None, columns=None, **kwargs)

Convert 2D matrix-like data to an HTML table.

Parameters:

• data – Sequence data.
• columns – A list of column names to be added as <thead>.
• role – Role used to render elements of the table.
• keyword arguments are passed to the root element. (Additional) –

Examples

>>> doc = html_table([[1, 2], [3, 4]], columns=['a', 'b'])
>>> print(doc.pretty())
<table>
    <thead>
        <tr><th>a</th><th>b</th></tr>
    </thead>
    <tbody>
        <tr><td>1</td><td>2</td></tr>
        <tr><td>3</td><td>4</td></tr>
    </tbody>
</table>

Icons

Generic icon support using the <i> tag and helper functions for Font Awesome icons.

hyperpython.components.icon(name, href=None, icon_class=<function <lambda>>, **kwargs)

Returns a icon tag.

Parameters:

• name (str) – Name of the icon.
• href (str) – If given, it wraps the results into a anchor link.
• icon_class (callable) – A function that maps an icon name into the corresponding class or list of classes that should be added to the icon.

hyperpython.components.fa_icon(name, href=None, collection=None, **kwargs)

Font awesome icon.

Parameters:

• name (str) – Name of the icon.
• href (str) – If given, it wraps the results into a anchor link.
• collection ('fa', 'fab', 'far', 'fal', 'fas') –

  The font-awesome collection:

  • fa/far/regular: regular icons
  • fab/brand: brand icons
  • fal/light: light icons
  • fas/solid: solid icons

Examples

>>> fa_icon('face')
<i class="fa fa-face"></i>

Text

hyperpython.components.markdown(text, *, output_format='html5', **kwargs)

Renders Markdown content as HTML and return as a safe string.