code-smell test changes

* Create get_exception and wildcard import code-smell tests
* Add more detail to boilerplate and no-basestring descriptions
* Remove the no-list-cmp test as the pylint undefined-variable test covers it

docs/docsite/rst/dev_guide/testing/sanity/boilerplate.rst

@@ -1,11 +1,10 @@
 Sanity Tests » boilerplate
 ==========================
 
-Most Python files other than those under ``lib/ansible/modules/`` should include the following boilerplate:
+Most Python files should include the following boilerplate:
 
 .. code-block:: python
 
     from __future__ import (absolute_import, division, print_function)
-
     __metaclass__ = type
 

docs/docsite/rst/dev_guide/testing/sanity/no-basestring.rst

@@ -1,4 +1,11 @@
 Sanity Tests » no-basestring
 ============================
 
-Do not use ``isinstance(s, basestring)``.
+Do not use ``isinstance(s, basestring)`` as basestring has been removed in
+Python3.  You can import ``string_types``, ``binary_type``, or ``text_type``
+from ``ansible.module_utils.six`` and then use ``isinstance(s, string_types)``
+or ``isinstance(s, (binary_type, text_type))`` instead.
+
+If this is part of code to convert a string to a particular type,
+``ansible.module_utils._text`` contains several functions that may be even
+better for you: ``to_text``, ``to_bytes``, and ``to_native``.

docs/docsite/rst/dev_guide/testing/sanity/no-get-exception.rst

@@ -0,0 +1,28 @@
+Sanity Tests » no-get-exception
+===============================
+
+We created a function, ``ansible.module_utils.pycompat24.get_exception`` to
+help retrieve exceptions in a manner compatible with Python-2.4 through
+Python-3.6.  We no longer support Python-2.4 and Python-2.5 so this is
+extraneous and we want to deprecate the function.  Porting code should look
+something like this:
+
+.. code-block:: python
+
+    # Unfixed code:
+    try:
+        raise IOError('test')
+    except IOError:
+        e = get_excetion()
+        do_something(e)
+    except:
+        e = get_exception()
+        do_something_else(e)
+
+    # After fixing:
+    try:
+        raise IOError('test')
+    except IOErrors as e:
+        do_something(e)
+    except Exception as e:
+        do_something_else(e)

docs/docsite/rst/dev_guide/testing/sanity/no-list-cmp.rst

@@ -1,8 +0,0 @@
-Sanity Tests » no-list-cmp
-==========================
-
-The ``cmp`` function has been removed in Python 3.
-
-See `When sorting, use key instead of cmp`_.
-
-.. _When sorting, use key instead of cmp: http://python3porting.com/preparing.html#when-sorting-use-key-instead-of-cmp

docs/docsite/rst/dev_guide/testing/sanity/no-wildcard-import.rst

@@ -0,0 +1,29 @@
+Sanity Tests » no-wildcard-import
+=================================
+
+Using :code:`import *` is a bad habit which pollutes your namespace, hinders
+debugging, and interferes with static analysis of code.  For those reasons, we
+do want to limit the use of :code:`import *` in the ansible code.  Change our
+code to import the specific names that you need instead.
+
+Examples of unfixed code:
+
+.. code-block:: python
+
+    from ansible.module_utils.six import *
+    if isinstance(variable, string_types):
+        do_something(variable)
+
+    from ansible.module_utils.basic import *
+    module = AnsibleModule([...])
+
+Examples of fixed code:
+
+.. code-block:: python
+
+    from ansible.module_utils import six
+    if isinstance(variable, six.string_types):
+        do_something(variable)
+
+    from ansible.module_utils.basic import AnsibleModule
+    module = AnsibleModule([...])