Warning

This is the documentation for a development version of flagman.

Documentation for the Most Recent Stable Version

API Reference

This part of the documentation covers all of the interfaces exposed by flagman.

The Action Class

This class is the abstract class you should inherit from to write your own actions.

class flagman.Action(*args)

The base Action class.

_close()

Close the action, preventing future runs and executing tear down logic.

Return type:None

set_up(*args)

Perform any required set up for the Action.

Return type:None

run()

Run the Action.

Return type:None

tear_down()

Perform any required clean up for the Action.

Return type:None

The Core Module

These functions and members are imported from the flagman.core module to be used if using flagman as a library instead of a standalone tool.

flagman.HANDLED_SIGNALS List[signal.Signals]

Signals in this list are handled by flagman. The CLI module auto-generates the appropriate CLI option for each signal.

flagman.KNOWN_ACTIONS Mapping[ActionName, Type[Action]]

Mapping of action entry point names to Action classes. Populated from the pkg_resources flagman.action entry point group.

flagman.create_action_bundles(args_dict)

Parse the enabled actions and insert them into the global ACTION_BUNDLES mapping.

The input dictionary should be like:

{'usr1': [['action1', 'arg1a', 'arg2a'], ['action2', 'arg2a']],
 'usr2': [['action3'], ['action4', 'arg4a', 'arg4b']]}

Parameters:args_dict (Mapping[str, Iterable[Sequence[str]]]) – a mapping of strings to an Iterable of Action names Return type:int Returns:The number of configured actions

flagman.run()

Run the flagman “event loop”.

Waits for a signal to be raised and dispatches to the user-defined handlers as appropriate.

Return type:None

flagman.set_handlers()

Register handlers for the signals we’re interested in.

Uses the global HANDLED_SIGNALS to decide what signals to register for.

Danger starts here!

Return type:None

Errors and Exceptions

exception flagman.ActionClosed

The Action is closed and no longer will do anything on a call to run().

Built-in Actions

Print Actions

Print actions for flagman.

Most likely only useful for debugging.

class flagman.actions.PrintAction(*args)

Bases: flagman.actions.action.Action

A simple Action that prints messages at the various stages of execution.

(message: str)

set_up(msg)

Store the message to be printed and print “init” message.

Parameters:msg (str) – the message Return type:None

run()

Print the message.

Return type:None

tear_down()

Print “cleanup” message.

Return type:None

class flagman.actions.DelayedPrintAction(*args)

Bases: flagman.actions.print.PrintAction

An Action that prints messages at the various stages of execution and has a configurable delay in the run stage.

(message: str, delay: int)

set_up(msg, delay)

Store the message and the delay.

Parameters:

• msg (str) – the message
• delay (str) – the delay in seconds

Return type:

None

run()

Print the message, delay, and print a finished message.

Return type:None

class flagman.actions.PrintOnceAction(*args)

Bases: flagman.actions.print.PrintAction

An Action that prints a message once and then cleans up after itself.

(message: str)

set_up(msg)

Store the message.

Parameters:msg (str) – the message Return type:None

run()

Print the message and close the action.

Return type:None

Types

Type aliases used throughout flagman.

flagman.types.ActionName

Type alias for the name of an Action.

alias of builtins.str

flagman.types.ActionArgument

Type alias for the the argument to an Action.

alias of builtins.str

flagman.types.SignalNumber

Type alias for a signal number.

alias of builtins.int

The CLI Module

Module that contains the command line for flagman.

Why does this file exist, and why not put this in __main__? You might be tempted to import things from __main__ later, but that will cause problems–the code will get executed twice:

• When you run python -m flagman python will execute __main__.py as a script. That means there won’t be any flagman.__main__ in sys.modules.
• When you import __main__ it will get executed again (as a module) because there’s no flagman.__main__ in sys.modules.

Also see (1) from http://click.pocoo.org/5/setuptools/#setuptools-integration

class flagman.cli.AllAttrEmptyString

Return ‘’ for any attribute.

flagman.cli._sigterm_handler(signum, _frame)

Raise SystemExit on SIGTERM.

Return type:None

flagman.cli.parse_args(argv)

Parse the arguments for the flagman CLI.

Parameters:argv (Sequence[str]) – a Squence of argument strings Return type:Namespace Returns:the parsed arguments as an argparse Namespace

flagman.cli.list_actions()

Pretty-print the list of available actions to stdout.

Return type:None

flagman.cli.main()

The main function of the flagman CLI.

Don’t call this from library code, use your own version implenting analogous logic.

Return type:Optional[int] Returns:An exit code or None

flagman.cli.main_wrapper()

Main wrapper that handles graceful exiting on KeyboardInterrupt.

Return type:Optional[int] Returns:An exit code or None

Systemd Notify Utilities

Systemd notification protocol implementation.

class flagman.sd_notify.SystemdNotifier(debug=False)

This class holds a connection to the systemd notification socket.

It can be used to send messages to systemd using its notify method.

__init__(debug=False)

Instantiate a new notifier object.

This will initiate a connection to the systemd notification socket.

Normally this method silently ignores exceptions (for example, if the systemd notification socket is not available) to allow applications to function on non-systemd based systems. However, setting debug=True will cause this method to raise any exceptions generated to the caller, to aid in debugging.

Return type:None

notify(state)

Send a notification to systemd.

State is a string; see the man page of sd_notify (http://www.freedesktop.org/software/systemd/man/sd_notify.html) for a description of the allowable values.

Normally this method silently ignores exceptions (for example, if the systemd notification socket is not available) to allow applications to function on non-systemd based systems. However, setting debug=True will cause this method to raise any exceptions generated to the caller, to aid in debugging.

Return type:None