charmhelpers.core.hookenv

Config	A dictionary representation of the charm’s config.yaml, with some
Hooks	A convenient handler for hook functions.
Serializable	Wrapper, an object that can be serialized to yaml or json
UnregisteredHookError	Raised when an undefined hook is called
action_fail	Sets the action status to failed and sets the error message.
action_get
action_set	Sets the values to be returned after the action finishes
cached	Cache return values for multiple executions of func + args
charm_dir	Return the root directory of the current charm
charm_name
close_port	Close a service network port
config
execution_environment	A convenient bundling of the current execution context
flush	Flushes any entries from function cache where the
hook_name	The name of the currently executing hook
in_relation_hook	Determine whether we’re running in a relation hook
is_relation_made
local_unit	Local unit ID
log	Write a message to the juju log
metadata
open_port	Open a service network port
related_units
relation_for_unit
relation_get
relation_id	The relation ID for the current relation hook
relation_ids
relation_set	Set relation information for the current unit
relation_type	The scope for the current relation hook
relation_types
relations
relations_for_id
relations_of_type
remote_unit	The remote unit for the current relation hook
service_name	The name service group this unit belongs to
unit_get
unit_private_ip	Get this unit’s private IP address

Interactions with the Juju environment

class charmhelpers.core.hookenv.Config(*args, **kw)

Bases: dict

A dictionary representation of the charm’s config.yaml, with some extra features:

• See which values in the dictionary have changed since the previous hook.
• For values that have changed, see what the previous value was.
• Store arbitrary data for use in a later hook.

NOTE: Do not instantiate this object directly - instead call hookenv.config(), which will return an instance of Config.

Example usage:

>>> # inside a hook
>>> from charmhelpers.core import hookenv
>>> config = hookenv.config()
>>> config['foo']
'bar'
>>> # store a new key/value for later use
>>> config['mykey'] = 'myval'


>>> # user runs `juju set mycharm foo=baz`
>>> # now we're inside subsequent config-changed hook
>>> config = hookenv.config()
>>> config['foo']
'baz'
>>> # test to see if this val has changed since last hook
>>> config.changed('foo')
True
>>> # what was the previous value?
>>> config.previous('foo')
'bar'
>>> # keys/values that we add are preserved across hooks
>>> config['mykey']
'myval'

CONFIG_FILE_NAME = '.juju-persistent-config'

changed(key)

Return True if the current value for this key is different from the previous value.

keys()

load_previous(path=None)

Load previous copy of config from disk.

In normal usage you don’t need to call this method directly - it is called automatically at object initialization.

Parameters:path – File path from which to load the previous config. If None, config is loaded from the default location. If path is specified, subsequent save() calls will write to the same path.

previous(key)

Return previous value for this key, or None if there is no previous value.

save()

Save this config to disk.

If the charm is using the Services Framework or :meth:’@hook <Hooks.hook>’ decorator, this is called automatically at the end of successful hook execution. Otherwise, it should be called directly by user code.

To disable automatic saves, set implicit_save=False on this instance.

class charmhelpers.core.hookenv.Hooks(config_save=True)

Bases: object

A convenient handler for hook functions.

Example:

hooks = Hooks()

# register a hook, taking its name from the function name
@hooks.hook()
def install():
    pass  # your code here

# register a hook, providing a custom hook name
@hooks.hook("config-changed")
def config_changed():
    pass  # your code here

if __name__ == "__main__":
    # execute a hook based on the name the program is called by
    hooks.execute(sys.argv)

execute(args)

Execute a registered hook based on args[0]

hook(*hook_names)

Decorator, registering them as hooks

register(name, function)

Register a hook

class charmhelpers.core.hookenv.Serializable(obj)

Bases: UserDict.UserDict

Wrapper, an object that can be serialized to yaml or json

json()

Serialize the object to json

yaml()

Serialize the object to yaml

exception charmhelpers.core.hookenv.UnregisteredHookError

Bases: exceptions.Exception

Raised when an undefined hook is called

charmhelpers.core.hookenv.action_fail(message)

Sets the action status to failed and sets the error message.

The results set by action_set are preserved.

charmhelpers.core.hookenv.action_get(*args, **kwargs)

charmhelpers.core.hookenv.action_set(values)

Sets the values to be returned after the action finishes

charmhelpers.core.hookenv.cached(func)

Cache return values for multiple executions of func + args

For example:

@cached
def unit_get(attribute):
    pass

unit_get('test')

will cache the result of unit_get + ‘test’ for future calls.

charmhelpers.core.hookenv.charm_dir()

Return the root directory of the current charm

charmhelpers.core.hookenv.charm_name(*args, **kwargs)

charmhelpers.core.hookenv.close_port(port, protocol='TCP')

Close a service network port

charmhelpers.core.hookenv.config(*args, **kwargs)

charmhelpers.core.hookenv.execution_environment()

A convenient bundling of the current execution context

charmhelpers.core.hookenv.flush(key)

Flushes any entries from function cache where the key is found in the function+args

charmhelpers.core.hookenv.hook_name()

The name of the currently executing hook

charmhelpers.core.hookenv.in_relation_hook()

Determine whether we’re running in a relation hook

charmhelpers.core.hookenv.is_relation_made(*args, **kwargs)

charmhelpers.core.hookenv.local_unit()

Local unit ID

charmhelpers.core.hookenv.log(message, level=None)

Write a message to the juju log

charmhelpers.core.hookenv.metadata(*args, **kwargs)

charmhelpers.core.hookenv.open_port(port, protocol='TCP')

Open a service network port

charmhelpers.core.hookenv.related_units(*args, **kwargs)

charmhelpers.core.hookenv.relation_for_unit(*args, **kwargs)

charmhelpers.core.hookenv.relation_get(*args, **kwargs)

charmhelpers.core.hookenv.relation_id()

The relation ID for the current relation hook

charmhelpers.core.hookenv.relation_ids(*args, **kwargs)

charmhelpers.core.hookenv.relation_set(relation_id=None, relation_settings=None, **kwargs)

Set relation information for the current unit

charmhelpers.core.hookenv.relation_type()

The scope for the current relation hook

charmhelpers.core.hookenv.relation_types(*args, **kwargs)

charmhelpers.core.hookenv.relations(*args, **kwargs)

charmhelpers.core.hookenv.relations_for_id(*args, **kwargs)

charmhelpers.core.hookenv.relations_of_type(*args, **kwargs)

charmhelpers.core.hookenv.remote_unit()

The remote unit for the current relation hook

charmhelpers.core.hookenv.service_name()

The name service group this unit belongs to

charmhelpers.core.hookenv.unit_get(*args, **kwargs)

charmhelpers.core.hookenv.unit_private_ip()

Get this unit’s private IP address