Expand docs; add simple doctest

csppfetch/exclusivelockfile.py

@@ -5,24 +5,31 @@ import logging
 class ExclusiveLockFile:
     """ Lock a temporary file created for the purpose.
 
-    Use with "with":
+    Intended to be used in a "with" block as a context manager.
         
-    with ExclusiveLockFile("/tmp/my-lock"):
-        do_stuff()
+    The file will be created if it doesn't exist. It will be deleted when the
+    block exits! The filename should not be a directory.
 
-    The file will be created if it doesn't exist. It will be
-    deleted when the block exits!
-
-    If multiple processes try to lock the same file, the first
-    to succeed will delete it when done. That means that a process
-    starting after that point will create _new_ file and lock that,
-    not sharing the previous one!  This makes it only suitable for
-    VERY specialized purposes (like ensuring only one process 
-    downloads a file, and later processes will immediately bail out
+    If multiple processes try to lock the same file, the first to succeed will
+    delete it when done. That means that a process starting after that point
+    will create _new_ file and lock that, not sharing the previous one!  This
+    makes it only suitable for VERY specialized purposes (like ensuring only
+    one process downloads a file, and later processes will immediately bail out
     if the downloaded file is already preent).
 
+    Be warned that this is implemented using fcntl.lockf which is an ADVISORY
+    lock; only code using fcntl.lockf or similar will resepect it.
+
     WILL create missing directories if necessary, will NOT
     remove them on completion.
+
+    >>> import tempfile
+    >>> with tempfile.TemporaryDirectory() as dir:
+    ...     with ExclusiveLockFile(dir+"/lock"):
+    ...         # In this block, the file f.name is exclusively locked
+    ...         # using fcntl.lockf. (Only code using fcntl.lockf or 
+    ...         # equivalent will respect this!)
+    ...         pass
     """
     def __init__(self, filename):
         self.filename = filename