Internals

Core

class core.Node(source_dir, name)

Node of the site tree.

name

Name.

children

List of child nodes.

source_dir

Path of the directory reflected by this node.

parent

Parent node.

add_child(node)

Adds node to the child nodes.

get_child(name)

First tries to find and return immediate child called name. Then continues search by calling get_child on every immediate child PageNode. If nothing found, returns None.

find_descendant(path)

Returns descendant node identified by path. If nothing found, returns None.

get_slug(intermediate=False)

Returns node slug – string used to build page URL.

Slug can vary depend on where it’s going to be used: in the middle of the URL (in that case intermediate is True) or in the end (intermediate is False).

get_path()

Returns node path.

get_slugs()

Returns ancestor nodes slugs ordered from top (root) to bottom (this node).

class core.PageNode(source_dir, index)

Represents pages created during automatic pagination (see paginate_tree()). Subclasses Node.

index

1-based index.

get_slug(intermediate=False)

If node represents first page or if slug going to be used in the middle of the URL, returns empty string. Otherwise returns node name.

core.create_tree(page_dir, page_name)

Creates tree that reflects the structure of page_dir.

core.sort_tree(node, ordering_dict)

Recursively sorts the tree according to the ordering_dict – a dictionary where keys are node paths and values are the following:

1. 'alphabetically': children will be sorted by their names
2. names list: children will be sorted in the order in which their names appear in the list (see utils.sort())
3. callable: will be called with list of children and must return it sorted.

core.paginate_tree(node, pagination_dict)

Recursively paginates tree according to the pagination_dict – a dictionary where keys are node paths and values are the numbers of the items per page (let’s denote it n).

If node path is in pagination_dict, it’s children detached from it, split into the chunks of size n and then each chunk attached back to the node through intermediate PageNode.

core.fill_tree(node, language=None)

Recursively walks the tree and annotates each node with context.

Calls utils.read_context() and combines it’s result with the following data:

• NAME: node.name;
• PATH: node.get_path();
• LANGUAGE: language;
• CHILDREN: list of the child contexts;
• SIBLINGS: list of the sibling contexts;
• PARENT: parent’s context;
• PREV_SIBLING, NEXT_SIBLING: adjacent siblings contexts.

core.build_site(jinja2_env, build_dir, node, root=None)

Given the site tree, builds the site. The main steps are the following:

1. Build chidren subtrees;
2. Determine index.html directory (which is basically build_dir-related url of node);
3. Define which template to use based on a LAYOUTS setting;
4. Render template with node context and write result to index.html.

core.url_for(root, path, language=None)

If page at path exists, returns it’s root-relative URL; otherwise throws an exception.

core.build_(source_dir, build_dir, static_dir, language=None)

1. Creates the tree from source_dir (create_tree()), sorts it (sort_tree()), paginates (paginate_tree()) and fills with contexts in given language (fill_tree());
2. Tries to load translation from ./translations/<language>.po;
3. Creates Jinja2 environment with webassets and i18n extensions and passes it to build_site().

Translations

i18n.get_translations(po_file_path)

Creates gettext.GNUTranslations from PO file po_file_path.

i18n.extract_translations(jinja2_env, target_pot_file)

Produces a target_pot_file which contains a list of all the translatable strings extracted from the templates.

Server

class server.EventHandler(project_dir, new_changes_event)

Watches all files except those that are hidden or are in the hidden directory.

Parameters:

• project_dir – project directory being watched
• new_changes_event (threading.Event) – event to be set when changes occur

class server.Shutdowner(http_server, new_changes_event)

Daemon thread that waits for the changes and then shuts down the server.

Parameters:

• http_server (BaseHTTPServer.HTTPServer) – server to be shut down
• new_changes_event (threading.Event) – event to be listened to

server.serve(host='localhost', port=8000)

Runs the development server at given host and port, watches the changes and regenerates the site.

Environments

Utils

class utils.RegexResolver(items)

Provides the facility to return the first matched value from the list of (regexp, value) pairs.

Parameters:items – List of tuples (compiled regexp, value)

get(key, default=None)

Returns the first matched value or default.

Parameters:key – basestring that will be sequentially tested with all regexps from items list

utils.patterns(*args)

Helper to create RegexResolver. Example:

LAYOUTS = patterns(
    (r'^content$', 'content.html'),
    (r'^content/.*$', 'speech.html'),
    (r'^.*$', 'page.html'),
)

utils.sort(list_, order, key=None)

Sorts list_ by explicitly specified order.

>>> sort(['a', 'b', 'c'],
...      ['c', 'b', 'xxx', 'a', 'yyy'])
['c', 'b', 'a']

>>> sort(['a', 'b', 'c', 'd'],
...      ['c', 'b', 'a'])
['c', 'b', 'a', 'd']

>>> sort([('a', 1), ('b', 2)],
...      ['b', 'a'],
...      key=lambda el: el[0])  # Sort tuples by first element
[('b', 2), ('a', 1)]

utils.paginate(items, items_per_page)

Splits items list into lists of size items_per_page.

>>> paginate([1, 2, 3], 1)
[[1], [2], [3]]

>>> paginate([1, 2, 3, 4, 5, 6, 7], 3)
[[1, 2, 3], [4, 5, 6], [7]]

>>> paginate([], 3)
[]

utils.yield_files(dir_, suffix)

Yields files from directory which name ends with suffix.

utils.read_context(dir_, language=None)

Searches dir_ for markdown- and yaml-files and returns context dictionary with parsed data.

Markdown and YAML files are files which names matched to <name>.(md|yaml) or <name>.<language>.(md|yaml) pattern if language specified.

First parses each Markdown file and puts result into context under the <name> key. Then parses each YAML file and updates context with resulting dictionary (note: update will override markdown data if there are duplicate keys).

utils.get_template_source(jinja2_env, template)

Returns the source text of the given template.