Salt Coding Style¶

Linting¶

Most Salt style conventions are codified in Salt's .pylintrc file. Salt's pylint file has two dependencies: pylint and saltpylint. You can install these dependencies with pip:

pip install pylint
pip install saltpylint

The .pylintrc file is found in the root of the Salt project and can be passed as an argument to the pylint program as follows:

pylint --rcfile=/path/to/salt/.pylintrc salt/dir/to/lint

Variables¶

Variables should be a minimum of three characters and should provide an easy-to-understand name of the object being represented.

When keys and values are iterated over, descriptive names should be used to represent the temporary variables.

Multi-word variables should be separated by an underscore.

Variables which are two-letter words should have an underscore appended to them to pad them to three characters.

Strings¶

Salt follows a few rules when formatting strings:

def foo():
    '''
    A function that does things
    '''
    name = 'A name'
    return name

data = 'some text'
more = '{0} and then some'.format(data)

def bar():
    '''
    Here lies a docstring with a newline after the quotes and is the salty
    way to handle it! Vertical code is the way to go!
    '''
    return

def baz():
    '''This is not ok!'''
    return

def new_func(msg=''):
    '''
    .. versionadded:: 0.16.0

    Prints what was passed to the function.

    msg : None
        The string to be printed.
    '''
    print msg

def new_func(msg='', signature=''):
    '''
    .. versionadded:: 0.16.0

    Prints what was passed to the function.

    msg : None
        The string to be printed. Will be prepended with 'Greetings! '.

    .. versionchanged:: 0.17.1

    signature : None
        An optional signature.

    .. versionadded 0.17.0
    '''
    print 'Greetings! {0}\n\n{1}'.format(msg, signature)

Dictionaries¶

Dictionaries should be initialized using {} instead of dict().

See here for an in-depth discussion of this topic.

Imports¶

Salt code prefers importing modules and not explicit functions. This is both a style and functional preference. The functional preference originates around the fact that the module import system used by pluggable modules will include callable objects (functions) that exist in the direct module namespace. This is not only messy, but may unintentionally expose code python libs to the Salt interface and pose a security problem.

To say this more directly with an example, this is GOOD:

import os

def minion_path():
    path = os.path.join(self.opts['cachedir'], 'minions')
    return path

This on the other hand is DISCOURAGED:

from os.path import join

def minion_path():
    path = join(self.opts['cachedir'], 'minions')
    return path

The time when this is changed is for importing exceptions, generally directly importing exceptions is preferred:

This is a good way to import exceptions:

from salt.exceptions import CommandExecutionError

from __future__ import absolute_import

Vertical is Better¶

When writing Salt code, vertical code is generally preferred. This is not a hard rule but more of a guideline. As PEP 8 specifies, Salt code should not exceed 79 characters on a line, but it is preferred to separate code out into more newlines in some cases for better readability:

import os

os.chmod(
        os.path.join(self.opts['sock_dir'],
            'minion_event_pub.ipc'),
        448
        )

Where there are more line breaks, this is also apparent when constructing a function with many arguments, something very common in state functions for instance:

def managed(name,
        source=None,
        source_hash='',
        user=None,
        group=None,
        mode=None,
        template=None,
        makedirs=False,
        context=None,
        replace=True,
        defaults=None,
        env=None,
        backup='',
        **kwargs):

Indenting¶

Some confusion exists in the python world about indenting things like function calls, the above examples use 8 spaces when indenting comma-delimited constructs.

The confusion arises because the pep8 program INCORRECTLY flags this as wrong, where PEP 8, the document, cites only using 4 spaces here as wrong, as it doesn't differentiate from a new indent level.

Right:

def managed(name,
        source=None,
        source_hash='',
        user=None)

WRONG:

def managed(name,
    source=None,
    source_hash='',
    user=None)

Lining up the indent is also correct:

def managed(name,
            source=None,
            source_hash='',
            user=None)

This also applies to function calls and other hanging indents.

pep8 and Flake8 (and, by extension, the vim plugin Syntastic) will complain about the double indent for hanging indents. This is a known conflict between pep8 (the script) and the actual PEP 8 standard. It is recommended that this particular warning be ignored with the following lines in ~/.config/flake8:

[flake8]
ignore = E226,E241,E242,E126

Make sure your Flake8/pep8 are up to date. The first three errors are ignored by default and are present here to keep the behavior the same. This will also work for pep8 without the Flake8 wrapper -- just replace all instances of 'flake8' with 'pep8', including the filename.

Code Churn¶

Many pull requests have been submitted that only churn code in the name of PEP 8. Code churn is a leading source of bugs and is strongly discouraged. While style fixes are encouraged they should be isolated to a single file per commit, and the changes should be legitimate, if there are any questions about whether a style change is legitimate please reference this document and the official PEP 8 (http://legacy.python.org/dev/peps/pep-0008/) document before changing code. Many claims that a change is PEP 8 have been invalid, please double check before committing fixes.