API Documentation

If you are looking for information on a specific function, class, or method, this part of the documentation covers all the interfaces of Rost.

Public API

This part of the documentation lists the full API reference of all public classes and functions.

class rost.Rost(searchpath='templates', outputpath='dist', staticpaths=None, context=None, contexts=None, merge_contexts=False, filters=None, before_callback=None, after_callback=None)

Simple Jinja2 static page generator.

Parameters

  • searchpath (str, optional) – A string representing the name of the directory to search for templates. Defaults to 'template'.

  • outputpath (str, optional) – A string representing the name of the directory that the Site should store rendered files in. Defaults to 'dist'.

  • staticpaths (list, optional) – A list of directories to get static files from (relative to searchpath). Defaults to None.

  • context (dict, optional) – A context that should be available all the time to all templates. Defaults to {}.

  • contexts (list, optional) – A list of “regex, context” pairs. Each context is either a dictionary or a function that takes either no argument or or the current template as its sole argument and returns a dictionary. The regex, if matched against a filename, will cause the context to be used. Defaults to [].

  • merge_context (bool, optional) – A boolean value. If set to True, then all matching regex from the contexts list will be merged (in order) to get the final context. Otherwise, only the first matching regex is used. Defaults to False.

  • filters (dict, optional) – A dictionary of Jinja2 filters to add to the Environment. Defaults to {}.

  • before_callback (func, optional) – A callback function called before the project is build. Defaults to None.

  • after_callback (func, optional) – A callback function called after the project is build. Defaults to None.

build()

Build the project.

clear_build()

Clear previous build.

copy_assets()

Copy static assets such as CSS or JavaScript.

is_ignored(template_name)

Check if a template should be ignored.

Parameters

template_name – A string representing the name of the file to check.

is_partial(template_name)

Check if a template is a partial template.

Parameters

template_name – A string representing the name of the file to check.

is_static(template_name)

Check if a template is a static template. Static templates are copied, rather than compiled using Jinja2.

A template is considered static if it lives in any of the directories specified in staticpaths.

Parameters

template_name – A string representing the name of the file to check.

is_template(template_name)

Check if a file is a template.

Parameters

template_name – A string representing the name of the file to check.

render_template(template)

Render a Jinja2 template.

render_templates()

Render the Jinja2 templates.

watch(monitorpaths=None, bind='localhost', port=8080, use_livereload=False)

Start an development server and re-build the project if the source directory for change.

By default the self.searchpath and self.staticpaths are monitored.

Parameters

  • monitorpaths (list of Paths, optional) – A list of paths to monitor. Defaults to None.

  • bind (str, optional) – A string representing the bind address. Defaults to 'localhost'.

  • port (int, optional) – A int representing the port. Defaults to 8080.

  • use_livereload (bool, optional) – If set to true will use the liverload server. Defaults to False.

rost.build(searchpath='templates', outputpath='dist', staticpaths=None, context=None, filters=None, contexts=None, merge_contexts=False)

Build the project.

Optional keyword arguments correspond to the instance attributes of Rost.

rost.watch(searchpath='templates', outputpath='dist', staticpaths=None, monitorpaths=None, context=None, filters=None, contexts=None, merge_contexts=False, bind='localhost', port=8080, use_livereload=False)

Start an development server and re-build the project if the source directory for change.

Optional keyword arguments correspond to the instance attributes of Rost.

Private API

This part of the documentation lists the full API reference of all private classes and functions.

class rost.server.WebServer(root='.', bind='localhost', port=8080)

This class creates a server that serves files from the directory directory and below, or the current directory if directory is not provided, directly mapping the directory structure to HTTP requests.

Parameters

  • root (str or Path, optional) – A directory relative to which it should serve the files. Defaults to ..

  • bind (str, optional) – A specific address to which the server should bind. Defaults to localhost.

  • port (int, optional) – A specific port to which the server should lissen. Defaults to 8080.

serve()

Start the server.

class rost.monitor.FileMonitor(monitorpaths, callback)

This class creates an observer thread that is watching the provided directories and dispatches callback calls.

Parameters

  • monitorpaths (list of Path) – A list of paths to monitor.

  • callback (callable) – A callable to call when a file from monitorpaths changes.

start()

Starts the file monitoring service.

stop()

Stops the file monitor service.

class rost.reloader.LiveReloader(monitorpaths, callback, root='.', bind='localhost', port=8080)

Initialize a livereload server and watch file changes.

Parameters

  • monitorpaths (list of Path) – A list of paths to monitor.

  • callback (callable) – A callable to call when a file from monitorpaths changes.

  • root (str or Path, optional) – A directory relative to which it should serve the files. Defaults to ..

  • bind (str, optional) – A specific address to which the server should bind. Defaults to localhost.

  • port (int, optional) – A specific port to which the server should lissen. Defaults to 8080.

serve()

Start the server.

start()

This methods does’t do anything. It’s only propose is to comform with the Monitor interface.

The serve methods also starts the observer thread that is watching the provided directories.

stop()

This methods does’t do anything. It’s only propose is to comform with the Monitor interface.

Stoping the server will stop the observer thread that is watching the provided directories.