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

Handler meta-data.

interface

alias of cement.core.output.IOutput

overridable = True

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

_setup(app_obj)

The _setup function is called during application initialization and must setup the handler object making it ready for the framework or the application to make further calls to it.

Parameters:app_obj – The application object.
Returns:None
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.