liara.site

Module Contents

Classes

Collection

A collection is a set of nodes. Collections can be ordered, which allows for next/previous queries.

Index

ContentFilter

Content filters can filter out nodes based on various criteria.

DateFilter

Filter content based on the metadata field date.

StatusFilter

Filter content based on the metadata field status.

ContentFilterFactory

Site

This class manages to all site content.

API

class liara.site.Collection(site: liara.site.Site, name: str, pattern: str, *, exclude_without: Optional[List[Union[str, Tuple[str, Any]]]] = None, order_by: Optional[Union[str, List[str]]] = None, node_kinds: Optional[List[Union[str, liara.nodes.NodeKind]]] = None)

A collection is a set of nodes. Collections can be ordered, which allows for next/previous queries.

Initialization

Create a new collection.

Parameters:
  • pattern – The pattern to select nodes which belong to this collection.

  • exclude_without – Exclude items without the specified metadata fields. If a tuple is provided, the metadata field’s value must match the requested value.

  • order_by – A list of accessors for fields to order by. If multiple entries are provided, the result will be sorted by each in order using a stable sort. To reverse the order, use a leading -, for example: -date.

  • node_kinds – Only include nodes of that kinds. If not specified, NodeKind.Document will be used as the default.

If an ordering is specified, and a particular node cannot support that ordering (for instance, as it’s missing the field that is used to order by), an error will be raised.

property nodes: Iterable[liara.nodes.Node]

Get the (sorted) nodes in this collection.

get_next(node: liara.nodes.Node) Optional[liara.nodes.Node]

Get the next node in this collection with regard to the specified order, or None if this is the last node.

get_previous(node: liara.nodes.Node) Optional[liara.nodes.Node]

Get the previous node in this collection with regard to the specified order, or None if this is the first node.

class liara.site.Index(collection: liara.site.Collection, path: str, group_by: List[str], *, exclude_without: Optional[List[Union[str, Tuple[str, Any]]]] = None, create_top_level_index=False)

Initialization

Create a new index.

Parameters:
  • collection – The collection to use for this index.

  • path – The path pattern to create index entries at. This must contain one numbered placeholder (%1, etc.) per entry in group_by

  • group_by – The grouping statements. The nodes are grouped by each entry in this array in-order.

  • exclude_without – Exclude items without the specified metadata field. If a tuple is provided, the metadata field’s value must match the requested value.

  • create_top_level_index – Create a node at the top-level path as well instead of only creating nodes per grouping statement.

create_nodes(site: liara.site.Site)

Create the index nodes inside the specified site.

class liara.site.ContentFilter

Bases: abc.ABC

Content filters can filter out nodes based on various criteria.

abstract apply(node: liara.nodes.Node) bool

Return True if the node should be kept, and False otherwise.

property reason: str

Return a reason why this filter applied.

property name: str
class liara.site.DateFilter

Bases: liara.site.ContentFilter

Filter content based on the metadata field date.

If the date is in the future, the node will be filtered.

Initialization

apply(node: liara.nodes.Node) bool
property reason
property name
class liara.site.StatusFilter

Bases: liara.site.ContentFilter

Filter content based on the metadata field status.

If status is set to private, the node will be filtered. The comparison is case-insensitive.

apply(node: liara.nodes.Node) bool
property reason
property name
class liara.site.ContentFilterFactory

Initialization

create_filter(name: str) liara.site.ContentFilter
class liara.site.Site

This class manages to all site content.

Initialization

data: List[liara.nodes.DataNode] = None

The list of all data nodes in this site.

indices: List[liara.nodes.IndexNode] = None

The list of all index nodes in this site.

documents: List[liara.nodes.DocumentNode] = None

The list of all document nodes in this site.

resources: List[liara.nodes.ResourceNode] = None

The list of all resources nodes in this site.

static: List[liara.nodes.StaticNode] = None

The list of all static nodes in this site.

generated: List[liara.nodes.GeneratedNode] = None

The list of all generated nodes in this site.

metadata: Dict[str, Any] = None

Metadata describing this site.

register_content_filter(content_filter: liara.site.ContentFilter)

Register a new content filter.

set_metadata(metadata: Dict[str, Any]) None

Set the metadata for this site.

This overrides any previously set metadata. Metadata is accessible via the metadata attribute.

set_metadata_item(key: str, value: Any) None

Set a single entry in the metadata for this site.

This can be used to override individual metadata items.

property filtered_content: Dict[pathlib.PurePosixPath, str]

Return which node paths got filtered and due to which filter.

add_data(node: liara.nodes.DataNode) None

Add a data node to this site.

add_index(node: liara.nodes.IndexNode) None

Add an index node to this site.

add_document(node: liara.nodes.DocumentNode) None

Add a document to this site.

add_resource(node: liara.nodes.ResourceNode) None

Add a resource to this site.

add_static(node: liara.nodes.StaticNode) None

Add a static node to this site.

add_generated(node: liara.nodes.GeneratedNode) None

Add a generated node to this site.

property nodes: ValuesView[liara.nodes.Node]

The list of all nodes in this site.

property urls: KeysView[pathlib.PurePosixPath]

The list of all registered URLs.

This creates links between parents/children.

This is a separate step so it can be executed after merging nodes from multiple sources, for instance themes. It is safe to call this function multiple times to create new links; nodes which already have a parent are automatically skipped.

create_collections(collections)

Create collections.

create_indices(indices)

Create indices.

create_thumbnails(thumbnail_definition)

Create thumbnails.

Based on the thumbnail definition – which is assumed to be a dictionary containing the suffix, the desired size and the target formats – this function iterates over all static nodes that contain images, and creates new thumbnail nodes as required.

get_next_in_collection(collection: str, node: liara.nodes.Node) Optional[liara.nodes.Node]

Get the next node in a collection.

get_previous_in_collection(collection: str, node: liara.nodes.Node) Optional[liara.nodes.Node]

Get the previous node in a collection.

get_collection(collection: str) liara.site.Collection

Get a collection.

get_node(path: Union[str, pathlib.PurePosixPath]) Optional[liara.nodes.Node]

Get a node based on the URL, or None if no such node exists.

select(query: str) Iterable[liara.nodes.Node]

Select nodes from this site.

The query string may contain * to list all direct children of a node, and ** to recursively enumerate nodes. Partial matches using *foo are not supported. See URL patterns for details.

property merged_data: types.MappingProxyType[str, Any]

Return the union of all data nodes.

This is a read-only view, as shortcodes and templates can access the data in any order and thus modifications would be unsafe.

Added in version 2.6.2.