Use example files to allow proper git-ignoring

The following files:

* myhosts
* blacklist
* whitelist

can be all be modified by the user for personal usage.
However, git is tracking these files since they exist
in the repository, which makes it difficult to do so
without accidentally pushing one's own customizations.

This commit converts those examples to ".example" files,
which serve as the defaults if one of the files listed
above does not exist.

Closes gh-144.

testUpdateHostsFile.py

@@ -904,44 +904,10 @@ class TestWriteOpeningHeader(BaseMockDir):
         ):
             self.assertNotIn(expected, contents)
 
-    def test_no_preamble(self):
-        # We should not even attempt to read this, as it is a directory.
-        hosts_dir = os.path.join(self.test_dir, "myhosts")
-        os.mkdir(hosts_dir)
-
-        kwargs = dict(extensions="", outputsubfolder="",
-                      numberofrules=5, skipstatichosts=True)
-
-        with self.mock_property("updateHostsFile.BASEDIR_PATH"):
-            updateHostsFile.BASEDIR_PATH = self.test_dir
-            write_opening_header(self.final_file, **kwargs)
-
-        contents = self.final_file.getvalue()
-        contents = contents.decode("UTF-8")
-
-        # Expected contents.
-        for expected in (
-            "# This hosts file is a merged collection",
-            "# with a dash of crowd sourcing via Github",
-            "# Number of unique domains: {count}".format(
-                count=kwargs["numberofrules"]),
-            "Fetch the latest version of this file:",
-            "Project home page: https://github.com/StevenBlack/hosts",
-        ):
-            self.assertIn(expected, contents)
-
-        # Expected non-contents.
-        for expected in (
-            "# Extensions added to this file:",
-            "127.0.0.1 localhost",
-            "127.0.0.1 local",
-            "127.0.0.53",
-            "127.0.1.1",
-        ):
-            self.assertNotIn(expected, contents)
-
-    def test_preamble(self):
+    def _check_preamble(self, check_copy):
         hosts_file = os.path.join(self.test_dir, "myhosts")
+        hosts_file += ".example" if check_copy else ""
+
         with open(hosts_file, "w") as f:
             f.write("peter-piper-picked-a-pepper")
 
@@ -977,6 +943,12 @@ class TestWriteOpeningHeader(BaseMockDir):
         ):
             self.assertNotIn(expected, contents)
 
+    def test_preamble_exists(self):
+        self._check_preamble(True)
+
+    def test_preamble_copy(self):
+        self._check_preamble(False)
+
     def tearDown(self):
         super(TestWriteOpeningHeader, self).tearDown()
         self.final_file.close()

updateHostsFile.py

@@ -641,9 +641,10 @@ def create_initial_file():
             with open(filename, "r") as curFile:
                 write_data(merge_file, curFile.read())
 
-    if os.path.isfile(settings["blacklistfile"]):
-        with open(settings["blacklistfile"], "r") as curFile:
-            write_data(merge_file, curFile.read())
+    maybe_copy_example_file(settings["blacklistfile"])
+
+    with open(settings["blacklistfile"], "r") as curFile:
+        write_data(merge_file, curFile.read())
 
     return merge_file
 
@@ -739,12 +740,13 @@ def remove_dups_and_excl(merge_file, exclusion_regexes, output_file=None):
     """
 
     number_of_rules = settings["numberofrules"]
-    if os.path.isfile(settings["whitelistfile"]):
-        with open(settings["whitelistfile"], "r") as ins:
-            for line in ins:
-                line = line.strip(" \t\n\r")
-                if line and not line.startswith("#"):
-                    settings["exclusions"].append(line)
+    maybe_copy_example_file(settings["whitelistfile"])
+
+    with open(settings["whitelistfile"], "r") as ins:
+        for line in ins:
+            line = line.strip(" \t\n\r")
+            if line and not line.startswith("#"):
+                settings["exclusions"].append(line)
 
     if not os.path.exists(settings["outputpath"]):
         os.makedirs(settings["outputpath"])
@@ -956,10 +958,10 @@ def write_opening_header(final_file, **header_params):
         write_data(final_file, "\n")
 
     preamble = path_join_robust(BASEDIR_PATH, "myhosts")
+    maybe_copy_example_file(preamble)
 
-    if os.path.isfile(preamble):
-        with open(preamble, "r") as f:
-            write_data(final_file, f.read())
+    with open(preamble, "r") as f:
+        write_data(final_file, f.read())
 
     final_file.write(file_contents)
 
@@ -1213,6 +1215,23 @@ def domain_to_idna(line):
 
 
 # Helper Functions
+def maybe_copy_example_file(file_path):
+    """
+    Given a file path, copy over its ".example" if the path doesn't exist.
+
+    If the path does exist, nothing happens in this function.
+
+    Parameters
+    ----------
+    file_path : str
+        The full file path to check.
+    """
+
+    if not os.path.isfile(file_path):
+        example_file_path = file_path + ".example"
+        shutil.copyfile(example_file_path, file_path)
+
+
 def get_file_by_url(url):
     """
     Get a file data located at a particular URL.