Clarify/improve docs around leases and lease reacquisition.

diff --git a/zookeeper.py b/zookeeper.py
index 9decfef82a0961fbda0c5f1f0689b639bebe276d..480ce1a041497abfaedd6f6a159060b57ec484da 100644 (file)
--- a/zookeeper.py
+++ b/zookeeper.py
@@ -13,7 +13,7 @@ import os
 import platform
 import sys
 import threading
-from typing import Callable, Optional
+from typing import Any, Callable, Optional
 
 from kazoo.client import KazooClient
 from kazoo.protocol.states import KazooState
@@ -43,6 +43,16 @@ def obtain_lease(
     before invoking a function or skip invoking the function if the
     lease cannot be obtained.
 
+    There is no method of releasing a lease manually provided on
+    the Kazoo public lease API.  Therefore, letting the lease expire
+    is the only mechanism by which it becomes re-acquirable at this
+    time.  Thus, due consideration is in order when choosing the
+    initial duration.
+
+    According to Kazoo docs, "The client may renew the lease without
+    losing it by obtaining a new lease with the same path (lease_id)
+    and same identity (contender_id)."
+
     Args:
         lease_id: string identifying the lease to obtain
         contender_id: string identifying who's attempting to obtain
@@ -69,7 +79,7 @@ def obtain_lease(
 
     def wrapper(func: Callable) -> Callable:
         @functools.wraps(func)
-        def wrapper2(*args, **kwargs):
+        def wrapper2(*args, **kwargs) -> Optional[Any]:
             zk = KazooClient(
                 hosts=scott_secrets.ZOOKEEPER_NODES,
                 use_ssl=True,
@@ -102,6 +112,7 @@ def obtain_lease(
                 if also_pass_lease:
                     args = (*args, lease)
                 ret = func(*args, *kwargs)
+                # Release the lease?
             else:
                 logger.debug(
                     'Failed to obtain %s for contender %s, doing nothing more.',