# `cement.ext.ext_json`

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

## Requirements

> - No external dependencies.

## Configuration

This extension does not support any configuration settings.

### Usage

myapp.conf

    {
        "myapp": {
            "foo": "bar"
        }
    }

myapp.py

    from cement.core.foundation import CementApp

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

            # you probably don't want this to be json by default.. but you can
            # output_handler = 'json'

    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 `json`, but rather another type of output handler that display 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 json` will override the default output handler and set it to `JsonOutputHandler`.

See `CementApp.Meta.handler_override_options`.

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

## What if I Want To Use UltraJson or Something Else?

It is possible to override the backend `json` library module to use, for example if you wanted to use UltraJson (`ujson`) or another drop-in replacement library. The recommended solution would be to override the `JsonOutputHandler` with you’re own sub-classed version, and modify the `json_module` meta-data option.

    from cement.ext.ext_json import JsonOutputHandler

    class MyJsonHandler(JsonOutputHandler):
        class Meta:
            json_module = 'ujson'

    # then, the class must be replaced via a 'post_setup' hook

    def override_json(app):
        app.handler.register(MyJsonHandler, force=True)

    app.hook.register('post_setup', override_json)

class `cement.ext.ext_json.``JsonConfigHandler`(*args, **kw)

  Bases: `cement.ext.ext_configparser.ConfigParserConfigHandler`

  This class implements the IConfig interface, and provides the same functionality of ConfigParserConfigHandler but with JSON configuration files.

  class `Meta`

    Bases: `object`

    Handler meta-data.

    `json_module` = 'json'

      Backend JSON library module to use (json, ujson).

  `JsonConfigHandler.``_parse_file`(file_path)

    Parse JSON 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 JSON configuration file.
    Returns: | boolean

class `cement.ext.ext_json.``JsonOutputHandler`(*args, **kw)

  Bases: `cement.core.output.CementOutputHandler`

  This class implements the IOutput interface. It provides JSON output from a data dictionary using the json module of the standard library. 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 JSON). 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`

      The interface this class implements.

      alias of `IOutput`

    `json_module` = 'json'

      Backend JSON library module to use (json, ujson)

    `label` = 'json'

      The string identifier of this handler.

    `overridable` = True

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

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

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

    Parameters:

    - data_dict – The data dictionary to render.
    - template – This option is completely ignored.

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

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

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

  Parameters: | app – The application object.

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

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

  Parameters: | app – The application object.

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

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

  Parameters: | app – The application object.