Small fixes and docs

teos/gatekeeper.py

@@ -53,7 +53,15 @@ class Gatekeeper:
     perform actions.
 
     Attributes:
+        default_slots (:obj:`int`): the number of slots assigned to a user subscription.
+        default_subscription_duration (:obj:`int`): the expiry assigned to a user subscription.
+        expiry_delta (:obj:`int`): the grace period given to the user to renew their subscription.
+        block_processor (:obj:`BlockProcessor <teos.block_processor.BlockProcessor>`): a ``BlockProcessor`` instance to
+            get block from bitcoind.
+        user_db (:obj:`UserDBM <teos.user_dbm.UserDBM>`): a ``UserDBM`` instance to interact with the database.
         registered_users (:obj:`dict`): a map of user_pk:UserInfo.
+        lock (:obj:`Lock`): a Threading.Lock object to lock access to the Gatekeeper on updates.
+
     """
 
     def __init__(self, user_db, block_processor, default_slots, default_subscription_duration, expiry_delta):
@@ -75,12 +83,15 @@ class Gatekeeper:
             user_pk(:obj:`str`): the public key that identifies the user (33-bytes hex str).
 
         Returns:
-            :obj:`tuple`: a tuple with the number of available slots in the user subscription and the subscription end
-            time (in absolute block height).
+            :obj:`tuple`: a tuple with the number of available slots in the user subscription and the subscription
+            expiry (in absolute block height).
+
+        Raises:
+            :obj:`InvalidParameter`: if the user_pk does not match the expected format.
         """
 
         if not is_compressed_pk(user_pk):
-            raise ValueError("Provided public key does not match expected format (33-byte hex string)")
+            raise InvalidParameter("Provided public key does not match expected format (33-byte hex string)")
 
         if user_pk not in self.registered_users:
             self.registered_users[user_pk] = UserInfo(
@@ -125,11 +136,33 @@ class Gatekeeper:
             raise AuthenticationFailure("Wrong message or signature.")
 
     def update_available_slots(self, user_id, new_appointment, old_appointment=None):
+        """
+        Updates (add/removes) slots from a user subscription.
+
+        Slots are removed if a new subscription is given, or an update is given with a new subscription bigger than the
+        old one.
+
+        Slots are added if an update is given but the new appointment is smaller than the old one.
+
+        Args:
+            user_id(:obj:`str`): the public key that identifies the user (33-bytes hex str).
+            new_appointment (:obj:`ExtendedAppointment <teos.extended_appointment.ExtendedAppointment>`): the new
+                appointment the user is requesting to add.
+            old_appointment (:obj:`ExtendedAppointment <teos.extended_appointment.ExtendedAppointment>`): the old
+                appointment the user wants to replace. Optional.
+
+        Returns:
+            :obj:`int`: the number of remaining appointment slots.
+
+        Raises:
+            :obj:`NotEnoughSlots`: If the user does not have enough slots to fill.
+        """
+
         self.lock.acquire()
         if old_appointment:
             # For updates the difference between the existing appointment and the update is computed.
-            used_slots = ceil(new_appointment.get("size") / ENCRYPTED_BLOB_MAX_SIZE_HEX)
-            required_slots = ceil(old_appointment.get("size") / ENCRYPTED_BLOB_MAX_SIZE_HEX) - used_slots
+            used_slots = ceil(old_appointment.get("size") / ENCRYPTED_BLOB_MAX_SIZE_HEX)
+            required_slots = ceil(new_appointment.get("size") / ENCRYPTED_BLOB_MAX_SIZE_HEX) - used_slots
         else:
             # For regular appointments 1 slot is reserved per ENCRYPTED_BLOB_MAX_SIZE_HEX block.
             required_slots = ceil(new_appointment.get("size") / ENCRYPTED_BLOB_MAX_SIZE_HEX)
@@ -145,8 +178,19 @@ class Gatekeeper:
         self.lock.release()
         return self.registered_users.get(user_id).available_slots
 
-    def get_expiring_appointments(self, block_height):
-        expiring_appointments = []
+    def get_expired_appointments(self, block_height):
+        """
+        Gets a list of appointments that are expiring at a given block height.
+
+        Args:
+            block_height: the block height that wants to be checked.
+
+        Returns:
+            :obj:`list`: a list of appointment uuids that will expire at ``block_height``.
+        """
+        expired_appointments = []
         for user_id, user_info in self.registered_users.items():
-            if block_height > user_info.subscription_expiry + self.expiry_delta:
-                expiring_appointments.extend(user_info.appointments)
+            if block_height == user_info.subscription_expiry + self.expiry_delta:
+                expired_appointments.extend(user_info.appointments)
+
+        return expired_appointments