Framework Extensions
Cement defines an Extension Interface, as well as the default CementExtensionHandler that implements the interface. Its purpose is to manage loading framework extensions and making them usable by the application. Extensions are similar to Application Plugins, but at the framework level (application agnostic).
Cement often includes multiple handler implementations of an interface that may or may not have additional features or functionality than the interface requires. The documentation below only references usage based on the interface and default handler (not the full capabilities of an implementation).
As of Cement 2.1.3, optional extensions with external dependencies are now being shipped along with mainline sources. This means that although Cement Core continues to maintain a 100% zero dependency policy, Framework Extensions can rely on external deps. It is the responsibility of the application developer to include these dependencies in their application (as the Cement package does not include these dependencies).
API References:
Option | Description |
extension_handler | A handler class that implements the Extension Interface. This can be a string (label of a registered handler), an uninstantiated class, or an instantiated class object. Default: ExtensionHandler |
extensions | A list of additional framework extensions to load. Will be merged together with App.Meta.core_extensions. |
In general, extensions are only loaded and accessed by the framework. That said the extension handler can be used to access information about loaded extensions, as well as manually load extensions if necessary.
Example: Working with Extensions
from cement import App
with App('myapp') as app:
# list loaded extensions
app.ext.list()
# load an extension
app.ext.load_extension('myapp.ext.myextension')
# load a list of extensions
app.ext.load_extensions(['myapp.ext.ext1',
'myapp.ext.ext2'])
The extension system is a mechanism for dynamically loading code to extend the functionality of the framework. In general, this includes the registration of interfaces, handlers, and/or hooks but can include controllers, command-line options, or anything else.
$ cement generate extension /path/to/myapp/ext
This would produce something like the following:
Example: Creating an Extension
myapp/ext/ext_myextension.py
from cement import minimal_logger
LOG = minimal_logger(__name__)
def myextension_pre_run_hook(app):
# do something with app
LOG.debug('Inside myextension_pre_run_hook!')
def load(app):
# do something to extend cement
app.hook.register('pre_run', myextension_pre_run_hook)
Extensions can provide anything from defining interfaces, registering hooks, or even adding command line arguments. The only thing required to make up an extension is the
load() function.You will notice that extensions are essentially the same as application plugins. The difference is found both in when/how the code is loaded, as well as the purpose of that code.
Framework extensions add functionality to the framework for the application to utilize, whereas application plugins extend the functionality of the application itself.
Extensions are loaded when
App.setup() is called on an application. Cement automatically loads all extensions listed under the application's App.Meta.core_extensions and App.Meta.extensions meta options.To load the above example into our application, we just add it to the list of
App.Meta.extensions. Let's assume the extension code lives in myapp/ext/ext_myextension.py:Example: Loading Extensions
from cement import App
class MyApp(App):
class Meta:
label = 'myapp'
extensions = 'myapp.ext.ext_myextension'
Note that Cement provides a shortcut for its own builtin extensions so that you can refer to extensions via their short name (ex:
json instead of cement.ext.ext_json). All other extensions must be referenced by their full dotted Python module name.Some use cases may require that end-users be able to modify what framework extensions are loaded depending on the needs of the application, while most extensions are defined by the developer to support key features.
The following example demonstrates an application loading extensions defined via the
extensions setting under the application's configuration settings.Example: Loading Extensions via Configuration File
cli
myapp.py
from cement import App
with App('myapp') as app:
app.run()
for e in app.extension.list():
print(e)
~/.myapp.conf
[myapp]
exensions = json, yaml, myapp.ext.ext_myextension
$ python myapp.py
cement.ext.ext_dummy
cement.ext.ext_smtp
cement.ext.ext_plugin
cement.ext.ext_configparser
cement.ext.ext_logging
cement.ext.ext_argparse
cement.ext.ext_json
cement.ext.ext_yaml
myapp.ext.ext_myextension
Note that extensions loaded in this way will happen after the config handler is setup. Normally, extensions are loaded just before the configuration files are read. Therefore, some extensions may not be compatible with this method if they attempt to perform any actions before
app.setup() completes (such as in early framework hooks before configuration files are loaded).Last modified 4yr ago