# `cement.ext.ext_yaml`

The Yaml Extension adds the `YamlOutputHandler` to render output in pure Yaml, as well as the `YamlConfigHandler` that allows applications to use Yaml configuration files as a drop-in replacement of the default `cement.ext.ext_configparser.ConfigParserConfigHandler`.

## Requirements

> - pyYaml (`pip install pyYaml`)

## Configuration

This extension does not honor any application configuration settings.

### Usage

myapp.conf

    ---
    myapp:
        foo: bar

myapp.py

    from cement.core.foundation import CementApp

    class MyApp(CementApp):
        class Meta:
            label = 'myapp'
            extensions = ['Yaml']
            config_handler = 'Yaml'

            # you probably don't want to do this.. but you can
            # output_handler = 'Yaml'

    with MyApp() as app:
        app.run()

        # create some data
        data = dict(foo=app.config.get('myapp', 'foo'))

        app.render(data)

In general, you likely would not set `output_handler` to `Yaml`, but rather another type of output handler that displays readable output to the end-user (i.e. Mustache, Genshi, or Tabulate). By default Cement adds the `-o` command line option to allow the end user to override the output handler. For example: passing `-o Yaml` will override the default output handler and set it to `YamlOutputHandler`.

See `CementApp.Meta.handler_override_options`.

    $ python myapp.py -o Yaml
    {foo: bar}

class `cement.ext.ext_yaml.``YamlConfigHandler`(*args, **kw)

  Bases: `cement.ext.ext_configparser.ConfigParserConfigHandler`

  This class implements the IConfig interface, and provides the same functionality of ConfigParserConfigHandler but with Yaml configuration files. See pyYaml for more information on pyYaml.

  Note This extension has an external dependency on pyYaml. You must include pyYaml in your application’s dependencies as Cement explicitly does not include external dependencies for optional extensions.

  `_parse_file`(file_path)

    Parse Yaml configuration file settings from file_path, overwriting existing config settings. If the file does not exist, returns False.

    Parameters: | file_path – The file system path to the Yaml configuration file.
    Returns: | boolean

class `cement.ext.ext_yaml.``YamlOutputHandler`(*args, **kw)

  Bases: `cement.core.output.CementOutputHandler`

  This class implements the IOutput interface. It provides Yaml output from a data dictionary and uses pyYaml to dump it to STDOUT. Please see the developer documentation on Output Handling.

  This handler forces Cement to suppress console output until `app.render` is called (keeping the output pure Yaml). If troubleshooting issues, you will need to pass the `--debug` option in order to unsuppress output and see what’s happening.

  class `Meta`

    Bases: `object`

    Handler meta-data.

    `interface`

      alias of `IOutput`

    `overridable` = True

      Whether or not to include `Yaml` as an available to choice to override the `output_handler` via command line options.

  `YamlOutputHandler.``render`(data_dict, template=None, **kw)

    Take a data dictionary and render it as Yaml output. Note that the template option is received here per the interface, however this handler just ignores it. Additional keyword arguments passed to `yaml.dump()`.

    Parameters:

    - data_dict – The data dictionary to render.
    - template – Ignored in this output handler implementation.

    Returns: | A Yaml encoded string.
    Return type: | `str`

`cement.ext.ext_yaml.``suppress_output_after_render`(app, out_text)

  This is a `post_render` hook that suppresses console output again after rendering, only if the `YamlOutputHandler` is triggered via command line.

  Parameters: | app – The application object.

`cement.ext.ext_yaml.``suppress_output_before_run`(app)

  This is a `post_argument_parsing` hook that suppresses console output if the `YamlOutputHandler` is triggered via command line.

  Parameters: | app – The application object.

`cement.ext.ext_yaml.``unsuppress_output_before_render`(app, data)

  This is a `pre_render` that unsuppresses console output if the `YamlOutputHandler` is triggered via command line so that the Yaml is the only thing in the output.

  Parameters: | app – The application object.