Add documentation

CHANGELOG.txt

@@ -1,3 +1,6 @@
+0.2.0:
+- Added automatic auto-updater for updating built-in blacklists.
+
 0.1.12:
 - Blacklist/whitelist domains checking is now independent of regex checking.
 

README.rst

@@ -7,7 +7,7 @@
 py3-validate-email
 ============================
 
-py3-validate-email is a package for Python that check if an email is valid, properly formatted and really exists.
+py3-validate-email is a package for Python that check if an email is valid, not blacklisted, properly formatted and really exists.
 
 This module is for Python 3.6 and above!
 
@@ -41,6 +41,10 @@ Basic usage::
 
 :code:`use_blacklist`: use the blacklist of domains downloaded from https://github.com/martenson/disposable-email-domains
 
+Auto-updater
+============================
+The package contains an auto-updater for downloading and updating the built-in blacklist.txt. It will run on each module load (and installation), but will try to update the content if the file is older than 5 days, and if the content is not the same that's already downloaded.
+
 TODOs and BUGS
 ============================
 See: https://github.com/karolyi/py3-validate-email/issues

validate_email/updater.py

@@ -82,6 +82,8 @@ class BlacklistUpdater(object):
 
     def process(self, force: bool = False):
         'Start optionally updating the blacklist.txt file.'
+        # Locking for avoiding multi-process update on multi-process
+        # startup
         with open(self._lock_file_path) as fd:
             try:
                 flock(fd, LOCK_EX)