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

Handler meta-data.

json_module = 'json'

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

_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
_setup(app)

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

Handler meta-data

interface

alias of cement.core.output.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.

_setup(app)

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