RenderableTreePart

class penzai.treescope.foldable_representation.part_interface.RenderableTreePart

Bases: ABC

Abstract base class for a formatted part of a foldable tree.

Formatted objects are produced by treescope handlers from the original Python objects, and know how to convert themselves to a concrete renderable representation.

Renderable tree parts can appear either expanded or collapsed, depending on the status of their parent foldable tree nodes. They are responsible for:

• computing the relevant sizing metrics for each of these display modes,

• tracking any children that are foldable tree nodes themselves,

• and rendering themselves to HTML or text form.

Methods

foldables_in_this_part()	Returns a collection of foldables contained in this node.
html_setup_parts(context, /)	Returns a set of setup strings for this part.
render_to_html(stream, *[, at_beginning_of_line])	Renders this tree part to an HTML source string.
render_to_text(stream, *, expanded_parent, ...)	Renders this tree part to a plain-text string.

Attributes

collapsed_width	The length of this rendering if collapsed in one line, in characters.
newlines_in_expanded_parent	The number of newlines in this rendering if in an expanded parent.
tags_in_this_part	Returns a set of "tag" objects contained in this part.

Inherited Methods

(expand to view inherited methods)

__init__()

property collapsed_width: int

The length of this rendering if collapsed in one line, in characters.

This should include the (collapsed) lengths of all children of this tree part as well. Cached to avoid O(n^2) computations while iteratively expanding children.

abstract foldables_in_this_part() → Sequence[FoldableTreeNode]

Returns a collection of foldables contained in this node.

This should return the outermost foldables that are contained in this node, e.g. any foldable that is contained in this node but not contained in another foldable contained in this node. If this node is already a FoldableTreeNode, the result should just be self.

Returns:

A sequence of foldables contained in this node.

abstract html_setup_parts(context: HtmlContextForSetup, /) → set[CSSStyleRule | JavaScriptDefn]

Returns a set of setup strings for this part.

Setup strings are strings that should appear in the HTML at least once but not more than once if possible, such as definitions of javascript functions or CSS styles.

Parameters:

context – Context for the setup.

Returns:

A set of setup strings, which can use the given selectors to configure themselves.

property newlines_in_expanded_parent: int

The number of newlines in this rendering if in an expanded parent.

For instance, if this will always render as a single line, this should return zero. If this renders as three lines, it contains two newlines, so this should return 2.

Being in an expanded parent means that all parent FoldableTreeNodes containing this part are in an expanded state, and this tree part is not constrained to lie on a single line.

However, any foldable tree nodes contained within this node itself should be considered collapsed for the purposes of computing this value; this should represent the smallest height this part could have if all of its children were collapsed. As a special case, if this node is itself a subclass of FoldableTreeNode, this should usually return 0 regardless of whether the node is currently set to expand or not.

abstract render_to_html(stream: io.TextIOBase, *, at_beginning_of_line: bool = False, render_context: dict[Any, Any])

Renders this tree part to an HTML source string.

Nodes will be automatically indented as needed using parent margins and padding, so they do not need to handle this.

Handling of collapsed parents and roundtrip node should be done in html_setup_parts and then configured using CSS classes.

Parameters:

• stream – Output stream to write to.

• at_beginning_of_line – Whether this node is at the beginning of its line, meaning that it only has whitespace to its left and is allowed to extend slightly past its ordinary bounds on the left side. For instance, if this is True, it’s OK to render an “unfold” marker inside the whitespace to the left of this node.

• render_context – Dictionary of optional additional context. Specific types of renderable part that need to set context should ensure they use a unique key, and any unrecognized keys should be passed down to any children being rendered.

abstract render_to_text(stream: io.TextIOBase, *, expanded_parent: bool, indent: int, roundtrip_mode: bool, render_context: dict[Any, Any])

Renders this tree part to a plain-text string.

Parameters:

• stream – Output stream to write to.

• expanded_parent – Whether this node’s parent is expanded, and it’s thus OK to render across multiple lines.

• indent – Number of spaces to indent this part if it breaks across multiple lines.

• roundtrip_mode – Whether to render in round-trip mode (with fully qualified names).

• render_context – Dictionary of optional additional context. Specific types of renderable part that need to set context should ensure they use a unique key, and any unrecognized keys should be passed down to any children being rendered.

Returns:

A plain-text rendering.

property tags_in_this_part: frozenset[Any]

Returns a set of “tag” objects contained in this part.

Tags allow surfacing of internal information to guide layout decisions. For instance, if nodes of a particular type need to be made visible, they can add a tag and propagate it upward through the tree. Then, foldables can be expanded whenever they contain a tag of the given type. (This is how expansion of selections is implemented.)

Cached to avoid O(n^2) computations while iteratively expanding children.