`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`	A generated node.
`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`	A thumbnail node, derived from a static image file.

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.

abstractmethod publish_document(document: liara.nodes.DocumentNode) → pathlib.Path¶

Publish a document node.

Returns:: The path of the generated file.

abstractmethod publish_index(index: liara.nodes.IndexNode) → pathlib.Path¶

Publish an index node.

Returns:: The path of the generated file.

abstractmethod publish_resource(resource: liara.nodes.ResourceNode) → pathlib.Path | None¶

Publish a resource node.

Returns:: The path of the generated file, or None if no file content was generated.

abstractmethod publish_static(static: liara.nodes.StaticNode) → pathlib.Path¶

Publish a static node.

Returns:: The path of the generated file.

abstractmethod publish_generated(generated: liara.nodes.GeneratedNode) → pathlib.Path | None¶

Publish a generated node.

Returns:: The path of the generated file, or None if no file content was generated.

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.

liara.nodes.fixup_relative_links(document: DocumentNode)¶: 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

A generated node.

A generated node synthesizes all its content by itself, not referencing a single node as an input. For example, redirections or feeds are generated based off site-level data.

Initialization

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 | None¶: 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] | None = None) → None¶

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.

Static nodes have always a valid src.

Initialization

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.

For all static nodes, this will populate $size with the file size.

Changed in version 2.7.3: image_size was renamed to $image_size, and $size was added.

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: tuple[int, int], format: str | None = 'original')¶

Bases: liara.nodes.ResourceNode

A thumbnail node, derived from a static image file.

The thumbnail node is a resource node which holds the thumbnail of an image.

Initialization

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

liara.nodes¶

Module Contents¶

Classes¶

Functions¶

Data¶

API¶

`liara.nodes`¶