Node Classes

The Node family of classes represent nodes as Python objects.

There are three Node classes, with a parent/child relationship:

• Node - all methods implemented here, do not instantiate directly
• FileNode - turns a node file into a Node instance
• VirtualNode - creates a Node not backed by a node file

These classes are all defined in the Uriel source code.

Working With Nodes

There are two places where you can encounter Node instances:

• lib/soju.py
• lib/handlers.py

Each Soju function is capable of accepting a node argument as input, which represents the current node. You can call any of the Node methods on it.

Most of the Handler functions accept a root_node parameter, which represents the root node. You can call any of the Node methods on it.

The Node, FileNode, and VirtualNode symbols are also imported into the lib/handlers.py module automatically.

See the Soju and Handlers sections for more details on how to work with Node instances within those contexts.

Creating Your Own Nodes

If you want to create your own nodes dynamically, creating one or more VirtualNode instances in the before_render_node_tree(project_root, root_node) method of lib/handlers.py is probably the best place to start.

If you want to create a Node instance, do not instantiate it directly.

• Instantiate a FileNode if you want to load a node file into a Node instance. Uriel already does this for each node file, so you probably just need to find the node you want.
• Instantiate a VirtualNode if you want to create a Node instance that is not backed by a node file. This is how you create your own nodes dynamically from a user-defined handler.

VirtualNode Constructor Reference

class VirtualNode(Node):
    """
    Represents a virtual node, not backed by a file.

    To use this class:
      - call set_body() to set the node body (which will be merged with
        template later)
      - set headers (although it inherits headers from the parent node)
      - add children (if necessary)

    """

    def __init__(self,
                 project_root: str,
                 path: str,
                 parent_node: Optional[Node] = None) -> None:

        """
        Accepts the project root directory.

        Accepts the path (as a subdirectory of the node root).

        Optionally accepts a parent Node instance.

        """

See the Handlers section for examples of how to use VirtualNode from a handler function.

Node Method Reference

The following is a curated list of Node methods that are likely to be useful when creating a web site.

Take a look at the very bottom of this page to see the results of some of these methods when they are called on the node for this page on the documentation web site.

get_parent_node(self) -> Optional["Node"]

Get the parent Node, or None if this is the root.

get_path(self) -> str

Get the node path (e.g. "index", "foo/bar").

get_node_type(self) -> str

Get the Node type as a string (e.g. "file", "virtual").

add_child(self, node: "Node") -> None

Add the given Node as a child of this Node.

get_children(self) -> List["Node"]

Get a list of child Node entries immediately under this Node.

get_url(self) -> str

Get the URL path for this Node.

URL paths are relative to the root of the site.

Example URL paths:
    /
    /foo/
    /foo/bar/

This method is the authoritative source of where a node will be
placed in the rendered files.

This method never returns canonical URLs, only URL paths.

get_canonical_url(self) -> str

Get the canonical URL for this Node.

This method only returns canonical URLs. If the Canonical-URL header
is not set, it will raise an error.

get_name(self) -> str

Get the name of this Node (e.g. "index", "bar").

This is generally the most specific dirent from the URL path. For example, a
node with a node path of "foo/index" and a URL path of "/foo/" will have a
node name of "foo".

As a special case, the name of the top-level index node is "index".

get_display_name(self) -> str

Get the display name of the node.

This is constructed from the base node name, but is formatted to be
more human readable. For example, if the base node name is
"hello-world", then this method will return "Hello World".

It is used as a fallback plan in case a Title header is not set.

get_title(self) -> str

Get the title of the node, as set by the Title header.

If that doesn't work, fall back on using the node display name.

get_escaped_title(self) -> str

Get the escaped title of the node, as set by the Title header.

If the Escape-Title: false header is set, return the Title
without escaping.

If that doesn't work, fall back on using the node display name.

get_link(self) -> str

Get a link to this node, using its title as the link text.

This method never returns canonical URL links.

get_canonical_link(self) -> str

Get a canonical link to this node, using its title as the link text.

This method only returns canonical URL links. If the Canonical-URL
header is not set, it will raise an error.

get_link_prefix(self) -> str

Get the HTML prefix to use in generated lists of links.

Returns the unescaped value of the Link-Prefix header,
or a default of <p>

get_link_suffix(self) -> str

Get the HTML suffix to use in generated lists of links.

Returns the unescaped value of the Link-Suffix header,
or a default of </p>

get_tags(self) -> List[str]

Get the list of tags associated with this Node.

Returns a list of tags.

get_dest_dir(self) -> str

Get the destination directory in the public website that will
contain this page.

get_dest_file(self) -> str

Get the destination file in the public website that will
contain this page.

get_boolean_header_value(self, header: str, default: bool) -> bool

Get the boolean value for a header as True or False.

For example, if the value of the header is "true", then this method
will return True.

If the header is not set, return the provided default value.

Raises an UrielError if any other value is found.

get_breadcrumb_separator(self) -> str

Get the unescaped breadcrumb separator for this node, possibly
surrounded by spaces.

If the Breadcrumb-Separator header is not set, then "»"
is used as the default value.

If the Breadcrumb-Separator-Spaces header is not explicitly set to
"false", then the return value will contain a space before and after
the breadcrumb separator.

The default return value, if neither of these headers are set, is
" » "

find_node_by_path(self,
                  path:str,
                  raise_exceptions: bool = True) -> Optional["Node"]

Find the Node that matches the given node path.

Returns the given node.

Raises a UrielError if the node can not be found.

If the optional raise_exceptions parameter is set to False,
then instead of raising an exception, it will return None instead.

get_root_node(self) -> "Node"

Get the root Node.

get_tag_node(self) -> Optional["Node"]

Get the tag node, by looking at the value of the Tag-Node header,
and then returning the matching node.

There is only one tag node, and the Tag-Node header should only be
set on the root node.

Returns the tag node, or None if the tag node is not configured.

Raises a UrielError if the tag node is configured, but can not be
found.

get_tag_node_index(self) -> Dict[str, Set["Node"]]

Get the tag node index.

The tag node index is a dict of tags, with sets of Node as values.

Returns the tag node index, or raises a UrielError if the tag node
index has not already been created.

get_vnode_for_tag(self, tag: str) -> Optional["Node"]

Get the virtual node that represents the given tag
(e.g. the node for /tag/$SOME_TAG/)

get_body(self) -> Optional[str]

Get the unrendered Node body as a multi-line string.

get_rendered_body(self) -> Optional[str]

Get the rendered Node body as a multi-line string.

set_body(self, body: Optional[str]) -> None

Set the unrendered Node body. Accepts a multi-line string.

set_rendered_body(self, rendered_body: Optional[str]) -> None

Replace the contents of the Node body (e.g. with a rendered version).

has_header(self, header: str) -> bool

Does the given header exist on this node?

Inside the program, headers should all be lowercase.

get_header(self, header: str) -> str

Get the value associated with the given header.

Inside the program, headers should all be lowercase.

set_header(self, header: str, value: str) -> None

Set the given header to the specified value.

Inside the program, headers should all be lowercase.

delete_header(self, header: str) -> None

Delete the given header.

Inside the program, headers should all be lowercase.

get_header_keys(self) -> List[str]

Get each of the headers for this node.

get_header_key_values(self) -> List[Tuple[str, str]]

Get each key/value element of the headers and their values,
as a list of two-element tuples.

get_datetime_from_date_str(self, date_str: str) -> datetime.datetime

Get a datetime.datetime instance from the provided date string.

The date string must be in the ISO 8601 date format.

Raises a UrielError if the date string conversion fails.

Tags: