From: Scott Gasch <scott@gasch.org>
Date: Tue, 23 Aug 2022 16:59:49 +0000 (-0700)
Subject: Improve docs.
X-Git-Url: https://wannabe.guru.org/gitweb/?a=commitdiff_plain;h=f9e0d471e6d57b62cdc21a904ae48a2a43331bec;p=python_utils.git

Improve docs.
---

diff --git a/zookeeper.py b/zookeeper.py
index 39730fa..2b50059 100644
--- a/zookeeper.py
+++ b/zookeeper.py
@@ -57,7 +57,6 @@ class RenewableReleasableLease(NonBlockingLease):
     expired or released lease by calling renew.  Go create a new lease
     object at that point.  Finally, note that when you renew the lease
     it will evaluate to False briefly as it is reobtained.
-
     """
 
     def __init__(
@@ -75,7 +74,12 @@ class RenewableReleasableLease(NonBlockingLease):
         self.utcnow = utcnow
 
     def release(self) -> bool:
-        """Release the lease, if it's presently being held."""
+        """Release the lease, if it's presently being held.
+
+        Returns:
+            True if the lease was successfully released,
+            False otherwise.
+        """
         self.client.ensure_path(self.path)
         holder_path = self.path + "/lease_holder"
         lock = self.client.Lock(self.path, self.identifier)
@@ -102,6 +106,19 @@ class RenewableReleasableLease(NonBlockingLease):
         return False
 
     def try_renew(self, duration: datetime.timedelta) -> bool:
+        """Attempt to renew a lease that is currently held.  Note that
+        this will cause self to evaluate to False briefly as the lease
+        is renewed.
+
+        Args:
+            duration: the amount of additional time to add to the
+                      current lease expiration.
+
+        Returns:
+            True if the lease was successfully renewed,
+            False otherwise.
+        """
+
         if not self.obtained:
             return False
         self.obtained = False
@@ -124,6 +141,11 @@ class RenewableReleasableLease(NonBlockingLease):
         return False
 
     def __bool__(self):
+        """Note that this implementation differs from that of the base
+        class in that it probes zookeeper to ensure that the lease is
+        not yet expired and is therefore more expensive.
+        """
+
         if not self.obtained:
             return False
         lock = self.client.Lock(self.path, self.identifier)