# salt.renderers.py

## Pure python state renderer

To use this renderer, the SLS file should contain a function called `run` which returns highstate data.

The highstate data is a dictionary containing identifiers as keys, and execution dictionaries as values. For example the following state declaration in YAML:

    common_packages:
      pkg.installed:
       - pkgs:
          - curl
          - vim

translates to:

    {'common_packages': {'pkg.installed': [{'pkgs': ['curl', 'vim']}]}}

In this module, a few objects are defined for you, giving access to Salt's execution functions, grains, pillar, etc. They are:

- `__salt__` - Execution functions (i.e. `__salt__['test.echo']('foo')`)

- `__grains__` - Grains (i.e. `__grains__['os']`)

- `__pillar__` - Pillar data (i.e. `__pillar__['foo']`)

- `__opts__` - Minion configuration options

- `__env__` - The effective salt fileserver environment (i.e. `base`). Also referred to as a "saltenv". `__env__` should not be modified in a pure python SLS file. To use a different environment, the environment should be set when executing the state. This can be done in a couple different ways:

  - Using the `saltenv` argument on the salt CLI (i.e. `salt '*' state.sls foo.bar.baz saltenv=env_name`).

  - By adding a `saltenv` argument to an individual state within the SLS file. In other words, adding a line like this to the state's data structure: `{'saltenv': 'env_name'}`

- `__sls__` - The SLS path of the file. For example, if the root of the base environment is `/srv/salt`, and the SLS file is `/srv/salt/foo/bar/baz.sls`, then `__sls__` in that file will be `foo.bar.baz`.

When used in a scenario where additional user-provided context data is supplied (such as with `file.managed`), the additional data will typically be injected into the script as one or more global variables:

    /etc/http/conf/http.conf:
      file.managed:
        - source: salt://apache/generate_http_conf.py
        - template: py
        - context:
            # Will be injected as the global variable "site_name".
            site_name: {{ site_name }}

When writing a reactor SLS file the global context `data` (same as context `{{ data }}` for states written with Jinja + YAML) is available. The following YAML + Jinja state declaration:

    {% if data['id'] == 'mysql1' %}
    highstate_run:
      local.state.apply:
        - tgt: mysql1
    {% endif %}

translates to:

    if data['id'] == 'mysql1':
        return {'highstate_run': {'local.state.apply': [{'tgt': 'mysql1'}]}}

### Full Example

     1 #!py
     2
     3 def run():
     4     config = {}
     5
     6     if __grains__['os'] == 'Ubuntu':
     7         user = 'ubuntu'
     8         group = 'ubuntu'
     9         home = '/home/{0}'.format(user)
    10     else:
    11         user = 'root'
    12         group = 'root'
    13         home = '/root/'
    14
    15     config['s3cmd'] = {
    16         'pkg': [
    17             'installed',
    18             {'name': 's3cmd'},
    19         ],
    20     }
    21
    22     config[home + '/.s3cfg'] = {
    23         'file.managed': [
    24             {'source': 'salt://s3cfg/templates/s3cfg'},
    25             {'template': 'jinja'},
    26             {'user': user},
    27             {'group': group},
    28             {'mode': 600},
    29             {'context': {
    30                 'aws_key': __pillar__['AWS_ACCESS_KEY_ID'],
    31                 'aws_secret_key': __pillar__['AWS_SECRET_ACCESS_KEY'],
    32                 },
    33             },
    34         ],
    35     }
    36
    37     return config

salt.renderers.py.render(template, saltenv='base', sls='', tmplpath=None, **kws)

  Render the python module's components

  Return type:

    string