API

Folio is an static website generator using jinja2 template engine.

class folio.Folio(import_name, source_path='src', build_path='build', encoding='utf-8', extensions=(), jinja_extensions=())

The project. This is the main (and only?) object for creating a Folio.

The basic example is:

from folio import Folio
proj = Folio(__name__)
proj.build()

You could also call the run method to start a local web server and watch for modified files.

Parameters:

• import_name – Projects’s name.
• source_path – Source directory that contains the templates to be processed and the static files to be copied to the build directory. Defaults to 'src' in the project’s root.
• build_path – Destination directory where the final HTML will be generated. Defaults to 'build' in the project’s root.
• encoding – The template’s encoding. Defaults to utf-8.
• extensions – List of Folio extensions to load and register.
• jinja_extensions – Jinja2 extensions.

add_builder(pattern, builder)

Adds a new builder related with the given file pattern. If the pattern is a iterable, will add several times the same builder.

Parameters:

• pattern – One or more file patterns.
• builder – The builder to be related with the file pattern(s).

add_context(pattern, context)

Add a new context to the given pattern of a template name. If the pattern is a iterable, will add several times the same context.

Parameters:

• pattern – One or more template name patterns to add the context.
• context – The context itself or a function that will accept the jinja environment as first parameter and return the context for the template.

add_extension(extension)

Add an extension to the registry.

build()

Build templates to the build directory. It will create the build path if not exists, and build all matched templates.

build_path = None

The destination directory to copy the static content and create the builded templates.

build_template(template_name)

Build a template with it’s corresponding builder.

The builder is responsible of generating the destination file in the destination path. It won’t be checked for that the file was really created.

The builder will be called with the jinja environment, the template name, a dictionary with the context, the source and destination paths and the output encoding.

Parameters:template_name – The template name to build.

builders = None

Builders are the core of folio, this will link a filename match with a build function that will be responsible of translating templates into final HTML files.

The default builder is given, this will treat all HTML files as jinja2 templates and process them, generating the same template name as output file in the build directory.

config = None

Make the configuration dictionary.

context(pattern)

A decorator that is used to register a context function for a given template. This make the same thing as the method add_context passed with a function.

A basic example:

@proj.context('articles/index.html')
def articles_context(env):
    return {'articles': [
        ('2012-12-31', 'Happy New Year', 'articles/2013.html'),
        ('2012-10-11', 'Hello World', 'articles/helloworld.html')
    ]}

Parameters:pattern – The template name pattern (or more than one) to make a context.

contexts = None

The context generators per template. The template name is store as key and the callback as value. It will call the function, with the jinja2 environment as first parameters, for the template in the build process. The function must return a dictionary to be used in the template.

Context functions are registered like this:

@proj.context('index.html')
def index_context(jinja2_env):
    return {'files': jinja2_env.list_templates(),
            'author': 'Me'}

Then in the template you could use it as normal variables.

The template name passed to the context can be a list of patterns for a filename, so you could apply the same context to series of templates:

@proj.context(['feed.atom', '*.rss'])
def feed(jinja2_env):
    return {'desc': 'A site about nothing'}

Only the jinja environment is passed to the context function. If you need more control, you should write an extension.

default_config = {'JINJA_EXTENSIONS': [], 'STATIC_BUILDER_PATTERN': '*', 'TESTING': False, 'EXTENSIONS': [], 'DEBUG': False, 'TEMPLATE_BUILDER_PATTERN': '*.html'}

The default configuration dictionary.

encoding = None

The source encoding for templates. Default to utf-8.

env = None

The jinja environment is used to make a list of the templates, and it’s used by the builders to dump output files.

extensions = None

Define the Folio extensions registry.

get_builder(template_name)

Returns the builder for the given template name or None if there are not related builders.

Parameters:template_name – The template name to lookup the builder for.

get_context(template_name)

Returns a context for the given template. If more that one context are assigned to the template name, there are going to be merged all together in the order that has been added. If a context is a callable it will be called with the jinja environment as first argument.

A basic example:

proj.add_context('index.html', {'name': 'Juan', 'files': [])
proj.add_context('index.html', lambda env: {'name': 'Flor'})
proj.get_context('index.html')
# Returns {'name': 'Flor', 'files': []}

Parameters:template_name – The template name to retrieve the context.

import_name = None

The name of the project. It’s used for logging and can improve debugging information.

import_path

Retrieve the import path (or root path) from the import name module file.

The module has to be already loaded as this function doesn’t support loaders/finders. If the module is not already loaded, the current working directory will be used instead.

init_config()

Initialize the configuration.

is_template(filename)

Return true if a file is considered a template. The default behavior is to ignore all hidden files and the ones that start with and underscore.

New in version 0.2: Will ignore files inside directories that starts with a dot or an underscore.

Parameters:filename – The (possible) template filename.

jinja_loader

Create a Jinja loader.

list_templates()

Returns a list of templates.

logger

The project logger, an instance of the :class: logging.Logger.

The default configuration is to log to stderr if the application is in debug mode.

register_extension(extension)

Registers a new extension.

Extensions can be used to add extra functionality to Folio. As they are created by this instance they cannot accept any arguments for configuration.

If the extension is an string, it will try to load it from the buildin extension package, or as folio_<extname>.

The extension could have an register function that will be called with the Folio project instance as first argument.

Parameters:extension – The extension itself or an string of the extension name that could be found inside the build-in package or as folio_<extname>.

source_path = None

The source directory from where the templates will be parsed.

translate_template_name(template_name)

Translate the template name to a destination filename. For the moment this will return the same filename.

Because is used by the static builder, this will not try to change the template name extension to HTML.

Parameters:template_name – The input template name.