Text Utils

To create strings with various HTML elements, Pyreball provides various text utility functions. These functions return a string that can be directly printed into the HTML file.

Each function takes zero or more values which are all automatically converted to strings and concatenated with a separator passed through sep parameter. It is also possible to set the class HTML attribute through cl function parameter, or any HTML attribute through a more general attrs parameter.

Grouping Elements

To group or enclose zero or more elements into <div> or <span> elements, use corresponding functions div() and span().

import pyreball as pb

pb.print(
    pb.div("First block"),
    pb.div(
        pb.span("Second block A"),
        pb.span("Second block B"),
    ),
)

Setting HTML Attributes

div(), span() and other functions provide parameters cl, attrs and sep. Let's see them in action.

import pyreball as pb

pb.print(
    pb.div("Centered block of text", cl="pyreball-text-centered"),
    pb.div(
        "Highlighted block of text",
        "<br>",
        "Another line",
        attrs={"style": "background-color: yellow;"},
        sep="\n",
    ),
    sep="\n",
)

In particular, we set the class of the first <div> to value pyreball-text-centered, for which there is actually an entry in included CSS for aligning text to center.

In the case of the second <div>, we set style attribute through attrs parameter. Moreover, we set sep to "\n", which adds newlines to the output HTML file between the elements instead of putting all elements on a single line. Therefore, it just formats differently the content of the HTML file. To insert a line break visually into the shown HTML, it is necessary to print <br> element.

Last, but not least, we also set sep to "\n" in the print() function to create a line break between the <div> elements themselves in the output HTML file.

Basic Text Formatting

To format text, bold() and em() can be used.

import pyreball as pb

pb.print(f"A line with {pb.bold('bold')} and {pb.em('emphasized')} text.")

Code Formatting

When including a source code string into a text, code() and code_block() can be used to format it. The former wraps values into <code> element and can be used inline, whereas the latter wraps values into <pre><code> and is displayed as a block element. Pyreball uses highlight.js library to highlight the syntax in both cases.

import inspect

import pyreball as pb


def add(x, y):
    return x + y


pb.print(f"The sum of {pb.code([1, 2, 3])} is {pb.code(sum([1, 2, 3]))}.")
pb.print(f"The source code of {pb.code('add')} function is:")
pb.print(pb.code_block(inspect.getsource(add)))

The default language used for highlighting is Python. A different language can be set through syntax_highlight. Here is an example with JSON highlighting:

import pyreball as pb

json_str = '{\n  "a": 12,\n  "b": [2, 3, 4]\n}'

pb.print(pb.code_block(json_str, syntax_highlight="json"))

Other supported languages are listed in the highlight.js' Supported Languages table - see the column Aliases.

To turn off the syntax highlighting, set syntax_highlight parameter to None.

import pyreball as pb

json_str = '{\n  "a": 12,\n  "b": [2, 3, 4]\n}'

pb.print(pb.code_block(json_str, syntax_highlight=None))

There is also print_code_block() function that constructs the element and prints it directly into the HTML document. Moreover, it can add a caption and align the block horizontally. The function is demonstrated in Code Blocks chapter.

Creating Hyperlinks

There are two functions for creating hyperlinks. The first one is a(), which contains all the parameters as other text util functions:

import pyreball as pb

pb.print(
    "Text with a ",
    pb.a("link", attrs={"href": "https://www.python.org/"}),
    " to the Python homepage.",
)

The second one is link(), which is a shortcut that contains just two parameters: text and href.

import pyreball as pb

pb.print(
    "Text with a ",
    pb.link("link", "https://www.python.org/"),
    " to the Python homepage.",
)

Lists

To create unordered and ordered lists, Pyreball provides ulist() and olist() functions, respectively.

import pyreball as pb

pb.print(
    "Pyreball allows creating unordered lists:",
    pb.ulist("First", "Second", "Third"),
)

pb.print(
    "And ordered lists too:",
    pb.olist("Fourth", "Fifth", "Sixth"),
)

Each value is automatically wrapped into <li> element and then the whole group is wrapped either to <ul> or <ol> element, depending on whether ulist() or olist() is used. Because there are two types of elements used, cl and attrs parameters are use for the outer <ul> or <ol> element, and special li_cl and li_attrs parameters are used for the inner <li> elements.

Pyreball also allows nesting the lists inside each other. Because HTML requires nested list to be wrapped together with a parent element inside a common <li> element, Pyreball solves this by using a tuple in such a case, see example below.

import pyreball as pb

pb.print(
    "Nested list: ",
    pb.ulist(
        "A",
        (
            "B",
            pb.olist("X", "Y"),
        ),
        (
            "C",
            pb.ulist("Z"),
        ),
        (
            "D",
            "",
        ),
    ),
)

Adding a list item without a sublist can be achieved by providing a single value (as in the case of item A in the example above), or packing it into a tuple with an empty string (as in the case of D item). The latter approach might be more appropriate when the data are generated automatically and the types of all items need to be the same.

Custom HTML Tags

It is possible to use tag() function to create tags that are not implemented directly by Pyreball.

For example, paired tag <pre> and unpaired tag <hr> can be created and used as follows:

import pyreball as pb

pb.set_title("Custom Tags")

pb.print(pb.tag("Text displayed in a fixed-width font.", name="pre"))
hr_tag = pb.tag(name="hr", paired=False)
pb.print(hr_tag)