Metadata-Version: 2.1
Name: hmd-lib-mickey
Version: 0.1.77
Summary: Common library for code generation
Home-page: UNKNOWN
Author: Alex Burgoon
Author-email: alex.burgoon@hmdlabs.io
License: Apache 2.0
Platform: UNKNOWN
Description-Content-Type: text/markdown
Requires-Dist: hmd-lib-remote-deps (~=0.1.6)
Requires-Dist: jinja2 (==3.0.3)
Requires-Dist: markupsafe (==3.0.2)
Requires-Dist: pyyaml (==6.0.1)
Requires-Dist: xmltodict (==0.13.0)

# 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.

```python
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:

```json
{
  "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`.

```python
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.

```python
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:

```python
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.


