hmd-lib-mickey

Common library for code generation used in hmd-tf-mickey. The library provides basic abstractions around building data contexts, downloading and using remote packages, and rendering Jinja templates. It also provides mechanisms to provide pre/post-hooks to various parts of the generation process.

Basic Usage

There are two core classes required perform code generation, MickeyRunConfiguration and MickeyRun. MickeyRunConfiguration represents the basic configuration of the current code generation run. It contains properties for the context definitions, template paths to render, data contexts to use, etc. The easiest way to build it is passing a simple Mickey transform instance context.

config = MickeyRunConfiguration(
    project_name, # project repository name
    {
        "input": input_content_path,
        "output": output_content_path,
        "cache": cache_path,
    }, # Dirs dictionary containing paths for finding inputs, where to output results, and cache location
    transform_instance_context,
    variables=transform_instance_context.get("variables", {}), # Additional variables to use
    skip_deps=skip_deps, # Flad to download remote packages or not
    hook_scripts=hooks, # Paths to hook scripts
)

The transform_instance_context has the following shape:

{
  "context_definitions": {},
  "template_packages": [],
  "templates": [],
  "contexts": [],
  "hooks": []
}

A list of MickeyPhase instances and a name is passed to MickeyRun. This represents the actual running of the code generator. You can build your own set of phases, but it is probably easier to use the default set PHASES found in hmd_lib_mickey.phases.

from hmd_lib_mickey.types import MickeyRun
from hmd_lib_mickey.phases import PHASES

run = MickeyRun(PHASES, 'run')

The final step is to actually perform the code generation with the generate function.

from hmd_lib_mickey.hmd_lib_mickey import generate

generate(run, config)

Phase Hooks

The base class MickeyPhase has two decorator methods for extension via pre/post hooks. The decorator methods expect a function that takes a MickeyRunConfiguration instance as its only argument and returns either the same instance or a mutated copy.

Example:

from hmd_lib_mickey.phases import BuildEnvironment
from hmd_lib_mickey.types import MickeyRunConfiguration


@BuildEnvironment.post_hook
def add_jinja_filters(config: MickeyRunConfiguration):
    env = config.environment

    # Mutate the Jinja Environment
    # ...

    return config.copy(environment=env)

The above example adds a post-hook to the BuildEnvironment phase to edit the standard Jinja Environment used. You can use it to add filter functions to be used by templates for example. Hooks can included in the code generation run by giving a list of paths to single Python scripts in the MickeyRunConfiguration. Currently, you cannot import relative packages from the scripts because Mickey copies only the script to the cache location. The MickeyRun will handle importing each listed script, which will cause any decorators used to run and register with the appropriate phase.