Page building and views¶

class optimus.pages.registry.PageRegistry(templates={})[source]¶

Page registry.

Index templates and memorize page destination that use them.

Keyword Arguments:: templates (dict) – Initial element dictionnary. Default to an empty dict.

templates¶

Dictionnary indexed on template names which contain destinations using them.

Type:: string

destinations_pages_index¶

Dictionnary indexed on destinations which contain their related page view.

Type:: string

logger¶

Optimus logger.

Type:: logging.Logger

add_page(page, templates)[source]¶

Add a page to registry.

Parameters:

page (optimus.pages.views.PageViewBase) – Page instance
templates (list) – List of templates names to link to given page instance.

add_data(page, datas)[source]¶

Index view datas into registry.

Parameters:

page (optimus.pages.views.PageViewBase) – Page instance
datas (list) – List of view datas to link to given page instance.

get_pages_from_template(template_name)[source]¶

Get page list depending from a template.

This method is not safe out of the context of scanned pages, because it use an internal map builded from the scan use by the add_page method. In short, it will raise a KeyError exception for every destination that is unknowned from internal map.

Parameters:: template_name (string) – Template name to search for.
Returns:: List of page instances depending from given template name.
Return type:: list

get_pages_from_data(data)[source]¶

Get page list depending from a data.

Parameters:: data (string) – Source to search for.
Returns:: List of page instances depending from given data path.
Return type:: list

get_all_destinations()[source]¶

Return all registered destinations

Returns:: List of all page destinations.
Return type:: list

get_all_pages()[source]¶

Return all registered pages

Returns:: List of all page instances.
Return type:: list

class optimus.pages.builder.PageBuilder(settings, jinja_env=None, assets_env=None, dry_run=False)[source]¶

Builder class to init Jinja2 environment and build given pages.

Parameters:

settings (conf.model.SettingsModel) – Settings registry instance.

Keyword Arguments:

jinja_env (jinja2.Jinja2Environment) – Jinja2 environment. Default is None.
assets_env (webassets.Environment) – Webasset environment. Default is None.
dry_run (boolean) – Enable dry run mode. Default is False.

logger¶

Optimus logger.

Type:: logging.Logger

settings¶

Settings registry instance.

Type:: conf.model.SettingsModel

jinja_env¶

Jinja2 environment. Default is None.

Type:: jinja2.Jinja2Environment

assets_env¶

Webasset environment. Default is None.

Type:: webassets.Environment

internationalized¶

Indicate if internationalization is enabled. Will be automatically set to True if Jinja environment enable the i18n extension.

Type:: boolean

translations¶

Dictionnary of translation catalog indexed on language identifier.

Type:: dict

registry¶

Registry of all knowed page from scanning. Registry will be automatically filled only if you use the PageBuilder.scan_bulk(..) method.

Type:: optimus.pages.registry.PageRegistry

dry_run¶

Dry run mode.

Type:: boolean

get_environnement(assets_env=None)[source]¶

Init and configure Jinja environment.

Automatically enable some extensions and link possible asset environment.

Keyword Arguments:: assets_env (webassets.Environment) – Webasset environment. Default is None. If empty, webassets will not be available from page templates.
Returns:: Configured Jinja2 environment.
Return type:: jinja2.Jinja2Environment

serialize_settings()[source]¶

Get and return valid settings variables.

Valid settings means only variable names full uppercase.

Returns:: Settings variables.
Return type:: dict

get_globals()[source]¶

Get global context variables.

Returns:: Shortcuts to some common settings like SITE options, static urls, Optimus version and finally all settings contained in _SETTINGS.
Return type:: dict

get_translation_for_item(page_item)[source]¶

Try to load the translations for the page language if any, then install it in Jinja2.

It does not reload a language translations if a previous page has allready loaded it.

Parameters:: page_item (optimus.pages.views.PageViewBase) – Page instance which its language identifier will be used to search for translation catalog.
Returns:: Translations object to give to Jinja i18n extension.
Return type:: babel.support.Translations

scan_item(page_item)[source]¶

Scan given page to retrieve template dependancies.

Possibly connect settings to page instance if not allready done.

Parameters:: page_item (optimus.pages.views.PageViewBase) – Page instance.
Returns:: All used templates from given page.
Return type:: string

scan_bulk(page_list)[source]¶

Scan all given pages to register their dependancy templates.

Parameters:: page_list (list) – List of page instances.
Returns:: Every template names involved in scanned page instances.
Return type:: set

build_item(page_item)[source]¶

Build given page.

Possibly connect settings to page instance if not allready done.

Parameters:: page_item (optimus.pages.views.PageViewBase) – Page instance.
Returns:: Destination path from builded page.
Return type:: string

build_bulk(page_list)[source]¶

Build all given pages.

Return all the effective builded pages

Parameters:: page_list (list) – List of page instances.
Returns:: List of destination paths from builded pages.
Return type:: list

class optimus.pages.views.PageViewBase(**kwargs)[source]¶

Base view object for a page.

You can set class attributes at the init if needed.

Only lang and context attributes are optional, so take care to set all the required ones because their default value is None. You should not use directly PageViewBase, inherit it in a common object with all attributes setted by default.

Template context will have the following variables :

page_title: Page title.
page_destination: Page destination, the path is relative to the build directory.
page_lang: Defined view langage if any.
page_datas: Sources related to the page building.

You can add extra variable if needed. The default context variables can not be overriden from the context class attribute, only from the get_context class method.

View need settings to be defined either as argument on instance init or later through attribute setter.

title¶

Page title.

Type:: string

destination¶

Page destionation path relative to build directory.

Type:: string

lang¶

Language identifier or an instance of optimus.i18n.LangBase.

Type:: string

datas¶

Sources related to the page building. If the page use these files to perform a rendering build, they should be defined here so the watcher will be able to know them and trigger a new build when these files are modified.

Type:: list

context¶

Initial page view context.

Type:: dict

logger¶

Optimus logger.

Type:: logging.Logger

_used_templates¶

List of every used templates. Only filled when introspect() method is executed. Default to None.

Type:: list

__settings¶

Settings registry instance when given in kwargs. Default to None.

Type:: conf.model.SettingsModel

Parameters:: **kwargs – Arbitrary keyword arguments. Will be added as object attribute.

validate()[source]¶

Validate every required attribute is set.

Returns:: True if requirements are set.
Return type:: boolean

property settings¶

settings attribute getter, check settings have been correctly defined.

Returns:: Settings registry instance when given in kwargs. Default to None.
Return type:: conf.model.SettingsModel

get_title()[source]¶

Get page title.

Default behavior is to use page attribute title.

Returns:: Page title.
Return type:: string

get_lang()[source]¶

Get page language object.

Returns:: Language object. If lang page attribute is None it will create a language object using default language identifier from setting LANGUAGE_CODE.
Return type:: optimus.i18n.LangBase

get_destination()[source]¶

Get page destination path.

Returns:: Page destination path relative to build directory.
Return type:: string

get_datas()[source]¶

Get related page data file paths.

Default behavior is to use page attribute datas.

Returns:: Page datas.
Return type:: list

get_relative_position()[source]¶

Get relative path position from the destination file to the root.

Returns:: Either something like “../../” if the destination is in subdirectories or “./” if at the root. Won’t never return empty string.
Return type:: string

get_context()[source]¶

Get view context.

Returns:: Template context of variables.
Return type:: dict

render(env)[source]¶

Base rendering method does not render anything and always return an empty string. You will have to implement the render method yourself or see PageTemplateView instead if you just want to render a template.

Although it is does not implement any template logic, this method set the Jinja environment.

Parameters:: env (jinja2.Jinja2Environment) – Jinja environment.
Returns:: An empty string.
Return type:: string

introspect(env)[source]¶

Dummy introspect method for base view required for internal code like watchers that may use it.

This does not implement any introspection since there is not template logic here and this method is mostly used from the template watcher.

Parameters:: env (jinja2.Jinja2Environment) – Jinja environment.
Returns:: Empty list.
Return type:: list

class optimus.pages.views.PageTemplateView(**kwargs)[source]¶

Extend the PageViewBase class to add logic about templates for HTML rendering.

Additionnally to the base view, the context will have the following variables :

page_template_name: Template name used to compile the page HTML

template_name¶

Page template file path relaive to templates directoy. Used as Python template string with optional non positional argument {{ language_code }} available for internationalized pages.

Type:: string

get_template_name()[source]¶

Get template file path.

Returns:: Template file path relative to templates directory.
Return type:: string

_recurse_template_search(env, template_name)[source]¶

Load involved template sources from given template file path then find their template references.

Parameters:

env (jinja2.Jinja2Environment) – Jinja environment.
template_name (string) – Template file path.

Returns:

List of involved templates sources files.

Return type:

list

get_context()[source]¶

Augment method from base view to insert variables related to templates.

Returns:: Template context of variables.
Return type:: dict

introspect(env)[source]¶

Take the Jinja2 environment as required argument to find every templates dependancies from page.

Parameters:: env (jinja2.Jinja2Environment) – Jinja environment.
Returns:: List of involved templates sources files.
Return type:: list

render(env)[source]¶

Take the Jinja2 environment as required argument.

Parameters:: env (jinja2.Jinja2Environment) – Jinja environment.
Returns:: HTML builded from page template with its context.
Return type:: string