Add top-level docstrings to a bunch of salt.utils modules which are m…

…issing them
saltstack · Oct 16, 2017 · 473fbb1 · 473fbb1
1 parent 413de95
commit 473fbb1
Show file tree

Hide file tree

Showing 29 changed files with 100 additions and 21 deletions.
diff --git 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,15 +111,18 @@ 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
     import salt.state
     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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -1,5 +1,7 @@
 # -*- coding: utf-8 -*-
-
+'''
+ZMQ-specific functions
+'''
 # Import Python libs
 from __future__ import absolute_import