class kingpin.actors.misc.Macro(*args, **kwargs)[source]

Parses a kingpin script, instantiates and executes it.


Kingpin JSON/YAML has 2 passes at its validity. Script syntax must be valid, with the exception of a few useful deviations allowed by demjson parser. Main one being the permission of inline comments via /* this */ syntax.

The second pass is validating the Schema. The script will be validated for schema-conformity as one of the first things that happens at load-time when the app starts up. If it fails, you will be notified immediately.

Lastly after the JSON/YAML is established to be valid, all the tokens are replaced with their specified value. Any key/value pair passed in the tokens option will be available inside of the JSON file as %KEY% and replaced with the value at this time.

In a situation where nested Macro executions are invoked the tokens do not propagate from outter macro into the inner. This allows to reuse token names, but forces the user to specify every token needed. Similarly, if environment variables are used for token replacement in the main file, these tokens are not available in the subsequent macros.


In an effort to prevent mid-run errors, we pre-instantiate all Actor objects all at once before we ever begin executing code. This ensures that major typos or misconfigurations in the JSON/YAML will be caught early on.


misc.Macro actor simply calls the execute() method of the most-outter actor; be it a single action, or a group actor.


Macro:String of local path to a JSON/YAML script.
Tokens:Dictionary to search/replace within the file.


{ "desc": "Stage 1",
  "actor": "misc.Macro",
  "options": {
    "macro": "deployment/stage-1.json",
    "tokens": {
      "TIMEOUT": 360,
      "RELEASE": "%RELEASE%"

Dry Mode

Fully supported – instantiates the actor inside of JSON with dry=True. The behavior of the consecutive actor is unique to each; read their description for more information on dry mode.


class kingpin.actors.misc.Sleep(desc=None, options={}, dry=False, warn_on_failure=False, condition=True, init_context={}, init_tokens={}, timeout=None)[source]

Sleeps for an arbitrary number of seconds.


Sleep:Integer of seconds to sleep.


{ "actor": "misc.Sleep",
  "desc": "Sleep for 60 seconds",
  "options": {
    "sleep": 60

Dry Mode

Fully supported – does not actually sleep, just pretends to.


class kingpin.actors.misc.GenericHTTP(desc=None, options={}, dry=False, warn_on_failure=False, condition=True, init_context={}, init_tokens={}, timeout=None)[source]

A very simple actor that allows GET/POST methods over HTTP.

Does a GET or a POST to a specified URL.


Url:Destination URL
Data:Optional POST data as a dict. Will convert into key=value&key2=value2.. Exclusive of data-json option.
Data-json:Optional POST data as a dict. Will stringify and pass as JSON. Exclusive of data option.
Username:Optional for HTTPAuth.
Password:Optional for HTTPAuth.


{ "actor": "misc.GenericHTTP",
  "desc": "Make a simple web call",
  "options": {
    "url": "http://example.com/rest/api/v1?id=123&action=doit",
    "username": "secret",
    "password": "%SECRET_PASSWORD%"

Dry Mode

Will not do anything in dry mode except print a log statement.