euporie.core.ft.html

Contain a HTML to formatted text parser.

Functions

`NamedTuple`(typename[, fields])	Typed version of namedtuple.
`add_border`(ft[, width, style, border_grid, ...])	Add a border around formatted text.
`align`(ft[, how, width, style, placeholder, ...])	Align formatted text at a given width.
`apply_reverse_overwrites`(ft)	Write fragments tagged with "[ReverseOverwrite]" over text to their left.
`apply_style`(ft, style)	Apply a style to formatted text.
`bisect_right`(a, x[, lo, hi, key])	Return the index where to insert item x in list a, assuming a is sorted.
`cast`(typ, val)	Cast a value to a type.
`ceil`(x, /)	Return the ceiling of x as an Integral.
`compute_padding`(cell[, render_count])	Compute a cell's padding.
`concat`(ft_a, ft_b[, baseline_a, baseline_b, ...])	Concatenate two blocks of formatted text, aligning at a given baseline.
`css_dimension`(value[, vertical, available])	Convert CSS dimensions to terminal cell sizes.
`data_pixel_size`(data, format_[, fg, bg])	Get the dimensions of an image.
`eq`(a, b, /)	Same as a == b.
`fragment_list_to_words`(fragments[, sep])	Split formatted text into a list of word fragments which form words.
`fragment_list_width`(fragments)	Return the character width of this text fragment list.
`ge`(a, b, /)	Same as a >= b.
`get_app`()	Get the current active (running) Application.
`get_app_session`()
`get_color`(value)	Extract a hex color from a string.
`get_format`(path[, default])	Attempt to guess the format of a path.
`get_integer`(value)	Extract the first integer from a string.
`get_loop`()	Create or return the conversion IO loop.
`gt`(a, b, /)	Same as a > b.
`join_lines`(fragments)	Join a list of lines of formatted text.
`last_char`(ft)	Retrieve the last character of formatted text.
`le`(a, b, /)	Same as a <= b.
`literal_eval`(node_or_string)	Evaluate an expression node or a string containing only a Python expression.
`lru_cache`([maxsize, typed])	Least-recently-used cache decorator.
`lt`(a, b, /)	Same as a < b.
`match_css_selector`(selector, attrs, pseudo, ...)	Determine if a CSS selector matches a particular element.
`max_line_width`(ft)	Calculate the length of the longest line in formatted text.
`pad`(ft[, width, char, style])	Fill space at the end of lines.
`parse_css_content`(content)	Convert CSS declarations into the internals style representation.
`parse_media_condition`(condition, dom)	Convert media rules to conditions.
`parse_style_sheet`(css_str, dom[, condition])	Collect all CSS styles from style tags.
`paste`(ft_top, ft_bottom[, row, col, transparent])	Pate formatted text on top of other formatted text.
`pixels_to_cell_size`([px, py])	Get the cell width and aspect ration of a pixel dimension.
`selector_specificity`(selector_parts)	Calculate the specificity score of a CSS selector.
`split_lines`(fragments)	Take a single list of (style_str, text) tuples and yield one such list for each line.
`strip`(ft[, left, right, chars, only_unstyled])	Strip whitespace (or a given character) from the ends of formatted text.
`truncate`(ft, width[, style, placeholder, ...])	Truncate all lines at a given length.
`try_eval`(value[, default])	Attempt to cast a string to a python type.
`url_to_fs`(url, **kwargs)	Turn fully-qualified and potentially chained URL into filesystem instance
`urljoin`(base, url[, allow_fragments])	Join a base URL and a possibly relative URL to form an absolute interpretation of the latter.

Classes

`Cell`([text, row, col, colspan, rowspan, ...])	A table cell.
`Condition`(func)	Turn any callable into a Filter.
`CssSelector`([comb, item, attr, pseudo])	A named tuple to hold CSS selector data.
`CustomHTMLParser`(dom)	An HTML parser.
`DiBool`([top, right, bottom, left])	A tuple of four bools with directions.
`DiInt`([top, right, bottom, left])	A tuple of four integers with directions.
`DiLineStyle`([top, right, bottom, left])	A description of a cell border: a `LineStyle` for each edge.
`DiStr`([top, right, bottom, left])	A tuple of four strings with directions.
`Dimension`([min, max, weight, preferred])	Specified dimension (width/height) of a user control or window.
`Direction`([x, y])	A description of a direction.
`Event`(sender[, handler])	Simple event to which event handlers can be attached. For instance::.
`FormattedTextAlign`(value[, names, module, ...])	Alignment of formatted text.
`GridStyle`(line_style, mask)	A collection of characters which can be used to draw a grid.
`HTML`(markup[, base, width, height, ...])	A HTML formatted text renderer.
`HTMLParser`(*[, convert_charrefs])	Find tags and other markup and call handler functions.
`Mapping`()	A Mapping is a generic container for associating key/value pairs.
`Node`(dom, name, parent[, text, attrs, contents])	Represent an node in the DOM.
`Size`(rows, columns)
`Table`([rows, cols, width, expand, align, ...])	A table.
`Theme`(element, parent_theme[, ...])	The computed theme of an element.
`UPath`(args, *kwargs)
`cached_property`(func)
`partial`	partial(func, args, *keywords) - new function with partial application of the given arguments and keywords.
`zip_longest`	zip_longest(iter1 [,iter2 [...]], [fillvalue=None]) --> zip_longest object

class euporie.core.ft.html.CssSelector(comb: str | None = None, item: str | None = None, attr: str | None = None, pseudo: str | None = None)

Bases: NamedTuple

A named tuple to hold CSS selector data.

attr: str | None: Alias for field number 2

comb: str | None: Alias for field number 0

count(value, /): Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

item: str | None: Alias for field number 1

pseudo: str | None: Alias for field number 3

class euporie.core.ft.html.CustomHTMLParser(dom: euporie.core.ft.html.HTML)

Bases: html.parser.HTMLParser

An HTML parser.

CDATA_CONTENT_ELEMENTS = ('script', 'style')

autoclose() → None: Automatically close void elements.

check_for_whole_start_tag(i)

clear_cdata_mode()

close(): Handle any buffered data.

curr: euporie.core.ft.html.Node

feed(data)

Feed data to the parser.

Call this as often as you want, with as little or as much text as you want (may include ‘n’).

get_starttag_text(): Return full source of start tag: ‘<…>’.

getpos(): Return current line number and offset.

goahead(end)

handle_charref(name)

handle_comment(data)

handle_data(data: str) → None: Create data (text) elements.

handle_decl(decl)

handle_endtag(tag: str) → None: Handle end tags: close the currently opened element.

handle_entityref(name)

handle_pi(data)

handle_startendtag(tag, attrs)

handle_starttag(tag: str, attrs: list[tuple[str, str | None]]) → None: Open a new element.

parse(markup: str) → euporie.core.ft.html.Node: Pare HTML markup.

parse_bogus_comment(i, report=1)

parse_comment(i, report=1)

parse_declaration(i)

parse_endtag(i)

parse_html_declaration(i)

parse_marked_section(i, report=1)

parse_pi(i)

parse_starttag(i)

reset(): Reset this instance. Loses all unprocessed data.

set_cdata_mode(elem)

soup: euporie.core.ft.html.Node

unknown_decl(data)

updatepos(i, j)

class euporie.core.ft.html.Direction(x: bool = False, y: bool = False)

Bases: NamedTuple

A description of a direction.

count(value, /): Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

x: bool: Alias for field number 0

y: bool: Alias for field number 1

class euporie.core.ft.html.HTML(markup: str, base: Path | str | None = None, width: int | None = None, height: int | None = None, collapse_root_margin: bool = False, fill: bool = True, css: CssSelectors | None = None, browser_css: CssSelectors | None = None, mouse_handler: Callable[[Node, MouseEvent], NotImplementedOrNone] | None = None, paste_fixed: bool = True, on_update: Callable[[HTML], None] | None = None, _initial_format: str = '')

Bases: object

A HTML formatted text renderer.

Accepts a HTML string and renders it at a given width.

async format_element(ft: StyleAndTextTuples, element: Node, left: int = 0, fill: bool = True, align_content: bool = True) → StyleAndTextTuples: Format an element’s content based on its theme.

async load_assets() → None

Load CSS styles and image resources.

Do not touch element’s themes!

property parser: euporie.core.ft.html.CustomHTMLParser: Load the HTML parser.

render(width: int | None, height: int | None) → StyleAndTextTuples: Render the current markup at a given size.

async render_details_content(element: Node, left: int = 0, fill: bool = True, align_content: bool = True) → StyleAndTextTuples: Render details, showing summary at the top and hiding contents if closed.

async render_element(element: Node, available_width: int, available_height: int, left: int = 0, fill: bool = True, align_content: bool = True) → StyleAndTextTuples: Render a Node.

async render_grid_content(element: Node, left: int = 0, fill: bool = True, align_content: bool = True) → StyleAndTextTuples

Render a element with display set to grid.

Parameters

element – The list of parsed elements to render
left – The position on the current line at which to render the output - used to indent subsequent lines when rendering inline blocks like images
fill – Whether to fill the remainder of the rendered space with whitespace
align_content – Whether to align the element’s content

Returns

Formatted text

async render_img_content(element: Node, left: int = 0, fill: bool = True, align_content: bool = True) → StyleAndTextTuples: Render an image’s content.

async render_input_content(element: Node, left: int = 0, fill: bool = True, align_content: bool = True) → StyleAndTextTuples: Render an input element.

async render_list_item_content(element: Node, left: int = 0, fill: bool = True, align_content: bool = True) → StyleAndTextTuples: Render a list item.

async render_node_content(element: Node, left: int = 0, fill: bool = True, align_content: bool = True) → StyleAndTextTuples: Generate flows for the contents of the element.

async render_ol_content(element: Node, left: int = 0, fill: bool = True, align_content: bool = True) → StyleAndTextTuples: Render lists, adding item numbers to child <li> elements.

async render_svg_content(element: Node, left: int = 0, fill: bool = True, align_content: bool = True) → StyleAndTextTuples: Display images rendered as ANSI art.

async render_table_content(element: Node, left: int = 0, fill: bool = True, align_content: bool = True) → StyleAndTextTuples

Render a HTML table element.

Parameters

element – The list of parsed elements to render
left – The position on the current line at which to render the output - used to indent subsequent lines when rendering inline blocks like images
fill – Whether to fill the remainder of the rendered space with whitespace
align_content – Whether to align the element’s content

Returns

Formatted text

async render_text_content(element: Node, left: int = 0, fill: bool = True, align_content: bool = True) → StyleAndTextTuples

Render a text element.

Parameters

element – The page element to render
left – The position on the current line at which to render the output - used to indent subsequent lines when rendering inline blocks like images
fill – Whether to fill the remainder of the rendered space with whitespace
align_content – Whether to align the element’s content

Returns

Formatted text

async render_ul_content(element: Node, left: int = 0, fill: bool = True, align_content: bool = True) → StyleAndTextTuples: Render lists, adding item numbers to child <li> elements.

property soup: euporie.core.ft.html.Node: Parse the markup.

class euporie.core.ft.html.Node(dom: euporie.core.ft.html.HTML, name: str, parent: euporie.core.ft.html.Node | None, text: str = '', attrs: list[tuple[str, str | None]] | None = None, contents: list[euporie.core.ft.html.Node] | None = None)

Bases: object

Represent an node in the DOM.

property child_elements: Generator[Node, None, None]: Yield all of the child element nodes.

property descendents: Generator[Node, None, None]: Yield all descendent elements.

find_all(tag: str, recursive: bool = False) → Iterator[Node]: Find all child elements of a given tag type.

property first_child_element: euporie.core.ft.html.Node | None: Return the first child element.

property is_first_child_element: bool: True if the element if the first child element of its parent element.

property is_first_child_node: bool: True if the element if the first child node of its parent element.

property is_last_child_element: bool: True if the element if the last child element of its parent element.

property is_last_child_node: bool: True if the element if the last child node of its parent element.

property last_child_element: euporie.core.ft.html.Node | None: Return the last child element.

property next_element: euporie.core.ft.html.Node | None: Return the next sibling element.

property next_node: euporie.core.ft.html.Node | None: Return the next sibling node.

property next_node_in_flow: euporie.core.ft.html.Node | None: Get the next node in the current element’s flow.

property parents: list[euporie.core.ft.html.Node]: Yield all parent elements.

property preceding_text: str: Return the text preceding this element.

property prev_element: euporie.core.ft.html.Node | None: Return the previous sibling element.

property prev_node: euporie.core.ft.html.Node | None: Return the previous sibling node.

property prev_node_in_flow: euporie.core.ft.html.Node | None: Get the previous node in the current element’s flow.

property renderable_contents: list[euporie.core.ft.html.Node]: List the node’s contents including ‘::before’ and ‘::after’ elements.

property renderable_descendents: Generator[Node, None, None]: Yield descendents, including pseudo and skipping inline elements.

property sibling_element_index: int | None: Return the index of this element among its siblings.

property sibling_flow_index: int | None: Return the index of this element among its siblings.

property text: str: Get the element’s computed text.

theme: Theme

class euporie.core.ft.html.Theme(element: euporie.core.ft.html.Node, parent_theme: euporie.core.ft.html.Theme | None, available_width: int = 0, available_height: int = 0)

Bases: collections.abc.Mapping

The computed theme of an element.

property anchors: euporie.core.data_structures.DiBool: Which position directions are set.

property attributes_theme: dict[str, str]: Calculate the theme defined by (depreciated) HTML attributes.

property background_color: str: Get the computed theme background color.

property base_margin: euporie.core.data_structures.DiInt: Calculate the margin box.

property block_align: euporie.core.ft.utils.FormattedTextAlign: Determine if the left and right margins are set to auto.

property border_collapse: bool: Determine if the border is collapsed.

property border_grid: euporie.core.border.GridStyle: Calculate a GridStyle based on the border lines.

property border_line: euporie.core.border.DiLineStyle: Calculate the line style.

property border_style: euporie.core.data_structures.DiStr: Calculate the visibility of the element’s borders.

property border_visibility: euporie.core.data_structures.DiBool: Calculate the visibility of the element’s borders.

property browser_css_theme: dict[str, str]: Calculate the theme defined in the browser CSS.

property color: str: Get the computed theme foreground color.

property content_height: int: Return the height available for rendering the element’s content.

property content_width: int: Return the width available for rendering the element’s content.

property d_block: bool: If the element a block element.

property d_blocky: bool: If the element an inline element.

property d_flex: bool: If the element a block element.

property d_grid: bool: If the element a block element.

property d_image: bool: If the element is an image.

property d_inline: bool: If the element an inline element.

property d_inline_block: bool: If the element an inline element.

property d_list_item: bool: If the element an inline element.

property d_table: bool: If the element a block element.

property d_table_cell: bool: If the element a block element.

property dom_css_theme: dict[str, str]: Calculate the theme defined in CSS in the DOM.

property floated: str | None: The float status of the element.

property font_size: float | int: Get the computed font size for the current element.

property gap: tuple[int, int]: Calculate the horizontal & vertical inter-element spacing.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

property grid_area: str | None: The name of the grid area assigned to the grid item.

property grid_areas: dict[int, dict[int, str]]: The layout of grid-areas in the current node’s grid layout.

property grid_column_span: int: The number of grid columns spanned by the grid item.

property grid_column_start: int | None: The index of the first grid column spanned by the grid item.

property grid_template: Iterator[list[str]]: Calculate the size of the grid tracks.

property height: int | None: The perscribed height.

property hidden: bool: Determine if the element is hidden.

property in_flow: bool: Determine if the element is “in-flow”.

property inherited_browser_css_theme: dict[str, str]: Get the inherited parts from the browser CSS.

property inherited_theme: dict[str, str]: Calculate the theme inherited from the element’s parent.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

property list_style_position: str: Where the list bullet should be located.

property list_style_type: str: The bullet character to use for the list.

property margin: euporie.core.data_structures.DiInt: Calculate the margin box.

property max_content_width: int: Get maximum absolute child width.

property max_height: int | None: The maximum permitted height.

property max_width: int | None: The maximum permitted width.

property min_content_width: int: Get maximum absolute child width.

property min_height: int | None: The minimum permitted height.

property min_width: int | None: The minimum permitted width.

property order: tuple[tuple[bool, int], int, tuple[bool, int]]: Items are sorted by ascending order value then their source code order.

property padding: euporie.core.data_structures.DiInt: Calculate the padding box.

property position: euporie.core.data_structures.DiInt: The position of an element with a relative, absolute or fixed position.

property preformatted: bool: Determine if the content is pre-formatted.

property skip: bool: Determine if the element should not be displayed.

property style: str: Calculate the output style.

property style_attribute_theme: dict[str, str]: Calculate the theme defined by the element’s style attribute.

property text_align: euporie.core.ft.utils.FormattedTextAlign: The text alignment direction.

async text_transform(value: str) → str: Return a function which transforms text.

property theme: dict[str, str]: Return the combined computed theme.

update_space(available_width: int, available_height: int) → None: Set the space available to the element for rendering.

values() → an object providing a view on D's values

property vertical_align: float: The vertical alignment direction.

property width: int | None: The pescribed width.

property z_index: int: The z-index of the element.

euporie.core.ft.html.css_dimension(value: str, vertical: bool = False, available: float | int | None = None) → float | None: Convert CSS dimensions to terminal cell sizes.

euporie.core.ft.html.get_color(value: str) → str: Extract a hex color from a string.

euporie.core.ft.html.get_integer(value: str) → int | None: Extract the first integer from a string.

euporie.core.ft.html.match_css_selector(selector: str, attrs: str, pseudo: str, element_name: str, is_first_child_element: bool, is_last_child_element: bool, sibling_element_index: int | None, **element_attrs: Any) → bool: Determine if a CSS selector matches a particular element.

euporie.core.ft.html.parse_css_content(content: str) → dict[str, str]: Convert CSS declarations into the internals style representation.

euporie.core.ft.html.parse_media_condition(condition: str, dom: HTML) → Filter: Convert media rules to conditions.

euporie.core.ft.html.parse_style_sheet(css_str: str, dom: HTML, condition: Filter = <prompt_toolkit.filters.base.Always object>) → None: Collect all CSS styles from style tags.

euporie.core.ft.html.selector_specificity(selector_parts: tuple[euporie.core.ft.html.CssSelector, ...]) → tuple[int, int, int]: Calculate the specificity score of a CSS selector.

euporie.core.ft.html.try_eval(value: str, default: Any = None) → Any: Attempt to cast a string to a python type.