diff --git a/salt/utils/__init__.py b/salt/utils/__init__.py index 3b0bcd0af3f..2d6191ba4c8 100644 --- a/salt/utils/__init__.py +++ b/salt/utils/__init__.py @@ -22,6 +22,7 @@ # DEPRECATED FUNCTIONS # # These are not referenced anywhere in the codebase and are slated for removal. +# def option(value, default='', opts=None, pillar=None): ''' Pass in a generic option and receive the value that will be assigned @@ -110,7 +111,10 @@ def required_modules_error(name, docstring): # # MOVED FUNCTIONS # -# These are deprecated and will be removed in Neon. +# These functions have been moved to new locations. The functions below are +# convenience functions which will allow the old function locations to continue +# to work. The convenience functions will be removed in the Neon release. +# def get_accumulator_dir(cachedir): # Late import to avoid circular import. import salt.utils.versions @@ -118,7 +122,7 @@ def get_accumulator_dir(cachedir): salt.utils.versions.warn_until( 'Neon', 'Use of \'salt.utils.get_accumulator_dir\' detected. This function ' - 'has been moved to \'salt.state.accumulator_dir\' as of ' + 'has been moved to \'salt.state.get_accumulator_dir\' as of ' 'Salt Oxygen. This warning will be removed in Salt Neon.' ) return salt.state.get_accumulator_dir(cachedir) @@ -1648,8 +1652,9 @@ def get_values_of_matching_keys(pattern_dict, user_name): salt.utils.versions.warn_until( 'Neon', 'Use of \'salt.utils.get_values_of_matching_keys\' detected. ' - 'This function has been moved to \'salt.utils.master.get_master_key\' ' - 'as of Salt Oxygen. This warning will be removed in Salt Neon.' + 'This function has been moved to ' + '\'salt.utils.master.get_values_of_matching_keys\' as of Salt Oxygen. ' + 'This warning will be removed in Salt Neon.' ) return salt.utils.master.get_values_of_matching_keys(pattern_dict, user_name) diff --git a/salt/utils/cache.py b/salt/utils/cache.py index fad2eeb10eb..32ccb23688d 100644 --- a/salt/utils/cache.py +++ b/salt/utils/cache.py @@ -1,4 +1,7 @@ # -*- coding: utf-8 -*- +''' +In-memory caching used by Salt +''' # Import Python libs from __future__ import absolute_import, print_function import os diff --git a/salt/utils/configcomparer.py b/salt/utils/configcomparer.py index b7a0f279ff6..60b7cf427a2 100644 --- a/salt/utils/configcomparer.py +++ b/salt/utils/configcomparer.py @@ -1,8 +1,8 @@ # -*- coding: utf-8 -*- -""" +''' Utilities for comparing and updating configurations while keeping track of changes in a way that can be easily reported in a state. -""" +''' # Import Python libs from __future__ import absolute_import diff --git a/salt/utils/configparser.py b/salt/utils/configparser.py index d060f9ddd24..6a0023073fd 100644 --- a/salt/utils/configparser.py +++ b/salt/utils/configparser.py @@ -1,4 +1,7 @@ # -*- coding: utf-8 -*- +''' +Custom configparser classes +''' # Import Python libs from __future__ import absolute_import import re diff --git a/salt/utils/crypt.py b/salt/utils/crypt.py index 1f643c81277..86a74e6e98a 100644 --- a/salt/utils/crypt.py +++ b/salt/utils/crypt.py @@ -1,4 +1,7 @@ # -*- coding: utf-8 -*- +''' +Functions dealing with encryption +''' from __future__ import absolute_import diff --git a/salt/utils/data.py b/salt/utils/data.py index 4dac969e2aa..b3b8aa2ff9f 100644 --- a/salt/utils/data.py +++ b/salt/utils/data.py @@ -1,4 +1,8 @@ # -*- coding: utf-8 -*- +''' +Functions for manipulating, inspecting, or otherwise working with data types +and data structures. +''' from __future__ import absolute_import diff --git a/salt/utils/dateutils.py b/salt/utils/dateutils.py index f5fd9f44cfa..941086432dc 100644 --- a/salt/utils/dateutils.py +++ b/salt/utils/dateutils.py @@ -1,4 +1,7 @@ # -*- coding: utf-8 -*- +''' +Convenience functions for dealing with datetime classes +''' from __future__ import absolute_import, division diff --git a/salt/utils/decorators/signature.py b/salt/utils/decorators/signature.py index a9e7662618a..96b7f993d15 100644 --- a/salt/utils/decorators/signature.py +++ b/salt/utils/decorators/signature.py @@ -1,5 +1,8 @@ # -*- coding: utf-8 -*- - +''' +A decorator which returns a function with the same signature of the function +which is being wrapped. +''' # Import Python libs from __future__ import absolute_import import inspect diff --git a/salt/utils/doc.py b/salt/utils/doc.py index f28b2f3c7f4..53a162383ec 100644 --- a/salt/utils/doc.py +++ b/salt/utils/doc.py @@ -1,4 +1,8 @@ # -*- coding: utf-8 -*- +''' +Functions for analyzing/parsing docstrings +''' + from __future__ import absolute_import import re from salt.ext import six diff --git a/salt/utils/files.py b/salt/utils/files.py index d9e76218cf6..64c7a55878f 100644 --- a/salt/utils/files.py +++ b/salt/utils/files.py @@ -1,4 +1,7 @@ # -*- coding: utf-8 -*- +''' +Functions for working with files +''' from __future__ import absolute_import diff --git a/salt/utils/fsutils.py b/salt/utils/fsutils.py index 049ab6c0a2c..df96020b47c 100644 --- a/salt/utils/fsutils.py +++ b/salt/utils/fsutils.py @@ -1,10 +1,10 @@ # -*- coding: utf-8 -*- -# -# Copyright (C) 2014 SUSE LLC - ''' Run-time utilities ''' +# +# Copyright (C) 2014 SUSE LLC + # Import Python libs from __future__ import absolute_import diff --git a/salt/utils/functools.py b/salt/utils/functools.py index 4dbada06f2a..c41a6d57104 100644 --- a/salt/utils/functools.py +++ b/salt/utils/functools.py @@ -1,4 +1,7 @@ # -*- coding: utf-8 -*- +''' +Utility functions to modify other functions +''' from __future__ import absolute_import diff --git a/salt/utils/gitfs.py b/salt/utils/gitfs.py index ad1154d1e57..fe20fce89a8 100644 --- a/salt/utils/gitfs.py +++ b/salt/utils/gitfs.py @@ -1,4 +1,7 @@ # -*- coding: utf-8 -*- +''' +Classes which provide the shared base for GitFS, git_pillar, and winrepo +''' # Import python libs from __future__ import absolute_import diff --git a/salt/utils/jid.py b/salt/utils/jid.py index f8a0664e229..c8dd40902fa 100644 --- a/salt/utils/jid.py +++ b/salt/utils/jid.py @@ -1,4 +1,8 @@ # -*- coding: utf-8 -*- +''' +Functions for creating and working with job IDs +''' + from __future__ import absolute_import from __future__ import print_function diff --git a/salt/utils/job.py b/salt/utils/job.py index a10098019aa..d0f61e06f70 100644 --- a/salt/utils/job.py +++ b/salt/utils/job.py @@ -1,4 +1,7 @@ # -*- coding: utf-8 -*- +''' +Functions for interacting with the job cache +''' # Import Python libs from __future__ import absolute_import diff --git a/salt/utils/json.py b/salt/utils/json.py index ab05bc6a863..e9f5e0969a7 100644 --- a/salt/utils/json.py +++ b/salt/utils/json.py @@ -1,4 +1,7 @@ # -*- coding: utf-8 -*- +''' +Functions to work with JSON +''' from __future__ import absolute_import diff --git a/salt/utils/lazy.py b/salt/utils/lazy.py index 78b6310ced2..a5f96953a49 100644 --- a/salt/utils/lazy.py +++ b/salt/utils/lazy.py @@ -1,4 +1,7 @@ # -*- coding: utf-8 -*- +''' +Lazily-evaluated data structures, primarily used by Salt's loader +''' # Import Python Libs from __future__ import absolute_import diff --git a/salt/utils/mako.py b/salt/utils/mako.py index 11edffe0cc1..6266112f0f4 100644 --- a/salt/utils/mako.py +++ b/salt/utils/mako.py @@ -1,4 +1,7 @@ # -*- coding: utf-8 -*- +''' +Functions for working with Mako templates +''' from __future__ import absolute_import # Import python libs diff --git a/salt/utils/oset.py b/salt/utils/oset.py index 677181f307e..4dbe08c7f30 100644 --- a/salt/utils/oset.py +++ b/salt/utils/oset.py @@ -1,5 +1,5 @@ # -*- coding: utf-8 -*- -""" +''' Available at repository https://github.com/LuminosoInsight/ordered-set @@ -20,7 +20,7 @@ - index() just returns the index of an item - added a __getstate__ and __setstate__ so it can be pickled - added __getitem__ -""" +''' from __future__ import absolute_import import collections diff --git a/salt/utils/process.py b/salt/utils/process.py index f156145a4c2..eccf859f72c 100644 --- a/salt/utils/process.py +++ b/salt/utils/process.py @@ -1,4 +1,7 @@ # -*- coding: utf-8 -*- +''' +Functions for daemonizing and otherwise modifying running processes +''' # Import python libs from __future__ import absolute_import, with_statement diff --git a/salt/utils/profile.py b/salt/utils/profile.py index ce8267ca370..6edcd0fbd34 100644 --- a/salt/utils/profile.py +++ b/salt/utils/profile.py @@ -1,4 +1,7 @@ # -*- coding: utf-8 -*- +''' +Decorator and functions to profile Salt using cProfile +''' from __future__ import absolute_import diff --git a/salt/utils/reactor.py b/salt/utils/reactor.py index e5021ec6fed..debb23598e7 100644 --- a/salt/utils/reactor.py +++ b/salt/utils/reactor.py @@ -1,4 +1,8 @@ # -*- coding: utf-8 -*- +''' +Functions which implement running reactor jobs +''' + # Import python libs from __future__ import absolute_import diff --git a/salt/utils/stringutils.py b/salt/utils/stringutils.py index d30cfb1b0a1..694734c8d8b 100644 --- a/salt/utils/stringutils.py +++ b/salt/utils/stringutils.py @@ -1,4 +1,7 @@ # -*- coding: utf-8 -*- +''' +Functions for manipulating or otherwise processing strings +''' # Import Python libs from __future__ import absolute_import, print_function diff --git a/salt/utils/timed_subprocess.py b/salt/utils/timed_subprocess.py index d77f3ca0ccf..cf7613898e3 100644 --- a/salt/utils/timed_subprocess.py +++ b/salt/utils/timed_subprocess.py @@ -1,5 +1,7 @@ # -*- coding: utf-8 -*- -'''For running command line executables with a timeout''' +''' +For running command line executables with a timeout +''' from __future__ import absolute_import import shlex diff --git a/salt/utils/timeout.py b/salt/utils/timeout.py index 6e3b01ca15a..9837b3a47f3 100644 --- a/salt/utils/timeout.py +++ b/salt/utils/timeout.py @@ -5,16 +5,14 @@ log = logging.getLogger(__name__) +# To give us some leeway when making time-calculations BLUR_FACTOR = 0.95 -""" -To give us some leeway when making time-calculations -""" def wait_for(func, timeout=10, step=1, default=None, func_args=(), func_kwargs=None): - """ - Call `func` at regular intervals and Waits until the given function returns a truthy value - within the given timeout and returns that value. + ''' + Call `func` at regular intervals and Waits until the given function returns + a truthy value within the given timeout and returns that value. @param func: @type func: function @@ -29,7 +27,7 @@ def wait_for(func, timeout=10, step=1, default=None, func_args=(), func_kwargs=N @param func_kwargs: **kwargs for `func` @type func_kwargs: dict @return: `default` or result of `func` - """ + ''' if func_kwargs is None: func_kwargs = dict() max_time = time.time() + timeout diff --git a/salt/utils/user.py b/salt/utils/user.py index 134a5658ecf..737f944c856 100644 --- a/salt/utils/user.py +++ b/salt/utils/user.py @@ -1,4 +1,8 @@ # -*- coding: utf-8 -*- +''' +Functions for querying and modifying a user account and the groups to which it +belongs. +''' from __future__ import absolute_import diff --git a/salt/utils/yamlencoding.py b/salt/utils/yamlencoding.py index 15e35b83da7..2f8ac8fb32e 100644 --- a/salt/utils/yamlencoding.py +++ b/salt/utils/yamlencoding.py @@ -1,4 +1,7 @@ # -*- coding: utf-8 -*- +''' +Functions for adding yaml encoding to the jinja context +''' # Import Python libs from __future__ import absolute_import diff --git a/salt/utils/yamlloader.py b/salt/utils/yamlloader.py index 6fe3a3fa1b8..b439302b776 100644 --- a/salt/utils/yamlloader.py +++ b/salt/utils/yamlloader.py @@ -1,4 +1,8 @@ # -*- coding: utf-8 -*- +''' +Custom YAML loading in Salt +''' + # Import python libs from __future__ import absolute_import import warnings diff --git a/salt/utils/zeromq.py b/salt/utils/zeromq.py index 892b23bbaff..251c05bee24 100644 --- a/salt/utils/zeromq.py +++ b/salt/utils/zeromq.py @@ -1,5 +1,7 @@ # -*- coding: utf-8 -*- - +''' +ZMQ-specific functions +''' # Import Python libs from __future__ import absolute_import