avoid setup warnings when constructing a list of all project sources

Python 2 versions prior to some early 2.7.x release and Python 3 versions prior
to some 3.2.x release had buggy disutils implementations that can result in our
project's source distribution containing some extra unwanted files picked up
from some of our local 'tools/__*' cache folders. Such extra files are then
explicitly excluded by an explicit 'prune' rule in MANIFEST.in.

However, that can cause spurious warnings in case no such local cache folders
exist or no files have been collected from them. This commit works around the
issue in 2 stages:
 1. setup.py always creates one such dummy folder containing a single dummy file
    that is guaranteed to always be included on buggy implementations. This
    avoids the warning on buggy distutils implementations when no extra files
    have been collected.
 2. MANIFEST.in explicitly includes the dummy file created by setup.py. This
    avoids the warning on working distutils implementations which never collect
    any extra files by themselves.

MANIFEST.in

@@ -22,5 +22,20 @@ recursive-include tests *.py
 include tools/*.cmd
 include tools/*.py
 include tools/*.txt
-prune tools/__*  # local cache folders
 recursive-include tools/suds_devel *.py
+
+# Python 2 versions prior to some early 2.7.x release and Python 3 versions
+# prior to some 3.2.x release had buggy disutils implementations that can
+# result in our project's source distribution containing some extra unwanted
+# files picked up from some of our local cache folders. This is a 3-layer fix
+# to work around the problem:
+#   1. We prune those folders just in case some of their content got added by
+#      mistake.
+#   2. An extra include is here to silence distutils warnings in case the used
+#      distutils implementation is not buggy and therefore no extra files have
+#      been added and distutils can not find anything to prune.
+#   3. To make the include actually include an existing file, setup.py
+#      constructs at least one such file to be included with a buggy distutils
+#      implementation.
+include tools/__*/*
+prune tools/__*

setup.py

@@ -117,7 +117,8 @@ if script_folder != current_folder:
 # Import suds_devel module shared between setup & development scripts.
 # -----------------------------------------------------------------------------
 
-sys.path.insert(0, os.path.join(script_folder, "tools"))
+tools_folder = os.path.join(script_folder, "tools")
+sys.path.insert(0, tools_folder)
 import suds_devel
 sys.path.pop(0)
 
@@ -561,6 +562,36 @@ if sys.version_info >= (3,):
             break;
 
 
+# -----------------------------------------------------------------------------
+# Avoid setup warnings when constructing a list of all project sources.
+# -----------------------------------------------------------------------------
+# Part of this workaround implemented and part in the project's MANIFEST.in
+# template. See a related comment in MANIFEST.in for more detailed information.
+
+dummy_tools_folder = os.path.join(tools_folder, "__dummy__")
+dummy_tools_file = os.path.join(dummy_tools_folder, "readme.txt")
+try:
+    if not os.path.isdir(dummy_tools_folder):
+        os.mkdir(dummy_tools_folder)
+    if not os.path.isfile(dummy_tools_file):
+        f = open(dummy_tools_file, "w")
+        try:
+            f.write("""\
+Dummy empty folder added as a part of a patch to silence setup.py warnings when
+determining which files belong to the project. See a related comment in the
+project's MANIFEST.in template for more detailed information.
+
+Both the folder and this file have been generated by the project's setup.py
+script and should not be placed under version control.
+""")
+        finally:
+            f.close()
+except EnvironmentError:
+    # Something went wrong attempting to construct the dummy file. Ah well, we
+    # gave it our best. Continue on with possible spurious warnings.
+    pass
+
+
 # -----------------------------------------------------------------------------
 # Set up project metadata and run the actual setup.
 # -----------------------------------------------------------------------------