Cogeno API¶

cogeno is a Python module that provides access to the public functions of the class: CodeGenerator and the sub-classes of it. See Code generation functions for a description of all cogeno module’s functions.

The interfaces listed hereafter are the internal interfaces of Cogeno. The Cogeno CodeGenerator is made of a set of Mixin classes that bundle specific generator functionality. The CodeGenerator stores it´s states in Context class objects.

CodeGenerator
Context

`CodeGenerator`¶

cogeno.generator.CodeGenerator : public cogeno.context.ContextMixin , public cogeno.options.OptionsMixin , public cogeno.lock.LockMixin , public cogeno.inlinegen.InlineGenMixin , public cogeno.pygen.PyGenMixin , public cogeno.jinja2gen.Jinja2GenMixin , public cogeno.paths.PathsMixin , public cogeno.stdmodules.StdModulesMixin , public cogeno.include.IncludeMixin , public cogeno.log.LogMixin , public cogeno.error.ErrorMixin , public cogeno.output.OutputMixin , public cogeno.importmodule.ImportMixin , public cogeno.redirectable.RedirectableMixin

Public Functions

__init__(self)¶

cogeno_state(self)¶: numeric cogeno state id

Public Static Attributes

cogeno_module = None¶

cogeno_module_states = []¶

The CodeGenerator class includes (sub-classes) several mixin classes:

`ContextMixin`¶

cogeno.context.ContextMixin : public object

Subclassed by cogeno.generator.CodeGenerator

Public Functions

context(self)¶

Get actual code generation context.

Return: context

context_enter(self, context)¶

Switch to new code generation context.

Parameters

The: new context

context_exit(self)¶

Switch back from code generation context.

Write to output file in case we are leaving the top level context.

Return: the outstring of the context just left

context_out(self, text)¶

Output text to current context.

Parameters

text: Text string

`ErrorMixin`¶

cogeno.error.ErrorMixin : public object

Subclassed by cogeno.generator.CodeGenerator

Public Functions

error(self, msg='Error raised by cogeno generator.', frame_index=0, lineno=0)¶

Raise Error exception.

Extra information is added that maps the python snippet line seen by the Python interpreter to the line of the file that inlines the python snippet.

Parameters

msg: [optional] exception message
frame_index: [optional] Call frame index. The call frame offset of the function calling error(). Zero if directly called in a snippet. Add one for every level of function call.
lineno: [optional] line number within template

`ImportMixin`¶

cogeno.importmodule.ImportMixin : public object

Subclassed by cogeno.generator.CodeGenerator

Public Functions

import_module(self, name)¶

Import a Cogeno module.

Import a module.

Module file is searched in current directory or modules directories.

Parameters

name: Module to import. Specified without any path.

import_extensions(self, extensions_paths, update=False)¶

Import extension modules.

Extension paths are searched for extension modules.

Parameters

extensions_paths: Directory paths for extensions
update: Optional, on true the modules are reloaded if already loaded

import_extensions_from_option(self, update=False)¶

Import extension modules given in extension:paths option.

Extension paths are searched for extension modules. Thes modules are imported. As modules may update the option in itself the import is done recursively.

Parameters

update: Optional, on true the modules are reloaded if already loaded

`IncludeMixin`¶

cogeno.include.IncludeMixin : public object

Subclassed by cogeno.generator.CodeGenerator

Public Functions

out_include(self, include_file)¶

Write the text from include_file to the output.

The include_file is processed by cogeno. Inline code generation in include_file can access the globals defined in the including source file before inclusion. The including source file can access the globals defined in the include_file (after inclusion).

Parameters

include_file: Path of include file, either absolute path or relative to current directory or relative to templates directory (e.g. ‘templates/drivers/simple_tmpl.c’)

guard_include(self)¶: Prevent the current file to be included by cogeno.out_include() when called the next time.

`InlineGenMixin`¶

cogeno.inlinegen.InlineGenMixin : public object: Subclassed by cogeno.generator.CodeGenerator

`Jinja2GenMixin`¶

cogeno.jinja2gen.Jinja2GenMixin : public object

Subclassed by cogeno.generator.CodeGenerator

Public Functions

render(self, template_spec, data=None)¶

Render a Ninja2 template.

Parameters

template_spec:
data:

Jinja2SnippetLoader : public BaseLoader

Public Functions

__init__(self, template_name=None, template_code=None)¶

get_source(self, environment, template)¶

Public Static Attributes

snippet_templates = dict()¶: Pool of known snippets.

`LockMixin`¶

cogeno.lock.LockMixin : public object

Subclassed by cogeno.generator.CodeGenerator

Public Functions

lock_file(self)¶

Lock file used for the current context.

Return: lock file name

lock(self)¶

Get the global cogeno lock.

try:
     with cogeno.lock().acquire(timeout = 10):
         ...
except cogeno.lock_timeout():
    cogeno.error(...)
except:
    raise

Return: Lock object

lock_timeout(self)¶

Lock timeout.

Return: Lock timeout object

`LogMixin`¶

cogeno.log.LogMixin : public object

Subclassed by cogeno.generator.CodeGenerator

Public Functions

log(self, message, message_type=None, end="\, logonly=True)¶

Print message and write to log file.

Parameters

message: Message
message_type: If given will be prepended to the message
end: Character to put at the end of the message. ‘\n’ by default.
logonly: Only write to logfile. True by default.

msg(self, message)¶

Print message to stdout and log with a “message: ” prefix.

See

LogMixin::log()

Parameters

message: Message

warning(self, message)¶

Print message to stdout and log with a “warning: ” prefix.

See

LogMixin::log()

Parameters

message: Message

prout(self, message, end="\)¶

Print message to stdout and log.

See

LogMixin::log()

Parameters

message: Message
end: Character to put at the end of the message. ‘\n’ by default.

prerr(self, message, end="\)¶

Print message to stderr and log with a “error: ” prefix.

See

LogMixin::log()

Parameters

message: Message
end: Character to put at the end of the message. ‘\n’ by default.

`OptionsMixin`¶

cogeno.options.OptionsMixin : public object

Subclassed by cogeno.generator.CodeGenerator

Public Functions

option(self, name)¶

Get option of actual context.

Return

option value

Parameters

name: Name of option

options_add_argument(self, args, kwargs)¶

Add option arguments to option parser of actual context.

Cogeno modules may add arguments to the cogeno option parser. The argument variables given to cogeno are rescanned after new option arguments are provided.

def mymodule(cogeno):
    if not hasattr(cogeno, '_mymodule'):
        cogeno._mymodule = None

        cogeno.options_add_argument('-m', '--mymodule', metavar='FILE',
            dest='mymodule_file', action='store',
            type=lambda x: cogeno.option_is_valid_file(x),
            help='Load mymodule data from FILE.')

   if getattr(cogeno, '_mymodule') is not None:
       return cogeno._mymodule

   if cogeno.option('mymodule_file'):
       mymodule_file = cogeno.option('mymodule_file')
   else:
       cogeno.error(..., 2)

   ...
   cogeno._mymodule = ...

option_is_valid_file(self, filepath)¶

option_is_valid_directory(self, directorypath)¶

options_argv_append(self, args)¶

`OutputMixin`¶

cogeno.output.OutputMixin : public object

Subclassed by cogeno.generator.CodeGenerator

Public Functions

out(self, args)¶

Write text to the output.

The string arguments are concenated. The filters are then applied to the lines of the concenated string. The resulting string is written to the output.

OutputFilterDedent and OutputFilterTrimBlankLines make it easier to use multi-line strings, and they are only are useful for multi-line strings:

cogeno.out("""
   These are lines I
   want to write into my source file.
""", cogeno.OutputFilterDedent(), cogeno.OutputFilterTrimBlankLines())

Return

output string

Parameters

*args: Variable length argument list of strings and output filters.

outl(self, args)¶

Write text to the output with newline appended.

See

OutputMixin::out(self, *args)

Return

output string

Parameters

*args: Variable length argument list of strings and output filters.

out_insert(self, insert_file, args)¶

Insert the text from the file into the output.

See

OutputMixin::out(self, *args)

Return

output string

Parameters

insert_file: Path of file, either absolute path or relative to current directory or relative to templates directory.
*args: Variable length argument list of strings and output filters.

class cogeno.OutputFilter¶

Subclassed by cogeno.output.OutputMixin.OutputFilterDedent, cogeno.output.OutputMixin.OutputFilterLineNumbers, cogeno.output.OutputMixin.OutputFilterReplace, cogeno.output.OutputMixin.OutputFilterReSub, cogeno.output.OutputMixin.OutputFilterStartAt, cogeno.output.OutputMixin.OutputFilterStopAt, cogeno.output.OutputMixin.OutputFilterTemplateSubstitude, cogeno.output.OutputMixin.OutputFilterTrimBlankLines

Public Functions

__call__(self, line, lineno=None, lines=None)¶

Apply filter.

Return

line with filter applied. Maybe None in case the line is deleted

Parameters

line: line to apply filter to
lineno: line number - starts at 1
lines: all lines

parselinenos(self, spec, total)¶

Parse a line number spec.

Return

A list of wanted line numbers (line numbers start at 1).

Parameters

spec: Line number spec (such as “1,2,4-6”)
total: Total number of lines

OutputFilterDedent : public cogeno.output.OutputMixin.OutputFilter

Remove common initial white space from the lines.

Parameters

new_indent: Optional new indentation (after dedent)

Public Functions

__init__(self, new_indent='')¶

__call__(self, line, lineno=None, lines=None)¶

Apply filter.

Return

line with filter applied. Maybe None in case the line is deleted

Parameters

line: line to apply filter to
lineno: line number - starts at 1
lines: all lines

Public Members

white_prefix¶

new_indent¶

OutputFilterLineNumbers : public cogeno.output.OutputMixin.OutputFilter

Filter lines by line numbers.

Filter lines that are given by line sumber specifications (such as “1,2,4-6”).

Parameters

args: list of arguments denoting line number specifications

Public Functions

__init__(self, args)¶

__call__(self, line, lineno=None, lines=None)¶

Apply filter.

Return

line with filter applied. Maybe None in case the line is deleted

Parameters

line: line to apply filter to
lineno: line number - starts at 1
lines: all lines

Public Members

args¶

line_numbers¶

OutputFilterReplace : public cogeno.output.OutputMixin.OutputFilter

Replace substring.

Parameters

old: old substring to replace
new: new substring which will replace the old substring. if new is None and the resulting line is empty it is deleted.
count: (optional) the number of times to replace the old substring with the new substring

Public Functions

__init__(self, old, new, count=None)¶

__call__(self, line, lineno=None, lines=None)¶

Public Members

old¶

new¶

count¶

OutputFilterReSub : public cogeno.output.OutputMixin.OutputFilter

Substitude regular expression pattern.

Replace the leftmost non-overlapping occurrences of pattern in each line by the replacement repl.

Parameters

pattern: Pattern for replacement. Pattern is a string that will be compiled to a pattern object.
repl: Replacement. Repl can be a string or a function. If repl is a function, it is called for every non-overlapping occurrence of pattern.
count: (optional) maximum number of pattern occurrences to be replaced

Public Functions

__init__(self, pattern, repl, count=0, flags=0)¶

__call__(self, line, lineno=None, lines=None)¶

Public Members

pattern¶

repl¶

count¶

flags¶

OutputFilterStartAt : public cogeno.output.OutputMixin.OutputFilter

Start output at pattern.

Parameters

start_at: Start pattern

Public Functions

__init__(self, start_at)¶

__call__(self, line, lineno=None, lines=None)¶

Public Members

start_at¶

started¶

OutputFilterStopAt : public cogeno.output.OutputMixin.OutputFilter

Stop output at pattern.

Parameters

stop_at: Stop pattern

Public Functions

__init__(self, stop_at)¶

__call__(self, line, lineno=None, lines=None)¶

Public Members

stop_at¶

stopped¶

OutputFilterTemplateSubstitude : public cogeno.output.OutputMixin.OutputFilter

Substitude template placeholders.

Template placeholder substitution supports $-based substitutions, using the following rules:

$$ is an escape; it is replaced with a single $.
$identifier names a substitution placeholder matching a mapping key of “identifier”. By default, “identifier” is restricted to any case-insensitive ASCII alphanumeric string (including underscores) that starts with an underscore or ASCII letter. The first non-identifier character after the $ character terminates this placeholder specification.
${identifier} is equivalent to $identifier. It is required when valid identifier characters follow the placeholder but are not part of the placeholder, such as “${noun}ification”.

At least up to 4 nesting levels of placeholders are substituded, e.g.:

${placeholder_level1} : mapping = ‘placeholder_level1’ : ‘holder’
${place${placeholder_level1}_level2} : mapping = ‘placeholder_level2’ : ‘placeholder’
${${placeholder_level2}_level3} : mapping = ‘placeholder_level3’ : ‘placeholder_level’
${${placeholder_level3}4} : mapping = ‘placeholder_level4’ : ‘success’

If more than one placeholder patterns are provided the substitution is done for each pattern sequencing through the patterns list.

Parameters

mapping: Mapping is any dictionary-like object with keys that match the template placeholders.
patterns: (optional) Patterns is a list of regular expressions describing the pattern for non-braced placeholders.

Public Functions

__init__(self, mapping, patterns=['[_a-zA-Z][_a-zA-Z0-9] *'])¶

__call__(self, line, lineno=None, lines=None)¶

Public Members

mapping¶

templates¶

Public Static Attributes

templates_classes = {}¶

OutputFilterTrimBlankLines : public cogeno.output.OutputMixin.OutputFilter

Remove initial and trailing blank lines from the block of lines.

Public Functions

__init__(self)¶

__call__(self, line, lineno=None, lines=None)¶

Apply filter.

Parameters

line: line to apply filter to
lineno: line number - starts at 1
lines: all lines return line with filter applied. Maybe None in case the line is deleted

Public Members

trim_inital_lines¶

trim_trailing_lines_start¶

`PathsMixin`¶

cogeno.paths.PathsMixin : public object

Subclassed by cogeno.generator.CodeGenerator

Public Functions

modules_paths_append(self, path)¶

modules_paths(self)¶

templates_paths_append(self, path)¶

templates_paths(self)¶

template_path(self)¶

Public Static Functions

path_walk(top, topdown=False, followlinks=False)¶

Walk directory tree.

For each directory in the tree rooted at directory top (including top itself), it yields a 3-tuple (dirpath, dirnames, filenames):

dirpath: the path to the directory.
dirnames: list of the paths of the subdirectories in dirpath
filenames: list of the paths of the non-directory files in dirpath

See Python docs for os.walk, exact same behavior but it yields Path() instances instead. From: http://ominian.com/2016/03/29/os-walk-for-pathlib-path/

Return

yields a 3-tuple (dirpath, dirpathes, filepathes)

Parameters

top: root of directory tree
topdown: if topdown is True, the triple for a directory is generated before the triples for any of its subdirectories (directories are generated top-down). If topdown is False, the triple for a directory is generated after the triples for all of its subdirectories (directories are generated bottom-up).
followlinks:

rmtree(top)¶

Delete an entire directory tree.

Parameters

top: root of directory tree

find_template_files(top, marker, suffix='.c')¶

Find template files.

Return

List of template file pathes

Parameters

marker: Marker as b’my-marker’
suffix:

cogeno_path()¶

find_file_path(file_name, paths)¶

`PyGenMixin`¶

cogeno.pygen.PyGenMixin : public object: Subclassed by cogeno.generator.CodeGenerator

`RedirectableMixin`¶

cogeno.redirectable.RedirectableMixin : public object

Subclassed by cogeno.generator.CodeGenerator, cogeno.redirectable.Redirectable

Public Functions

set_standard_streams(self, stdout=None, stderr=None)¶

Redirect status and error reporting.

Assign new files for standard out and/or standard error.

Parameters

stdout:
stderr:

`StdModulesMixin`¶

cogeno.stdmodules.StdModulesMixin : public object

Subclassed by cogeno.generator.CodeGenerator

Public Functions

edts(self, force_extract=False)¶

Get the extended device tree database.

Return: Extended device tree database.

cmake(self)¶

Get the cmake variables database.

Return: CMake variables database.

cmake_variable(self, variable_name, default='<unset>')¶

Get the value of a CMake variable.

If variable_name is not provided to cogeno by CMake the default value is returned.

A typical set of CMake variables that are not available in the CMakeCache.txt file and have to be provided as defines to cogeno if needed:

“PROJECT_NAME”
”PROJECT_SOURCE_DIR”
”PROJECT_BINARY_DIR”
”CMAKE_SOURCE_DIR”
”CMAKE_BINARY_DIR”
”CMAKE_CURRENT_SOURCE_DIR”
”CMAKE_CURRENT_BINARY_DIR”
”CMAKE_CURRENT_LIST_DIR”
”CMAKE_FILES_DIRECTORY”
”CMAKE_PROJECT_NAME”
”CMAKE_SYSTEM”
”CMAKE_SYSTEM_NAME”
”CMAKE_SYSTEM_VERSION”
”CMAKE_SYSTEM_PROCESSOR”
”CMAKE_C_COMPILER”
”CMAKE_CXX_COMPILER”
”CMAKE_COMPILER_IS_GNUCC”
”CMAKE_COMPILER_IS_GNUCXX”

Return

value

Parameters

variable_name: Name of the CMake variable
default: Default value

cmake_cache_variable(self, variable_name, default='<unset>')¶

Get the value of a CMake variable from CMakeCache.txt.

If variable_name is not given in CMakeCache.txt the default value is returned.

Return

value

Parameters

variable_name: Name of the CMake variable
default: Default value

configs(self, force_extract=False)¶

Get the configuration variables database.

Return: Configuration variables database.

config_properties(self)¶

Get all config properties.

The property names are the ones config file.

Return: A dictionary of config properties.

config_property(self, property_name, default='<unset>')¶

Get the value of a configuration property fromthe config file.

If property_name is not given in .config the default value is returned.

Return

property value

Parameters

property_name: Name of the property
default: Property value to return per default.

`Context`¶

cogeno.context.Context : public object

Context for code generation.

Public Functions

__init__(self, generator, parent_context=None, generation_globals=None, options=None, eval_begin=None, eval_end=None, eval_adjust=None, delete_code=None, template_file=None, template=None, template_source_type=None, script_type=None, template_tabsize=None, templates_paths=None, modules_paths=None, jinja2_environment=None, output_file=None, log_file=None, lock_file=None)¶: Initialise context object.

__str__(self)¶

__repr__(self)¶

parent(self)¶

generation_globals(self)¶

script_is_inline(self)¶

script_is_python(self)¶

script_is_jinja2(self)¶

script_type(self)¶

template_is_snippet(self)¶

Template is a snippet.

Snippets are parts of the template of the parent context.

Return: True in case the template is a snippet, False otherwise.

template_is_file(self)¶

template_is_string(self)¶

options(self)¶: Options.

out(self, line)¶: Add line.

outl(self, line)¶: Add line with newline.