artin/cement
1
0
Fork 0
mirror of https://github.com/datafolklabs/cement.git synced 2026-02-06 15:26:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improving documentation

Browse Source
This commit is contained in:
BJ Dierkes 2012-07-31 17:15:08 -05:00
parent b86f05d55f
commit f2a2bfc617
35 changed files with 489 additions and 401 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
cement/core/arg.py
View File

@ -97,7 +97,10 @@ class CementArgumentHandler(handler.CementBaseHandler):
"""
# pylint: disable=W0232,R0903
class Meta:
"""Handler meta-data options."""
"""
Handler meta-data (can be passed as keyword arguments to the parent
class).
"""
label = None
"""The string identifier of the handler implementation."""

6
cement/core/cache.py
View File

@ -109,7 +109,11 @@ class CementCacheHandler(handler.CementBaseHandler):
"""
class Meta:
"""Handler meta-data."""
"""
Handler meta-data (can be passed as keyword arguments to the parent
class).
"""
label = None
"""String identifier of this handler implementation."""

6
cement/core/config.py
View File

@ -161,6 +161,7 @@ class IConfig(interface.Interface):
"""
Returns whether or not the section exists.
:param section: The section to test for.
:returns: boolean
"""
@ -171,7 +172,10 @@ class CementConfigHandler(handler.CementBaseHandler):
"""
class Meta:
"""Handler meta-data."""
"""
Handler meta-data (can be passed as keyword arguments to the parent
class).
"""
label = None
"""The string identifier of the implementation."""

193
cement/core/controller.py
View File

@ -62,11 +62,16 @@ class IController(interface.Interface):
"""
# pylint: disable=W0232, C0111, R0903
class IMeta:
"""Interface meta-data."""
label = 'controller'
"""The string identifier of the interface."""
validator = controller_validator
"""The interface validator function."""
# Must be provided by the implementation
Meta = interface.Attribute('Handler Meta-data')
Meta = interface.Attribute('Handler meta-data')
def _setup(app_obj):
"""
@ -77,12 +82,8 @@ class IController(interface.Interface):
Must 'setup' the handler object making it ready for the framework
or the application to make further calls to it.
Required Arguments:
app_obj
The application object.
Return: None
:param app_obj: The application object.
:returns: None
"""
@ -96,7 +97,8 @@ class IController(interface.Interface):
on a controller, as it expects the controller to handle parsing
arguments (I.e. self.app.args.parse()).
Return None
:returns: None
"""
class expose(object):
@ -104,16 +106,12 @@ class expose(object):
Used to expose controller functions to be listed as commands, and to
decorate the function with Meta data for the argument parser.
Optional Arguments:
hide
Whether the command should be visible.
help
Help text to display for that command.
aliases
List of aliases to this command.
:param hide: Whether the command should be visible.
:type hide: boolean
:param help: Help text to display for that command.
:type help: str
:param aliases: Aliases to this command.
:type aliases: list
Usage:
@ -150,59 +148,15 @@ class expose(object):
class CementBaseController(handler.CementBaseHandler):
"""
This is an implementation of the IControllerHandler interface, but as a
base class that application controllers need to subclass from.
This is an implementation of the
`IControllerHandler <#cement.core.controller.IController>`_ interface, but
as a base class that application controllers `should` subclass from.
Registering it directly as a handler is useless.
NOTE: This handler *requires* that the applications 'arg_handler' be
NOTE: This handler **requires** that the applications 'arg_handler' be
argparse. If using an alternative argument handler you will need to
write your own controller base class.
Optional / Meta Options:
interface
The interface that this controller implements (IController).
label
The label of the controller. Will be used as the sub-command
name for 'stacked' controllers.
aliases
A list of aliases for the controller. Will be treated like
command/function aliases for non-stacked controllers. For example:
'myapp <controller_label> --help' is the same as
'myapp <controller_alias> --help'.
Default: []
description
The description shown at the top of '--help'.
config_section
A config [section] to merge config_defaults into.
Default: controller.<label>
config_defaults
Configuration defaults (type: dict) that are merged into the
applications config object for the config_section mentioned above.
arguments
Arguments to pass to the argument_handler. The format is a list
of tuples whos items are a ( list, dict ). Meaning:
[ ( ['-f', '--foo'], dict(dest='foo', help='foo option') ), ]
stacked_on
A label of another controller to 'stack' commands/arguments on
top of.
hide
Whether or not to hide the controller entirely.
epilog
The text that is displayed at the bottom when '--help' is passed.
Usage:
.. code-block:: python
@ -216,25 +170,78 @@ class CementBaseController(handler.CementBaseHandler):
config_defaults = dict()
arguments = []
epilog = "This is the text at the bottom of --help."
# ...
class MyStackedController(controller.CementBaseController):
class Meta:
label = 'second_controller'
aliases = ['sec', 'secondary']
stacked_on = 'base'
# ...
"""
class Meta:
"""
Controller meta-data (can be passed as keyword arguments to the parent
class).
"""
interface = IController
label = 'base' # provided in subclass
aliases = [] # aliases for the controller
"""The interface this class implements."""
label = 'base'
"""The string identifier for the controller."""
aliases = []
"""
A list of aliases for the controller. Will be treated like
command/function aliases for non-stacked controllers. For example:
'myapp <controller_label> --help' is the same as
'myapp <controller_alias> --help'.
"""
description = None
config_section = None # defaults to controller.<label>
config_defaults = {} # default config options
arguments = [] # list of tuple (*args, *kwargs)
stacked_on = None # controller name to merge commands/options into
hide = False # whether to hide controller completely
"""The description shown at the top of '--help'. Default: None"""
config_section = None
"""
A config [section] to merge config_defaults into. Cement will default
to controller.<label> if None is set.
"""
config_defaults = {}
"""
Configuration defaults (type: dict) that are merged into the
applications config object for the config_section mentioned above.
"""
arguments = []
"""
Arguments to pass to the argument_handler. The format is a list
of tuples whos items are a ( list, dict ). Meaning:
``[ ( ['-f', '--foo'], dict(dest='foo', help='foo option') ), ]``
This is equivelant to manually adding each argument to the argument
parser:
``parser.add_argument(['-f', '--foo'], help='foo option', dest='foo')``
"""
stacked_on = None
"""
A label of another controller to 'stack' commands/arguments on top of.
"""
hide = False
"""Whether or not to hide the controller entirely."""
epilog = None
"""
The text that is displayed at the bottom when '--help' is passed.
"""
### FIX ME: What is this used for???
ignored = ['visible', 'hidden', 'exposed']
@ -253,6 +260,9 @@ class CementBaseController(handler.CementBaseHandler):
self._arguments = []
def _setup(self, app_obj):
"""
See `IController._setup() <#cement.core.cache.IController._setup>`_.
"""
super(CementBaseController, self)._setup(app_obj)
if self._meta.description is None:
@ -269,7 +279,7 @@ class CementBaseController(handler.CementBaseHandler):
def _parse_args(self):
"""
Parse command line arguments and determine a command to dispatch.
Parses command line arguments and determine a command to dispatch.
"""
# chop off a command argument if it matches an exposed command
@ -325,6 +335,8 @@ class CementBaseController(handler.CementBaseHandler):
This is the default action if no arguments (sub-commands) are passed
at command line.
:raises: NotImplementedError
"""
raise NotImplementedError
@ -340,6 +352,9 @@ class CementBaseController(handler.CementBaseHandler):
def _collect_from_self(self):
"""
Collect arguments from this controller.
:raises: cement.core.exc.CementRuntimeError
"""
# collect our Meta arguments
for _args,_kwargs in self._meta.arguments:
@ -385,10 +400,8 @@ class CementBaseController(handler.CementBaseHandler):
"""
Collect arguments from non-stacked controllers.
Required Arguments:
controller
The controller to collect arguments from.
:param controller: The controller to collect arguments from.
:type controller: Uninstantiated controller class
"""
contr = controller()
@ -411,10 +424,9 @@ class CementBaseController(handler.CementBaseHandler):
"""
Collect arguments from stacked controllers.
Required Arguments:
controller
The controller to collect arguments from.
:param controller: The controller to collect arguments from.
:type controller: Uninstantiated controller class
:raises: cement.core.exc.CementRuntimeError
"""
contr = controller()
@ -452,10 +464,8 @@ class CementBaseController(handler.CementBaseHandler):
self.exposed[label] = func_dicts[label]
def _collect_from_controllers(self):
"""
Collect arguments from all controllers.
"""Collect arguments from all controllers."""
"""
for controller in handler.list('controller'):
contr = controller()
if contr._meta.label == self._meta.label:
@ -474,6 +484,9 @@ class CementBaseController(handler.CementBaseHandler):
"""
Collects all commands and arguments from this controller, and other
availble controllers.
:raises: cement.core.exc.CementRuntimeError
"""
LOG.debug("collecting arguments and commands from '%s' controller" % \
@ -512,10 +525,8 @@ class CementBaseController(handler.CementBaseHandler):
@property
def _usage_text(self):
"""
Returns the usage text displayed when '--help' is passed.
"""Returns the usage text displayed when '--help' is passed."""
"""
if self == self.app._meta.base_controller:
txt = "%s <CMD> -opt1 --opt2=VAL [arg1] [arg2] ..." % \
self.app.args.prog
@ -526,10 +537,8 @@ class CementBaseController(handler.CementBaseHandler):
@property
def _help_text(self):
"""
Returns the help text displayed when '--help' is passed.
"""Returns the help text displayed when '--help' is passed."""
"""
cmd_txt = ''
# hack it up to keep commands in alphabetical order

23
cement/core/exc.py
View File

@ -1,7 +1,12 @@
"""Cement core exceptions module."""
class CementError(Exception):
"""Generic errors."""
"""
Generic errors.
:param msg: The error message.
"""
def __init__(self, msg):
Exception.__init__(self)
self.msg = msg
@ -11,19 +16,33 @@ class CementError(Exception):
class CementConfigError(CementError):
"""Cement configuration related errors."""
pass
class CementRuntimeError(CementError):
"""
General runtime errors. Similar to '500 Internal Server Error' in the
web world.
"""
pass
class CementArgumentError(CementError):
"""Command line argument related errors."""
pass
class CementInterfaceError(CementError):
"""Interface related errors."""
pass
class CementSignalError(CementError):
"""Signal errors."""
"""
Signal errors. For more information regarding signals, reference the
`signal <http://docs.python.org/library/signal.html>`_ library.
:param signum: The signal number.
:param frame: The signal frame.
"""
def __init__(self, signum, frame):
msg = 'Caught signal %s' % signum
super(CementSignalError, self).__init__(msg)

60
cement/core/extension.py
View File

@ -45,8 +45,13 @@ class IExtension(interface.Interface):
# pylint: disable=W0232, C0111, R0903
class IMeta:
"""Interface meta-data."""
label = 'extension'
"""The string identifier of the interface."""
validator = extension_validator
"""The interface validator function."""
# Must be provided by the implementation
Meta = interface.Attribute('Handler Meta-data class')
@ -58,12 +63,8 @@ class IExtension(interface.Interface):
must 'setup' the handler object making it ready for the framework
or the application to make further calls to it.
Required Arguments:
app_obj
The application object.
Returns: n/a
:param app_obj: The application object.
:returns: None
"""
@ -72,10 +73,8 @@ class IExtension(interface.Interface):
Load an extension whose module is 'ext_module'. For example,
'cement.ext.ext_configobj'.
Required Arguments:
ext_module
The name of the extension to load.
:param ext_module: The name of the extension to load.
:type ext_module: str
"""
@ -83,36 +82,42 @@ class IExtension(interface.Interface):
"""
Load all extensions from ext_list.
Required Arguments:
ext_list
A list of extension modules to load. For example,
['cement.ext.ext_configobj', 'cement.ext.ext_logging'].
:param ext_list: A list of extension modules to load. For example:
``['cement.ext.ext_configobj', 'cement.ext.ext_logging']``
:type ext_list: list
"""
class CementExtensionHandler(handler.CementBaseHandler):
loaded_extensions = []
"""A list of loaded extensions."""
class Meta:
"""
Handler meta-data (can be passed as keyword arguments to the parent
class).
"""
interface = IExtension
"""The interface that this class implements."""
label = 'cement'
"""The string identifier of the handler."""
def __init__(self, **kw):
"""
This is an implementation of the IExtentionHandler interface. It handles
loading framework extensions.
This is an implementation of the IExtentionHandler interface. It
handles loading framework extensions.
"""
super(CementExtensionHandler, self).__init__(**kw)
self.app = None
self._loaded_extensions = []
def _setup(self, app_obj):
self.app = app_obj
@property
def loaded_extensions(self):
"""Returns list of loaded extensions."""
return self._loaded_extensions
def load_extension(self, ext_module):
@ -120,11 +125,10 @@ class CementExtensionHandler(handler.CementBaseHandler):
Given an extension module name, load or in other-words 'import' the
extension.
Required Arguments:
ext_module
The extension module name. For example
'cement.ext.ext_logging'.
:param ext_module: The extension module name. For example:
'cement.ext.ext_logging'.
:type ext_module: str
:raises: cement.core.exc.CementRuntimeError
"""
# If its not a full module path then preppend our default path
@ -154,10 +158,8 @@ class CementExtensionHandler(handler.CementBaseHandler):
Given a list of extension modules, iterate over the list and pass
individually to self.load_extension().
Required Arguments:
ext_list
A list of extension modules.
:param ext_list: A list of extension modules.
:type ext_list: list
"""
for ext in ext_list:

491
cement/core/foundation.py
View File

@ -1,4 +1,4 @@
"""Cement core application module."""
"""Cement core foundation module."""
import re
import os
@ -24,6 +24,10 @@ def cement_signal_handler(signum, frame):
Catch a signal, run the 'signal' hook, and then raise an exception
allowing the app to handle logic elsewhere.
:param signum: The signal number
:param frame: The signal frame.
:raises: cement.core.exc.CementSignalError
"""
LOG.debug('Caught signal %s' % signum)
@ -36,228 +40,6 @@ class CementApp(meta.MetaMixin):
"""
The primary class to build applications from.
Optional / Meta Arguments:
label
The name of the application. This should be the common name as
you would see and use at the command line. For example
'helloworld', or 'my-awesome-app'.
Default: None
bootstrap
A bootstrapping module to load after app creation, and before
app.setup() is called. This is useful for larger applications
that need to offload their bootstrapping code such as registering
hooks/handlers/etc to another file.
This must be a dotted python module path.
I.e. 'myapp.bootstrap' (myapp/bootstrap.py). Cement will then
import the module, and if the module has a 'load()' function, that
will also be called. Essentially, this is the same as an
extension or plugin, but as a facility for the application itself
to bootstrap 'hardcoded' application code. It is also called
before plugins are loaded.
Default: None
debug
Toggles debug output. By default, this setting is also overridden
by the '[base] -> debug' config setting parsed in any
of the application configuration files (where [base] is the
base configuration section of the application which is determined
by Meta.config_section but defaults to Meta.label).
Default: False
argv
A list of arguments to use for parsing command line arguments
and options.
Default: sys.argv[1:]
arguments_override_config
A boolean to toggle whether command line arguments should
override configuration values if the argument name matches the
config key. I.e. --foo=bar would override config['myapp']['foo'].
Default: False
config_section
The base configuration section for the application.
Default: None
Note: Though Meta.config_section defaults to None, Cement will
set this to the value of Meta.label (or in other words, the name
of the application).
config_defaults
Default configuration dictionary. Must be of type 'dict'.
Default: None
config_files
List of config files to parse.
Default: None
Note: Though Meta.config_section defaults to None, Cement will
set this to a default list based on Meta.label (or in other words,
the name of the application). This will equate to:
['/etc/<app_label>/<app_label>.conf', '~/.<app_label>.conf', '~/.<app_label>/config']
plugins
A list of plugins to load. This is generally considered bad
practice since plugins should be dynamically enabled/disabled
via a plugin config file.
Default: []
plugin_config_dir
A directory path where plugin config files can be found. Files
must end in '.conf'. By default, this setting is also overridden
by the '[base] -> plugin_config_dir' config setting parsed in any
of the application configuration files.
Default: None
Note: Though the meta default is None, Cement will set this to
'/etc/<app_label>/plugins.d/' if not set during app.setup().
plugin_dir
A directory path where plugin code (modules) can be loaded from.
By default, this setting is also overridden by the
'[base] -> plugin_dir' config setting parsed in any of the
application configuration files (where [base] is the
base configuration section of the application which is determined
by Meta.config_section but defaults to Meta.label).
Default: None
Note: Though the meta default is None, Cement will set this to
'/usr/lib/<app_label>/plugins/' if not set during app.setup()
plugin_bootstrap
A python package (dotted import path) where plugin code can be
loaded from. This is generally something like 'myapp.plugins'
where a plugin file would live at 'myapp/plugins/myplugin.py'.
This provides a facility for applications that use 'namespace'
packages allowing plugins to share the applications python
namespace.
Default: None
catch_signals
List of signals to catch, and raise exc.CementSignalError for.
Can be set to None to disable signal handling.
Default: [signal.SIGTERM, signal.SIGINT]
signal_handler
A function that is called to handle any caught signals.
Default: cement.core.foundation.cement_signal_handler
config_handler
A handler class that implements the IConfig interface. This can
be a string (label of a registered handler), an uninstantiated
class, or an instantiated class object.
Default: cement.ext.ext_configparser.ConfigParserConfigHandler
extension_handler
A handler class that implements the IExtension interface. This can
be a string (label of a registered handler), an uninstantiated
class, or an instantiated class object.
Default: cement.core.extension.CementExtensionHandler
log_handler
A handler class that implements the ILog interface. This can
be a string (label of a registered handler), an uninstantiated
class, or an instantiated class object.
Default: cement.ext.ext_logging.LoggingLogHandler
plugin_handler
A handler class that implements the IPlugin interface. This can
be a string (label of a registered handler), an uninstantiated
class, or an instantiated class object.
Default: cement.ext.ext_plugin.CementPluginHandler
argument_handler
A handler class that implements the IArgument interface. This can
be a string (label of a registered handler), an uninstantiated
class, or an instantiated class object.
Default: cement.ext.ext_argparse.ArgParseArgumentHandler
output_handler
A handler class that implements the IOutput interface. This can
be a string (label of a registered handler), an uninstantiated
class, or an instantiated class object.
Default: cement.ext.ext_nulloutput.NullOutputHandler
cache_handler
A handler class that implements the ICache interface. This can
be a string (label of a registered handler), an uninstantiated
class, or an instantiated class object.
Default: None
base_controller
This is the base application controller. If a controller is set,
runtime operations are passed to the controller for command
dispatch and argument parsing when CementApp.run() is called.
Default: None
core_extensions
List of Cement core extensions. These are generally required by
Cement and should only be modified if you know what you're
doing. Use 'extensions' to add to this list, rather than
overriding core extensions. That said if you want to prune down
your application, you can remove core extensions if they are
not necessary (for example if using your own log handler
extension you likely don't want/need LoggingLogHandler to be
registered).
Default: ['cement.ext.ext_nulloutput',
'cement.ext.ext_plugin',
'cement.ext.ext_configparser',
'cement.ext.ext_logging',
'cement.ext.ext_argparse']
extensions
List of additional framework extensions to load.
Default: []
core_meta_override
List of meta options that can/will be overridden by config options
of the '[base]' config section (where [base] is the base
configuration section of the application which is determined by
Meta.config_section but defaults to Meta.label). These overrides
are required by the framework to function properly and should not
be used by end user (developers) unless you really know what
you're doing. To add your own extended meta overrides please use
'meta_override'.
Default: ['debug', 'plugin_config_dir', 'plugin_dir']
meta_override
List of meta options that can/will be overridden by config options
of the '[base]' config section (where [base] is the
base configuration section of the application which is determined
by Meta.config_section but defaults to Meta.label).
Default: []
Usage:
The following is the simplest CementApp:
@ -301,7 +83,6 @@ class CementApp(meta.MetaMixin):
app = MyApp()
try:
app.setup()
app.run()
finally:
@ -309,29 +90,193 @@ class CementApp(meta.MetaMixin):
"""
class Meta:
"""
Application meta-data (can also be passed as keyword arguments to the
parent class).
"""
label = None
"""
The name of the application. This should be the common name as you
would see and use at the command line. For example 'helloworld', or
'my-awesome-app'.
"""
debug = False
"""
Toggles debug output. By default, this setting is also overridden
by the '[base] -> debug' config setting parsed in any
of the application configuration files (where [base] is the
base configuration section of the application which is determined
by Meta.config_section but defaults to Meta.label).
"""
config_files = None
"""
List of config files to parse.
Note: Though Meta.config_section defaults to None, Cement will
set this to a default list based on Meta.label (or in other words,
the name of the application). This will equate to:
.. code-block:: python
['/etc/<app_label>/<app_label>.conf',
'~/.<app_label>.conf',
'~/.<app_label>/config']
"""
plugins = []
"""
A list of plugins to load. This is generally considered bad
practice since plugins should be dynamically enabled/disabled
via a plugin config file.
"""
plugin_config_dir = None
"""
A directory path where plugin config files can be found. Files
must end in '.conf'. By default, this setting is also overridden
by the '[base] -> plugin_config_dir' config setting parsed in any
of the application configuration files.
Note: Though the meta default is None, Cement will set this to
``/etc/<app_label>/plugins.d/`` if not set during app.setup().
"""
plugin_bootstrap = None
"""
A python package (dotted import path) where plugin code can be
loaded from. This is generally something like 'myapp.plugins'
where a plugin file would live at ``myapp/plugins/myplugin.py``.
This provides a facility for applications that use 'namespace'
packages allowing plugins to share the applications python
namespace.
"""
plugin_dir = None
"""
A directory path where plugin code (modules) can be loaded from.
By default, this setting is also overridden by the
'[base] -> plugin_dir' config setting parsed in any of the
application configuration files (where [base] is the
base configuration section of the application which is determined
by Meta.config_section but defaults to Meta.label).
Note: Though the meta default is None, Cement will set this to
``/usr/lib/<app_label>/plugins/`` if not set during app.setup()
"""
argv = list(sys.argv[1:])
"""
A list of arguments to use for parsing command line arguments
and options.
"""
arguments_override_config = False
"""
A boolean to toggle whether command line arguments should
override configuration values if the argument name matches the
config key. I.e. --foo=bar would override config['myapp']['foo'].
"""
config_section = None
"""
The base configuration section for the application.
Note: Though Meta.config_section defaults to None, Cement will
set this to the value of Meta.label (or in other words, the name
of the application).
"""
config_defaults = None
"""Default configuration dictionary. Must be of type 'dict'."""
catch_signals = [signal.SIGTERM, signal.SIGINT]
"""
List of signals to catch, and raise exc.CementSignalError for.
Can be set to None to disable signal handling.
"""
signal_handler = cement_signal_handler
"""A function that is called to handle any caught signals."""
config_handler = ext_configparser.ConfigParserConfigHandler
"""
A handler class that implements the IConfig interface. This can
be a string (label of a registered handler), an uninstantiated
class, or an instantiated class object.
"""
extension_handler = extension.CementExtensionHandler
"""
A handler class that implements the IExtension interface. This can
be a string (label of a registered handler), an uninstantiated
class, or an instantiated class object.
"""
log_handler = ext_logging.LoggingLogHandler
"""
A handler class that implements the ILog interface. This can
be a string (label of a registered handler), an uninstantiated
class, or an instantiated class object.
"""
plugin_handler = ext_plugin.CementPluginHandler
"""
A handler class that implements the IPlugin interface. This can
be a string (label of a registered handler), an uninstantiated
class, or an instantiated class object.
"""
argument_handler = ext_argparse.ArgParseArgumentHandler
"""
A handler class that implements the IArgument interface. This can
be a string (label of a registered handler), an uninstantiated
class, or an instantiated class object.
"""
output_handler = ext_nulloutput.NullOutputHandler
"""
A handler class that implements the IOutput interface. This can
be a string (label of a registered handler), an uninstantiated
class, or an instantiated class object.
"""
cache_handler = None
"""
A handler class that implements the ICache interface. This can
be a string (label of a registered handler), an uninstantiated
class, or an instantiated class object.
"""
base_controller = None
"""
This is the base application controller. If a controller is set,
runtime operations are passed to the controller for command
dispatch and argument parsing when CementApp.run() is called.
"""
extensions = []
"""List of additional framework extensions to load."""
bootstrap = None
"""
A bootstrapping module to load after app creation, and before
app.setup() is called. This is useful for larger applications
that need to offload their bootstrapping code such as registering
hooks/handlers/etc to another file.
This must be a dotted python module path.
I.e. 'myapp.bootstrap' (myapp/bootstrap.py). Cement will then
import the module, and if the module has a 'load()' function, that
will also be called. Essentially, this is the same as an
extension or plugin, but as a facility for the application itself
to bootstrap 'hardcoded' application code. It is also called
before plugins are loaded.
"""
core_extensions = [
'cement.ext.ext_nulloutput',
'cement.ext.ext_plugin',
@ -339,13 +284,41 @@ class CementApp(meta.MetaMixin):
'cement.ext.ext_logging',
'cement.ext.ext_argparse',
]
"""
List of Cement core extensions. These are generally required by
Cement and should only be modified if you know what you're
doing. Use 'extensions' to add to this list, rather than
overriding core extensions. That said if you want to prune down
your application, you can remove core extensions if they are
not necessary (for example if using your own log handler
extension you likely don't want/need LoggingLogHandler to be
registered).
"""
core_meta_override = [
'debug',
'plugin_config_dir',
'plugin_dir'
]
"""
List of meta options that can/will be overridden by config options
of the '[base]' config section (where [base] is the base
configuration section of the application which is determined by
Meta.config_section but defaults to Meta.label). These overrides
are required by the framework to function properly and should not
be used by end user (developers) unless you really know what
you're doing. To add your own extended meta overrides please use
'meta_override'.
"""
meta_override = []
"""
List of meta options that can/will be overridden by config options
of the '[base]' config section (where [base] is the
base configuration section of the application which is determined
by Meta.config_section but defaults to Meta.label).
"""
def __init__(self, label=None, **kw):
super(CementApp, self).__init__(**kw)
@ -369,6 +342,7 @@ class CementApp(meta.MetaMixin):
@property
def argv(self):
"""The arguments list that will be used when self.run() is called."""
return self._meta.argv
def extend(self, member_name, member_object):
@ -378,13 +352,11 @@ class CementApp(meta.MetaMixin):
extensions to provide functionality that travel along with the
application object.
Required Arguments:
member_name
The name to attach the object to.
member_object
The function or class object to attach to CementApp().
:param member_name: The name to attach the object to.
:type member_name: str
:param member_object: The function or class object to attach to
CementApp().
:raises: cement.core.exc.CementRuntimeError
"""
if hasattr(self, member_name):
@ -416,7 +388,7 @@ class CementApp(meta.MetaMixin):
executed (possibly letting the developer perform other actions
before full execution.).
All handlers should be instantiated and callable after _setup() is
All handlers should be instantiated and callable after setup is
complete.
"""
@ -491,16 +463,9 @@ class CementApp(meta.MetaMixin):
This is a simple wrapper around self.output.render() which simply
returns an empty string if no self.output handler is defined.
Required Arguments:
data
The data dictionary to render.
Optional Arguments:
template
The template to render to. Default: None (some output
handlers do not use templates).
:param data: The data dictionary to render.
:param template: The template to render to. Default: None (some
output handlers do not use templates).
"""
for res in hook.run('pre_render', self, data):
@ -525,22 +490,15 @@ class CementApp(meta.MetaMixin):
@property
def pargs(self):
"""
A shortcut for self.args.parsed_args.
"""
"""A shortcut for self.args.parsed_args."""
return self.args.parsed_args
def add_arg(self, *args, **kw):
"""
A shortcut for self.args.add_argument.
"""
"""A shortcut for self.args.add_argument."""
self.args.add_argument(*args, **kw)
def _lay_cement(self):
"""
Initialize the framework.
"""
"""Initialize the framework."""
LOG.debug("laying cement for the '%s' application" % \
self._meta.label)
@ -623,7 +581,13 @@ class CementApp(meta.MetaMixin):
the handler to load from backend.handlers, or it can be an
instantiated or non-instantiated handler class.
Returns: The instantiated handler object.
:param handler_type: The type of handler (aka the interface label)
:param hander_def: The handler as defined in CementApp.Meta.
:type handler_def: str, uninstantiated object, or instantiated object
:param raise_error: Whether or not to raise an exception if unable
to resolve the handler.
:type raise_error: boolean
:returns: The instantiated handler object.
"""
han = None
@ -777,6 +741,25 @@ class CementApp(meta.MetaMixin):
def validate_config(self):
"""
Validate application config settings.
Usage:
.. code-block:: python
import os
from cement.core import foundation
class MyApp(foundation.CementApp):
class Meta:
label = 'myapp'
def validate_config(self):
# test that the log file directory exist, if not create it
logdir = os.path.dirname(self.config.get('log', 'file'))
if not os.path.exists(logdir):
os.makedirs(logdir)
"""
pass

5
cement/core/log.py
View File

@ -144,6 +144,11 @@ class CementLogHandler(handler.CementBaseHandler):
"""
class Meta:
"""
Handler meta-data (can be passed as keyword arguments to the parent
class).
"""
interface = ILog
def __init__(self, *args, **kw):

5
cement/core/output.py
View File

@ -82,6 +82,11 @@ class CementOutputHandler(handler.CementBaseHandler):
"""
class Meta:
"""
Handler meta-data (can be passed as keyword arguments to the parent
class).
"""
interface = IOutput
def __init__(self, *args, **kw):

5
cement/core/plugin.py
View File

@ -93,6 +93,11 @@ class CementPluginHandler(handler.CementBaseHandler):
"""
class Meta:
"""
Handler meta-data (can be passed as keyword arguments to the parent
class).
"""
interface = IPlugin
def __init__(self, *args, **kw):

4
doc/source/api/core/arg.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.core.arg
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

3
doc/source/api/core/backend.rst
View File

@ -5,4 +5,5 @@
.. automodule:: cement.core.backend
:members:
:undoc-members:
:undoc-members:
:show-inheritance:

4
doc/source/api/core/cache.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.core.cache
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/core/config.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.core.config
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/core/controller.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.core.controller
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/core/exc.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.core.exc
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/core/extension.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.core.extension
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

3
doc/source/api/core/foundation.rst
View File

@ -5,4 +5,5 @@
.. automodule:: cement.core.foundation
:members:
:undoc-members:
:undoc-members:
:show-inheritance:

4
doc/source/api/core/handler.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.core.handler
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/core/hook.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.core.hook
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/core/interface.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.core.interface
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/core/log.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.core.log
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/core/meta.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.core.meta
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/core/output.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.core.output
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/core/plugin.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.core.plugin
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

2
doc/source/api/ext/ext_argparse.rst
View File

@ -6,3 +6,5 @@
.. automodule:: cement.ext.ext_argparse
:members:
:undoc-members:
:private-members:
:show-inheritance:

3
doc/source/api/ext/ext_configparser.rst
View File

@ -5,3 +5,6 @@
.. automodule:: cement.ext.ext_configparser
:members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/ext/ext_json.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.ext.ext_json
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/ext/ext_logging.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.ext.ext_logging
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

2
doc/source/api/ext/ext_nulloutput.rst
View File

@ -6,3 +6,5 @@
.. automodule:: cement.ext.ext_nulloutput
:members:
:undoc-members:
:private-members:
:show-inheritance:

2
doc/source/api/ext/ext_plugin.rst
View File

@ -6,3 +6,5 @@
.. automodule:: cement.ext.ext_plugin
:members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/utils/fs.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.utils.fs
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/utils/misc.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.utils.misc
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/utils/shell.rst
View File

@ -5,4 +5,6 @@
.. automodule:: cement.utils.shell
:members:
:undoc-members:
:undoc-members:
:private-members:
:show-inheritance:

4
doc/source/api/utils/test.rst
View File

@ -6,7 +6,9 @@
.. automodule:: cement.utils.test
:members:
:undoc-members:
:private-members:
:show-inheritance:
.. autoclass:: cement.utils.test.raises
.. autofunction:: cement.utils.test.ok
.. autofunction:: cement.utils.test.eq