HTML¶

Utilities for working with HTML elements. Used for reading attributes and sanitizing HTML.

from prairielearn import ...

check_attribs ¶

check_attribs(
    element: HtmlElement,
    required_attribs: list[str],
    optional_attribs: list[str],
) -> None

Verify that the element has all required attributes and no unknown attributes.

escape_invalid_string ¶

escape_invalid_string(string: str) -> str

Wrap and escape string in <code> tags.

Returns:

Type	Description
`str`	The sanitized user input wrapped in a code block.

get_boolean_attrib ¶

get_boolean_attrib(
    element: HtmlElement, name: str, *args: bool | None
) -> bool | None

Return the named attribute for the element, or the (optional) default value. If the default value is not provided and the attribute is missing then an exception is thrown. If the attribute is not a valid boolean then an exception is thrown.

Returns:

Type	Description
`bool \| None`	The boolean value of attribute `name`.

Raises:

Type	Description
`ValueError`	If the attribute is not a valid boolean value.

get_color_attrib ¶

get_color_attrib(
    element: HtmlElement, name: str, *args: str | None
) -> str | None

Return a 3-digit or 6-digit hex RGB string in CSS format (e.g., '#123' or '#1a2b3c'), or the (optional) default value. If the default value is not provided and the attribute is missing then an exception is thrown. If the attribute is not a valid RGB string then it will be checked against various named colors. If the attribute is still not valid an exception is thrown.

Returns:

Type	Description
`str \| None`	A CSS color string.

Raises:

Type	Description
`ValueError`	If the attribute is not a valid CSS color string.

get_enum_attrib ¶

get_enum_attrib(
    element: HtmlElement,
    name: str,
    enum_type: type[EnumT],
    default: EnumT | None = None,
) -> EnumT

Return the named attribute for the element parsed as an enum, or the (optional) default value. If the default value is not provided and the attribute is missing then an exception is thrown. An exception is also thrown if the value for the enum provided is invalid. Also, alter the enum names to comply with PL naming convention automatically (replacing underscores with dashes and uppercasing). If a default value is provided, it must be a member of the given enum.

Returns:

Type	Description
`EnumT`	The value of attribute `name`, as part of the enum.

Raises:

Type	Description
`ValueError`	If the attribute is not a valid enum value.

get_float_attrib ¶

get_float_attrib(
    element: HtmlElement, name: str, *args: float | None
) -> float | None

Return the named attribute for the element, or the (optional) default value. If the default value is not provided and the attribute is missing then an exception is thrown. If the attribute is not a valid floating-point number then an exception is thrown.

Returns:

Type	Description
`float \| None`	The float value of attribute `name`.

Raises:

Type	Description
`ValueError`	If the attribute is not a valid floating-point number.

Examples:

>>> get_float_attrib(element, "stroke-width", 4.0)
10.0

get_integer_attrib ¶

get_integer_attrib(
    element: HtmlElement, name: str, *args: int | None
) -> int | None

Return the named attribute for the element, or the (optional) default value. If the default value is not provided and the attribute is missing then an exception is thrown. If the attribute is not a valid integer then an exception is thrown.

Returns:

Type	Description
`int \| None`	The int value of attribute `name`.

Raises:

Type	Description
`ValueError`	If the attribute is not a valid integer value.

get_string_attrib ¶

get_string_attrib(
    element: HtmlElement, name: str, *args: str | None
) -> str | None

Return the named attribute for the element, or the (optional) default value. If the default value is not provided and the attribute is missing then an exception is thrown.

Returns:

Type	Description
`str \| None`	The string value of attribute `name`.

has_attrib ¶

has_attrib(element: HtmlElement, name: str) -> bool

If an HTML element has an attribute name set.

Returns:

Type	Description
`bool`	`True` if the element has an attribute of that name, `False` otherwise.

inner_html ¶

inner_html(element: HtmlElement) -> str

Get the inner HTML of an lxml element.

Returns:

Type	Description
`str`	The inner HTML of the element as a string.

is_boolean_value ¶

is_boolean_value(value: str) -> bool

Return whether a string is a PrairieLearn boolean value.

is_float_value ¶

is_float_value(value: str) -> bool

Return whether a string is a PrairieLearn floating-point value.

Authoritative number format check, mirroring get_float_attrib. The linter-side regex is stricter: float() also accepts inf/nan, 1_000.0, +5, and surrounding whitespace. See the note in is_integer_value.

is_integer_value ¶

is_integer_value(value: str) -> bool

Return whether a string is a PrairieLearn integer value.

This is the authoritative integer format check (it matches how get_integer_attrib parses values at runtime). The linter-side regex in element-schemas/htmlmustache-plugin.ts is intentionally stricter: int() also accepts forms like 1_000, +5, and surrounding whitespace that the linter flags. Keep the two notions aligned when changing either side.