cli.create.role package¶

Module contents¶

Compatibility wrapper.

This package was migrated from a flat module (role.py) to a package layout:: role/__main__.py contains the original implementation.

We re-export the public API so existing imports keep working.

class cli.create.role.Environment(block_start_string: str = '{%', block_end_string: str = '%}', variable_start_string: str = '{{', variable_end_string: str = '}}', comment_start_string: str = '{#', comment_end_string: str = '#}', line_statement_prefix: str | None = None, line_comment_prefix: str | None = None, trim_blocks: bool = False, lstrip_blocks: bool = False, newline_sequence: te.Literal['\n', '\r\n', '\r'] = '\n', keep_trailing_newline: bool = False, extensions: ~typing.Sequence[str | ~typing.Type[Extension]] = (), optimized: bool = True, undefined: ~typing.Type[~jinja2.runtime.Undefined] = <class 'jinja2.runtime.Undefined'>, finalize: ~typing.Callable[[...], ~typing.Any] | None = None, autoescape: bool | ~typing.Callable[[str | None], bool] = False, loader: BaseLoader | None = None, cache_size: int = 400, auto_reload: bool = True, bytecode_cache: BytecodeCache | None = None, enable_async: bool = False)¶

Bases: object

The core component of Jinja is the Environment. It contains important shared variables like configuration, filters, tests, globals and others. Instances of this class may be modified if they are not shared and if no template was loaded so far. Modifications on environments after the first template was loaded will lead to surprising effects and undefined behavior.

Here are the possible initialization parameters:

block_start_string
The string marking the beginning of a block. Defaults to '{%'.

block_end_string
The string marking the end of a block. Defaults to '%}'.

variable_start_string
The string marking the beginning of a print statement. Defaults to '{{'.

variable_end_string
The string marking the end of a print statement. Defaults to '}}'.

comment_start_string
The string marking the beginning of a comment. Defaults to '{#'.

comment_end_string
The string marking the end of a comment. Defaults to '#}'.

line_statement_prefix
If given and a string, this will be used as prefix for line based statements. See also line-statements.

line_comment_prefix
If given and a string, this will be used as prefix for line based comments. See also line-statements.

Added in version 2.2.

trim_blocks
If this is set to True the first newline after a block is removed (block, not variable tag!). Defaults to False.

lstrip_blocks
If this is set to True leading spaces and tabs are stripped from the start of a line to a block. Defaults to False.

newline_sequence
The sequence that starts a newline. Must be one of '\r', '\n' or '\r\n'. The default is '\n' which is a useful default for Linux and OS X systems as well as web applications.

keep_trailing_newline
Preserve the trailing newline when rendering templates. The default is False, which causes a single newline, if present, to be stripped from the end of the template.

Added in version 2.7.

extensions
List of Jinja extensions to use. This can either be import paths as strings or extension classes. For more information have a look at the extensions documentation.

optimized
should the optimizer be enabled? Default is True.

undefined
Undefined or a subclass of it that is used to represent undefined values in the template.

finalize
A callable that can be used to process the result of a variable expression before it is output. For example one can convert None implicitly into an empty string here.

autoescape
If set to True the XML/HTML autoescaping feature is enabled by default. For more details about autoescaping see Markup. As of Jinja 2.4 this can also be a callable that is passed the template name and has to return True or False depending on autoescape should be enabled by default.

Changed in version 2.4: autoescape can now be a function

loader
The template loader for this environment.

cache_size
The size of the cache. Per default this is 400 which means that if more than 400 templates are loaded the loader will clean out the least recently used template. If the cache size is set to 0 templates are recompiled all the time, if the cache size is -1 the cache will not be cleaned.

Changed in version 2.8: The cache size was increased to 400 from a low 50.

auto_reload
Some loaders load templates from locations where the template sources may change (ie: file system or database). If auto_reload is set to True (default) every time a template is requested the loader checks if the source changed and if yes, it will reload the template. For higher performance it’s possible to disable that.

bytecode_cache
If set to a bytecode cache object, this object will provide a cache for the internal Jinja bytecode so that templates don’t have to be parsed if they were not changed.

See bytecode-cache for more information.

enable_async
If set to true this enables async template execution which allows using async functions and generators.

add_extension(extension: str | Type[Extension]) → None¶: Adds an extension after the environment was created.

Added in version 2.5.

call_filter(name: str, value: Any, args: Sequence[Any] | None = None, kwargs: Mapping[str, Any] | None = None, context: Context | None = None, eval_ctx: EvalContext | None = None) → Any¶

Invoke a filter on a value the same way the compiler does.

This might return a coroutine if the filter is running from an environment in async mode and the filter supports async execution. It’s your responsibility to await this if needed.

Added in version 2.7.

call_test(name: str, value: Any, args: Sequence[Any] | None = None, kwargs: Mapping[str, Any] | None = None, context: Context | None = None, eval_ctx: EvalContext | None = None) → Any¶

Invoke a test on a value the same way the compiler does.

This might return a coroutine if the test is running from an environment in async mode and the test supports async execution. It’s your responsibility to await this if needed.

Changed in version 3.0: Tests support @pass_context, etc. decorators. Added the context and eval_ctx parameters.

Added in version 2.7.

code_generator_class¶: alias of CodeGenerator

compile(source: str | Template, name: str | None = None, filename: str | None = None, raw: bool = False, defer_init: bool = False) → str | CodeType¶

Compile a node or template source code. The name parameter is the load name of the template after it was joined using join_path() if necessary, not the filename on the file system. the filename parameter is the estimated filename of the template on the file system. If the template came from a database or memory this can be omitted.

The return value of this method is a python code object. If the raw parameter is True the return value will be a string with python code equivalent to the bytecode returned otherwise. This method is mainly used internally.

defer_init is use internally to aid the module code generator. This causes the generated code to be able to import without the global environment variable to be set.

Added in version 2.4: defer_init parameter added.

compile_expression(source: str, undefined_to_none: bool = True) → TemplateExpression¶

A handy helper method that returns a callable that accepts keyword arguments that appear as variables in the expression. If called it returns the result of the expression.

This is useful if applications want to use the same rules as Jinja in template “configuration files” or similar situations.

Example usage:

>>> env = Environment()
>>> expr = env.compile_expression('foo == 42')
>>> expr(foo=23)
False
>>> expr(foo=42)
True

Per default the return value is converted to None if the expression returns an undefined value. This can be changed by setting undefined_to_none to False.

>>> env.compile_expression('var')() is None
True
>>> env.compile_expression('var', undefined_to_none=False)()
Undefined

Added in version 2.1.

compile_templates(target: str | PathLike[str], extensions: Collection[str] | None = None, filter_func: Callable[[str], bool] | None = None, zip: str | None = 'deflated', log_function: Callable[[str], None] | None = None, ignore_errors: bool = True) → None¶

Finds all the templates the loader can find, compiles them and stores them in target. If zip is None, instead of in a zipfile, the templates will be stored in a directory. By default a deflate zip algorithm is used. To switch to the stored algorithm, zip can be set to 'stored'.

extensions and filter_func are passed to list_templates(). Each template returned will be compiled to the target folder or zipfile.

By default template compilation errors are ignored. In case a log function is provided, errors are logged. If you want template syntax errors to abort the compilation you can set ignore_errors to False and you will get an exception on syntax errors.

Added in version 2.4.

concat(iterable, /)¶

Concatenate any number of strings.

The string whose method is called is inserted in between each given string. The result is returned as a new string.

Example: ‘.’.join([‘ab’, ‘pq’, ‘rs’]) -> ‘ab.pq.rs’

context_class¶: alias of Context

extend(**attributes: Any) → None¶: Add the items to the instance of the environment if they do not exist yet. This is used by extensions to register callbacks and configuration values without breaking inheritance.

from_string(source: str | Template, globals: MutableMapping[str, Any] | None = None, template_class: Type[Template] | None = None) → Template¶

Load a template from a source string without using loader.

Parameters:

source – Jinja source to compile into a template.
globals – Extend the environment globals with these extra variables available for all renders of this template. If the template has already been loaded and cached, its globals are updated with any new items.
template_class – Return an instance of this Template class.

get_or_select_template(template_name_or_list: str | Template | List[str | Template], parent: str | None = None, globals: MutableMapping[str, Any] | None = None) → Template¶: Use select_template() if an iterable of template names is given, or get_template() if one name is given.

Added in version 2.3.

get_template(name: str | Template, parent: str | None = None, globals: MutableMapping[str, Any] | None = None) → Template¶

Load a template by name with loader and return a Template. If the template does not exist a TemplateNotFound exception is raised.

Parameters:

name – Name of the template to load. When loading templates from the filesystem, “/” is used as the path separator, even on Windows.
parent – The name of the parent template importing this template. join_path() can be used to implement name transformations with this.
globals – Extend the environment globals with these extra variables available for all renders of this template. If the template has already been loaded and cached, its globals are updated with any new items.

Changed in version 3.0: If a template is loaded from cache, globals will update the template’s globals instead of ignoring the new values.

Changed in version 2.4: If name is a Template object it is returned unchanged.

getattr(obj: Any, attribute: str) → Any¶: Get an item or attribute of an object but prefer the attribute. Unlike getitem() the attribute must be a string.

getitem(obj: Any, argument: str | Any) → Any | Undefined¶: Get an item or attribute of an object but prefer the item.

handle_exception(source: str | None = None) → te.NoReturn¶: Exception handling helper. This is used internally to either raise rewritten exceptions or return a rendered traceback for the template.

iter_extensions() → Iterator[Extension]¶: Iterates over the extensions by priority.

join_path(template: str, parent: str) → str¶

Join a template with the parent. By default all the lookups are relative to the loader root so this method returns the template parameter unchanged, but if the paths should be relative to the parent template, this function can be used to calculate the real template name.

Subclasses may override this method and implement template path joining here.

lex(source: str, name: str | None = None, filename: str | None = None) → Iterator[Tuple[int, str, str]]¶

Lex the given sourcecode and return a generator that yields tokens as tuples in the form (lineno, token_type, value). This can be useful for extension development and debugging templates.

This does not perform preprocessing. If you want the preprocessing of the extensions to be applied you have to filter source through the preprocess() method.

property lexer: Lexer¶: The lexer for this environment.

linked_to: Environment | None = None¶: the environment this environment is linked to if it is an overlay

list_templates(extensions: Collection[str] | None = None, filter_func: Callable[[str], bool] | None = None) → List[str]¶

Returns a list of templates for this environment. This requires that the loader supports the loader’s list_templates() method.

If there are other files in the template folder besides the actual templates, the returned list can be filtered. There are two ways: either extensions is set to a list of file extensions for templates, or a filter_func can be provided which is a callable that is passed a template name and should return True if it should end up in the result list.

If the loader does not support that, a TypeError is raised.

Added in version 2.4.

make_globals(d: MutableMapping[str, Any] | None) → MutableMapping[str, Any]¶

Make the globals map for a template. Any given template globals overlay the environment globals.

Returns a collections.ChainMap. This allows any changes to a template’s globals to only affect that template, while changes to the environment’s globals are still reflected. However, avoid modifying any globals after a template is loaded.

Parameters:: d – Dict of template-specific globals.

Changed in version 3.0: Use collections.ChainMap to always prevent mutating environment globals.

overlay(block_start_string: str = missing, block_end_string: str = missing, variable_start_string: str = missing, variable_end_string: str = missing, comment_start_string: str = missing, comment_end_string: str = missing, line_statement_prefix: str | None = missing, line_comment_prefix: str | None = missing, trim_blocks: bool = missing, lstrip_blocks: bool = missing, newline_sequence: te.Literal['\n', '\r\n', '\r'] = missing, keep_trailing_newline: bool = missing, extensions: Sequence[str | Type[Extension]] = missing, optimized: bool = missing, undefined: Type[Undefined] = missing, finalize: Callable[[...], Any] | None = missing, autoescape: bool | Callable[[str | None], bool] = missing, loader: BaseLoader | None = missing, cache_size: int = missing, auto_reload: bool = missing, bytecode_cache: BytecodeCache | None = missing, enable_async: bool = missing) → te.Self¶

Create a new overlay environment that shares all the data with the current environment except for cache and the overridden attributes. Extensions cannot be removed for an overlayed environment. An overlayed environment automatically gets all the extensions of the environment it is linked to plus optional extra extensions.

Creating overlays should happen after the initial environment was set up completely. Not all attributes are truly linked, some are just copied over so modifications on the original environment may not shine through.

Changed in version 3.1.5: enable_async is applied correctly.

Changed in version 3.1.2: Added the newline_sequence, keep_trailing_newline, and enable_async parameters to match __init__.

overlayed = False¶: True if the environment is just an overlay

parse(source: str, name: str | None = None, filename: str | None = None) → Template¶

Parse the sourcecode and return the abstract syntax tree. This tree of nodes is used by the compiler to convert the template into executable source- or bytecode. This is useful for debugging or to extract information from templates.

If you are developing Jinja extensions this gives you a good overview of the node tree generated.

preprocess(source: str, name: str | None = None, filename: str | None = None) → str¶: Preprocesses the source with all extensions. This is automatically called for all parsing and compiling methods but not for lex() because there you usually only want the actual source tokenized.

sandboxed = False¶: if this environment is sandboxed. Modifying this variable won’t make the environment sandboxed though. For a real sandboxed environment have a look at jinja2.sandbox. This flag alone controls the code generation by the compiler.

select_template(names: Iterable[str | Template], parent: str | None = None, globals: MutableMapping[str, Any] | None = None) → Template¶

Like get_template(), but tries loading multiple names. If none of the names can be loaded a TemplatesNotFound exception is raised.

Parameters:

names – List of template names to try loading in order.
parent – The name of the parent template importing this template. join_path() can be used to implement name transformations with this.
globals – Extend the environment globals with these extra variables available for all renders of this template. If the template has already been loaded and cached, its globals are updated with any new items.

Changed in version 3.0: If a template is loaded from cache, globals will update the template’s globals instead of ignoring the new values.

Changed in version 2.11: If names is Undefined, an UndefinedError is raised instead. If no templates were found and names contains Undefined, the message is more helpful.

Changed in version 2.4: If names contains a Template object it is returned unchanged.

Added in version 2.3.

shared = False¶: shared environments have this set to True. A shared environment must not be modified

template_class¶: alias of Template

class cli.create.role.FileSystemLoader(searchpath: str | PathLike[str] | Sequence[str | PathLike[str]], encoding: str = 'utf-8', followlinks: bool = False)¶

Bases: BaseLoader

Load templates from a directory in the file system.

The path can be relative or absolute. Relative paths are relative to the current working directory.

loader = FileSystemLoader("templates")

A list of paths can be given. The directories will be searched in order, stopping at the first matching template.

loader = FileSystemLoader(["/override/templates", "/default/templates"])

Parameters:

searchpath – A path, or list of paths, to the directory that contains the templates.
encoding – Use this encoding to read the text from template files.
followlinks – Follow symbolic links in the path.

Changed in version 2.8: Added the followlinks parameter.

get_source(environment: Environment, template: str) → Tuple[str, str, Callable[[], bool]]¶

Get the template source, filename and reload helper for a template. It’s passed the environment and template name and has to return a tuple in the form (source, filename, uptodate) or raise a TemplateNotFound error if it can’t locate the template.

The source part of the returned tuple must be the source of the template as a string. The filename should be the name of the file on the filesystem if it was loaded from there, otherwise None. The filename is used by Python for the tracebacks if no loader extension is used.

The last item in the tuple is the uptodate function. If auto reloading is enabled it’s always called to check if the template changed. No arguments are passed so the function must store the old state somewhere (for example in a closure). If it returns False the template will be reloaded.

list_templates() → List[str]¶: Iterates over all templates. If the loader does not support that it should raise a TypeError which is the default behavior.

class cli.create.role.YAML(*, typ: List[str] | str | None = None, pure: Any = False, output: Any = None, plug_ins: Any = None)¶

Bases: object

Xdump_all(documents: Any, stream: Any, *, transform: Any = None) → Any¶: Serialize a sequence of Python objects into a YAML stream.

property block_seq_indent: Any¶

compact(seq_seq: Any = None, seq_map: Any = None) → None¶

compose(stream: Path | StreamTextType) → Any¶: Parse the first YAML document in a stream and produce the corresponding representation tree.

compose_all(stream: Path | StreamTextType) → Any¶: Parse all YAML documents in a stream and produce corresponding representation trees.

property composer: Any¶

property constructor: Any¶

dump(data: Path | StreamType, stream: Any = None, *, transform: Any = None) → Any¶

dump_all(documents: Any, stream: Path | StreamType, *, transform: Any = None) → Any¶

emit(events: Any, stream: Any) → None¶: Emit YAML parsing events into a stream. If stream is None, return the produced string instead.

property emitter: Any¶

get_constructor_parser(stream: StreamTextType) → Any¶: the old cyaml needs special setup, and therefore the stream

get_serializer_representer_emitter(stream: StreamType, tlca: Any) → Any¶

property indent: Any¶

load(stream: Path | StreamTextType) → Any¶: at this point you either have the non-pure Parser (which has its own reader and scanner) or you have the pure Parser. If the pure Parser is set, then set the Reader and Scanner, if not already set. If either the Scanner or Reader are set, you cannot use the non-pure Parser,

so reset it to the pure parser and set the Reader resp. Scanner if necessary

load_all(stream: Path | StreamTextType) → Any¶

map(**kw: Any) → Any¶

official_plug_ins() → Any¶: search for list of subdirs that are plug-ins, if __file__ is not available, e.g. single file installers that are not properly emulating a file-system (issue 324) no plug-ins will be found. If any are packaged, you know which file that are and you can explicitly provide it during instantiation:

yaml = ruamel.yaml.YAML(plug_ins=[‘ruamel/yaml/jinja2/__plug_in__’])

parse(stream: StreamTextType) → Any¶: Parse a YAML stream and produce parsing events.

property parser: Any¶

property reader: Any¶

register_class(cls: Any) → Any¶: register a class for dumping/loading - if it has attribute yaml_tag use that to register, else use class name - if it has methods to_yaml/from_yaml use those to dump/load else dump attributes

as mapping

property representer: Any¶

property resolver: Any¶

scan(stream: StreamTextType) → Any¶: Scan a YAML stream and produce scanning tokens.

property scanner: Any¶

seq(*args: Any) → Any¶

serialize(node: Any, stream: StreamType | None) → Any¶: Serialize a representation tree into a YAML stream. If stream is None, return the produced string instead.

serialize_all(nodes: Any, stream: StreamType | None) → Any¶: Serialize a sequence of representation trees into a YAML stream. If stream is None, return the produced string instead.

property serializer: Any¶

property tags: Any¶

property version: Tuple[int, int] | None¶

cli.create.role.dump_yaml_with_comments(data, path)¶

cli.create.role.get_entity_name(role_name)¶: Get the entity name from a role name by removing the longest matching category path from categories.yml.

cli.create.role.get_next_network(networks_dict, prefixlen)¶: Select the next contiguous subnet, based on the highest existing subnet + one network offset.

cli.create.role.get_next_port(ports_dict, category)¶: Assign the next port by taking the max existing plus one.

cli.create.role.load_yaml_with_comments(path)¶

cli.create.role.main()¶

cli.create.role.prompt_conflict(dst_file)¶

cli.create.role.render_templates(src_dir, dst_dir, context)¶

cli.create.role.select_autoescape(enabled_extensions: Collection[str] = ('html', 'htm', 'xml'), disabled_extensions: Collection[str] = (), default_for_string: bool = True, default: bool = False) → Callable[[str | None], bool]¶

Intelligently sets the initial value of autoescaping based on the filename of the template. This is the recommended way to configure autoescaping if you do not want to write a custom function yourself.

If you want to enable it for all templates created from strings or for all templates with .html and .xml extensions:

from jinja2 import Environment, select_autoescape
env = Environment(autoescape=select_autoescape(
    enabled_extensions=('html', 'xml'),
    default_for_string=True,
))

Example configuration to turn it on at all times except if the template ends with .txt:

from jinja2 import Environment, select_autoescape
env = Environment(autoescape=select_autoescape(
    disabled_extensions=('txt',),
    default_for_string=True,
    default=True,
))

The enabled_extensions is an iterable of all the extensions that autoescaping should be enabled for. Likewise disabled_extensions is a list of all templates it should be disabled for. If a template is loaded from a string then the default from default_for_string is used. If nothing matches then the initial value of autoescaping is set to the value of default.

For security reasons this function operates case insensitive.

Added in version 2.9.