From 994b6fc8d4426dd145460283b3c986b32ae63f75 Mon Sep 17 00:00:00 2001 From: Bystroushaak Date: Wed, 4 Nov 2015 14:37:27 +0100 Subject: [PATCH] #7, #12: Added docstrings. --- .../amqp/rest/database/status_handler.py | 52 ++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/src/edeposit/amqp/rest/database/status_handler.py b/src/edeposit/amqp/rest/database/status_handler.py index 0b9db16..8c33c36 100755 --- a/src/edeposit/amqp/rest/database/status_handler.py +++ b/src/edeposit/amqp/rest/database/status_handler.py @@ -127,7 +127,19 @@ def __lt__(self, obj): class StatusHandler(DatabaseHandler): + """ + Database handler for tracking :class:`StatusInfo` and + :class:`StatusMessage` objects sent tru AMQP. + """ def __init__(self, conf_path, project_key): + """ + Constructor. + + Args: + conf_path (str): Path to the ZEO client configuration file. + project_key (str): Project key used to access the StatusHandler's + data in DB dict. + """ super(self.__class__, self).__init__( conf_path=conf_path, project_key=project_key @@ -151,6 +163,13 @@ def log(self, msg): #: TODO: implement pass def register_status_tracking(self, username, rest_id): + """ + Register `username` for tracking states of given `rest_id`. + + Args: + username (str): Name of the user. + rest_id (str): Unique identificator of given REST request. + """ with transaction.manager: # handle id->username mapping self.id_to_username[rest_id] = username @@ -167,6 +186,15 @@ def register_status_tracking(self, username, rest_id): self.status_db[rest_id] = StatusInfo(rest_id=rest_id) def save_status_update(self, rest_id, message, timestamp, pub_url=None): + """ + Save new status `message` to given `rest_id`. + + Args: + rest_id (str): Unique identificator of given REST request. + message (str): Content of the status update. + timestamp (float): Python timestamp format. + pub_url (str, default None): URL of the publication in edeposit. + """ with transaction.manager: status_info_obj = self.status_db.get(rest_id, None) @@ -179,7 +207,14 @@ def save_status_update(self, rest_id, message, timestamp, pub_url=None): status_info_obj.add_message(message, timestamp) - def query_status(self, username, rest_id): + def query_status(self, username, rest_id): # TODO: make username non-required + """ + List all messages stored in given `rest_id` for given `username`. + + Args: + username (str): Name of the user. + rest_id (str): Unique identificator of given REST request. + """ with transaction.manager: status_info_obj = self.status_db.get(rest_id, None) db_username = self.id_to_username.get(rest_id, None) @@ -237,6 +272,14 @@ def query_statuses(self, username): ) def remove_status_info(self, rest_id, username=None): + """ + Stop tracking of given `rest_id`. + + Args: + rest_id (str): Unique identificator of given REST request. + username (str, default None): Name of the user. If not set, the + username will not be checked. + """ with transaction.manager: # check privileges of `username` to access `rest_id` if username: @@ -271,6 +314,13 @@ def remove_status_info(self, rest_id, username=None): del self.username_to_ids[username] def trigger_garbage_collection(self, interval=YEAR/2): + """ + Do a garbage collection run and remove all :class:`StatusInfo` objects + which are stored more than `interval`. + + Args: + interval (int/float): Inteval in seconds. + """ with transaction.manager: garbage_rest_ids = [ status_info.rest_id