liara.nodes

Module Contents

Classes

Publisher

A publisher produces the final output files, applying templates etc. as needed.

NodeKind

Node

MetadataKind

FixupDateTimezone

Set the timezone of the metadata['date'] field to the local timezone if no timezone has been set.

DocumentNode

HtmlDocumentNode

A node representing a Html document.

MarkdownDocumentNode

A node representing a Markdown document.

DataNode

A data node.

IndexNode

An index node.

GeneratedNode

RedirectionNode

A redirection node triggers a redirection to another page.

ResourceNode

A resource node applies some process when creating the output.

SassResourceNode

This resource node compiles .sass and .scss files to CSS when built.

NodeFactory

A generic factory for nodes, which builds nodes based on the file type.

ResourceNodeFactory

A factory for resource nodes.

DocumentNodeFactory

A factory for document nodes.

StaticNode

A static data node.

ThumbnailNode

Functions

extract_metadata_content

Extract metadata and content.

fixup_relative_links

Replace relative links in the document with links relative to the site root.

fixup_date

If the date in the document is a string, try to parse it to produce a datetime object.

Data

NT

API

class liara.nodes.Publisher

Bases: abc.ABC

A publisher produces the final output files, applying templates etc. as needed.

abstract publish_document(document: liara.nodes.DocumentNode) pathlib.Path

Publish a document node.

Returns:

The path of the generated file.

abstract publish_index(index: liara.nodes.IndexNode) pathlib.Path

Publish an index node.

Returns:

The path of the generated file.

abstract publish_resource(resource: liara.nodes.ResourceNode) pathlib.Path

Publish a resource node.

Returns:

The path of the generated file.

abstract publish_static(static: liara.nodes.StaticNode) pathlib.Path

Publish a static node.

Returns:

The path of the generated file.

abstract publish_generated(generated: liara.nodes.GeneratedNode) pathlib.Path

Publish a generated node.

Returns:

The path of the generated file.

class liara.nodes.NodeKind(*args, **kwds)

Bases: enum.Enum

Resource = 'auto(...)'
Index = 'auto(...)'
Document = 'auto(...)'
Data = 'auto(...)'
Static = 'auto(...)'
Generated = 'auto(...)'
class liara.nodes.Node

Bases: abc.ABC

kind: liara.nodes.NodeKind = None

The node kind, must be set in the constructor.

src: Optional[pathlib.Path] = None

The full path to the source file.

This is an OS specific path object.

path: pathlib.PurePosixPath = None

The output path, relative to the page root.

All paths must start with /.

metadata: Dict[str, Any] = None

Metadata associated with this node.

parent: Optional[liara.nodes.Node] = None

The parent node, if any.

property children

A list containing all direct children of this node.

add_child(child: liara.nodes.Node) None

Add a new child to this node.

The path of the child node must be a sub-path of the current node path, with exactly one more component. I.e. if the current node path is /foo/bar, a node with path /foo/bar/baz can be added as a child, but /baz/ or /foo/bar/boo/baz would be invalid.

select_children() liara.query.Query

Select all children of this node and return them as a Query.

get_child(name) Optional[liara.nodes.Node]

Get a child of this node.

Returns:

The child node or None if no such child exists.

get_children(*, recursive=False) Iterable[liara.nodes.Node]

Get all children of this node.

This function differs from select_children() in two important ways:

  • It returns a list of Node instances and does not wrap it in a Query

  • It can enumerate all children recursively.

process(cache: liara.cache.Cache, **kwargs) Optional[liara.nodes._AsyncTask]

Some nodes – resources, documents, etc. need to be processed. As this can be a resource-intense process (for instance, it may require generating images), processing can cache results and has to be called separately instead of being executed as part of some other operation.

By convention this method should populate self.content if executed synchronously. If asynchronous execution is supported, this method must return an _AsyncTask which is then executed later. In this case, self.content will be populated by the task runner.

The **kwargs are used to pass in additional context for processing. System-provided arguments will be prefixed with a $ (which is not a valid identifier.)

Changed in version 2.6.2: Added **kwargs **kwargs was added to allow passing in additional context.

class liara.nodes.MetadataKind(*args, **kwds)

Bases: enum.Enum

Unknown = 'auto(...)'
Yaml = 'auto(...)'
Toml = 'auto(...)'
liara.nodes.extract_metadata_content(text: str)

Extract metadata and content.

Metadata is stored at the beginning of the file, separated using a metadata separation marker, for instance:

+++
this_is_toml = True
+++

content

This function splits the provided text into metadata and actual content.

Replace relative links in the document with links relative to the site root.

liara.nodes.fixup_date(document: DocumentNode)

If the date in the document is a string, try to parse it to produce a datetime object.

class liara.nodes.FixupDateTimezone

Set the timezone of the metadata['date'] field to the local timezone if no timezone has been set.

Initialization

class liara.nodes.DocumentNode(src, path: pathlib.PurePosixPath, metadata_path: Optional[pathlib.Path] = None)

Bases: liara.nodes.Node

content: str | None = None
set_fixups(*, load_fixups, process_fixups) None

Set the fixups that should be applied to this document node. The fixups should be set before calling load().

Parameters:
  • load_fixups – These functions will be executed before load() returns.

  • process_fixups – These functions will be executed before process() returns.

load()

Load the content of this node.

validate_metadata()
reload()

Reload this node from disk.

By default, this just forwards to _load().

publish(publisher: liara.nodes.Publisher) pathlib.Path

Publish this node using the provided publisher.

class liara.nodes.HtmlDocumentNode(src, path: pathlib.PurePosixPath, metadata_path: Optional[pathlib.Path] = None)

Bases: liara.nodes.DocumentNode

A node representing a Html document.

Initialization

process(cache: liara.cache.Cache, **kwargs)
class liara.nodes.MarkdownDocumentNode(configuration, **kwargs)

Bases: liara.nodes.DocumentNode

A node representing a Markdown document.

Initialization

process(cache: liara.cache.Cache, **kwargs)
class liara.nodes.DataNode(src: pathlib.Path, path: pathlib.PurePosixPath)

Bases: liara.nodes.Node

A data node.

Data nodes consist of a dictionary. This can be used to store arbitrary data as part of a liara.site.Site, and make it available to templates (for instance, a menu structure could go into a data node.)

Initialization

class liara.nodes.IndexNode(path: pathlib.PurePosixPath, metadata: Optional[Dict] = None)

Bases: liara.nodes.Node

An index node.

Index nodes are created for every folder if there is no _index node present, and from indices. An index node can optionally contain a list of references, in case the referenced nodes by this index are not direct children of this node.

Initialization

references: List[liara.nodes.Node] = None

Nodes referenced by this index node.

An index can not rely on using children as those have to be below the path of the parent node. The references list allows to reference nodes elsewhere in the site.

add_reference(node)

Add a reference to an arbitrary node in the site.

publish(publisher) pathlib.Path

Publish this node using the provided publisher.

class liara.nodes.GeneratedNode(path: pathlib.PurePosixPath, metadata: Optional[Dict] = None)

Bases: liara.nodes.Node

generate() None

Generate the content of this node.

After this function has finished, self.content must be populated with the generated content.

publish(publisher: liara.nodes.Publisher)

Publish this node using the provided publisher.

class liara.nodes.RedirectionNode(path: pathlib.PurePosixPath, dst: pathlib.PurePosixPath, *, base_url='')

Bases: liara.nodes.GeneratedNode

A redirection node triggers a redirection to another page.

This node gets processed into a simple web site which tries to redirect using both <meta http-equiv="refresh"> and Javascript code setting window.location.

Initialization

generate()
class liara.nodes.ResourceNode(src, path: pathlib.PurePosixPath, metadata_path=None)

Bases: liara.nodes.Node

A resource node applies some process when creating the output.

This is useful if you have content where the source cannot be interpreted, and requires some process first before it becomes usable – for instance, SASS to CSS compilation.

Initialization

reload() None
publish(publisher: liara.nodes.Publisher) pathlib.Path

Publish this node using the provided publisher.

class liara.nodes.SassResourceNode(src, path: pathlib.PurePosixPath, metadata_path=None)

Bases: liara.nodes.ResourceNode

This resource node compiles .sass and .scss files to CSS when built.

Initialization

set_compiler(compiler: liara.nodes._SASS_COMPILER)
reload() None
process(cache: liara.cache.Cache, **kwargs)
liara.nodes.NT = 'TypeVar(...)'
class liara.nodes.NodeFactory

Bases: typing.Generic[liara.nodes.NT]

A generic factory for nodes, which builds nodes based on the file type.

Initialization

property known_types
register_type(suffixes: Union[str, Iterable[str]], node_type: type, *, extra_args: Dict[str, Any] = dict()) None

Register a new node type.

Parameters:
  • suffixes – Either one suffix, or a list of suffixes to be registered for this type. For instance, a node representing an image could be registered to [.jpg, .png, .webp].

  • node_type – The type of the node to be created.

  • extra_args – A dictionary of additional arguments for the node constructor. This dictionary gets passed as **kwargs into the node constructor.

create_node(suffix: str, src: pathlib.Path, path: pathlib.PurePosixPath, metadata_path: Optional[pathlib.Path] = None) liara.nodes.NT

Create a node using the provided parameters.

class liara.nodes.ResourceNodeFactory(configuration)

Bases: liara.nodes.NodeFactory[liara.nodes.ResourceNode]

A factory for resource nodes.

Initialization

class liara.nodes.DocumentNodeFactory(configuration)

Bases: liara.nodes.NodeFactory[liara.nodes.DocumentNode]

A factory for document nodes.

Initialization

class liara.nodes.StaticNode(src: pathlib.Path, path: pathlib.PurePosixPath, metadata_path=None)

Bases: liara.nodes.Node

A static data node.

Static nodes are suitable for large static data which never changes, for instance, binary files, videos, images etc.

Initialization

src: pathlib.Path = None
update_metadata() None

Update metadata by deriving some metadata from the source file, if possible.

For static nodes pointing to images, this will create a new metadata field image_size and populate it with the image resolution.

property is_image

Return True if this static file is pointing to an image.

publish(publisher: liara.nodes.Publisher) pathlib.Path

Publish this node using the provided publisher.

class liara.nodes.ThumbnailNode(src: pathlib.Path, path: pathlib.PurePosixPath, size: Dict[str, int], format: str | None = 'original')

Bases: liara.nodes.ResourceNode

process(cache: liara.cache.Cache, **kwargs) liara.nodes._AsyncThumbnailTask | None