What's New!

Overview of notable features and major changes in the latest release.

Notable Features and Changes

Better Documentation

A lot of time and effort has gone into revamping the developer documentation, which includes:

• Separation of Developer Guide (this) and API Reference

• Complete framework overview and beginner tutorial to get started building your first application

• List of terminology used throughout the framework and documentation

• Thorough guide of all builtin extensions

Simplified API Naming Conventions and Usage

The naming conventions and library paths in Cement 2 were laborious to type and remember. Now all modules/methods/etc are importable from cement namespace directly, and the naming is simplified (ex: CementApp is now App, CementHandler is now Handler, etc).

from cement import App, Controller, ex

class Base(Controller):
    class Meta:
        label = 'base'

    @ex(help='this is a command')
    def cmd1(self):
        print('Inside Base.cmd1()')

class MyApp(App):
    class Meta:
        label = 'myapp'
        handlers = [Base]

Developer Tools CLI

The Cement Developer Tools allow developers to quickly generate projects, plugins, extensions, and scripts:

$ cement generate project ./myapp
INFO: Generating cement project in ./myapp/

$ cement generate plugin ./myapp/plugins/
INFO: Generating cement plugin in ./myapp/plugins/

$ cement generate extension ./myapp/ext/
INFO: Generating cement extension in ./myapp/ext/

$ cement generate script .
INFO: Generating cement script in .

Clearer Interface Definition and Implementation

In Cement 2, the design of the interface and handler system was not easy to follow for new developers to the framework. It was also loosely modeled after ZopeInterface, and that may have lead to some odd naming conventions (IMeta, IMyInterface, etc), and an implementation that just felt weird.

Interfaces are now defined using the standard library's Abstract Base Class module per the request of the community, moving the framework away from oddities and more toward common Python standards.

Docker / Docker Compose Support

Cement now includes a fully functioning docker setup out-of-the-box for local development of the framework that includes all dependencies, and dependency services like Redis, Memcached, etc.

Getting up and running is as simple as running the following:

$ make dev

|> cement <| src #

This drops you into a shell within a docker container, and environment so that everything required to dev, and test is ready to roll:

|> cement <| src # make test

|> cement <| src # make docs

See the Makefile for more common development tasks (for framework development).

Environment Variable Overrides

Cement now supports the ability to override all config object settings via their associated environment variables. For example:

myapp.py

from cement import App, init_defaults

CONFIG = init_defaults('myapp')
CONFIG['myapp']['foo'] = 'bar'

class MyApp(App):
    class Meta:
        label = 'myapp'
        config_defaults = CONFIG

with MyApp() as app:
    app.run()
    foo = app.config.get('myapp', 'foo')
    print('Foo => %s' % foo)

cli

$ python myapp.py
Foo => bar

$ export MYAPP_FOO='not-bar'

$ python myapp.py
Foo => not-bar

Environment variables are logically mapped to configuration settings based on their config keys and are prefixed with MYAPP_ (based on the label of the app). So:

• config['myapp']['foo'] => $MYAPP_FOO

• config['some_section']['foo'] => $MYAPP_SOME_SECTION_FOO

New Interfaces

Interface	Description
Template	Rendering of template data (content, files, etc). Existing output handler extensions were also updated to include an associated template handler (MustacheTemplateHandler, Jinja2TemplateHandler, etc).

New Extensions

Extension	Description
Print	Used primarily in development as a replacement for standard print(), allowing the developer to honor framework features like pre_render and post_render hooks.
Scrub	Adds the ability to easily obfuscate sensitive data from rendered output (think IP addresses, credit card numbers, etc)
Generate	Adds the ability for application developers to add a generate controller to their application, and include any number of source templates to generate from. Think myapp generate plugin for third party developers to create plugins for your application from a fully-functional working template.