From 07750acd2cc8245b48ae5dfa522f2b23b734c02c Mon Sep 17 00:00:00 2001 From: Omer Anson Date: Mon, 28 Aug 2017 12:07:25 +0300 Subject: [PATCH] Update DB API documentation Change-Id: I27caec92d3155a8e5f02a0b848bb4b1f6e254dd2 --- dragonflow/db/db_api.py | 38 +++++++++++++++++++++++++------------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/dragonflow/db/db_api.py b/dragonflow/db/db_api.py index b493d280b..1491a35e3 100644 --- a/dragonflow/db/db_api.py +++ b/dragonflow/db/db_api.py @@ -43,7 +43,9 @@ class DbApi(object): @abc.abstractmethod def delete_table(self, table): - """Delete a table + """Delete a table. Delete all items in the table. + Reading any key from the table without re-creating it should + raise an exception. :param table: table name :type table: string @@ -52,13 +54,17 @@ class DbApi(object): @abc.abstractmethod def get_key(self, table, key, topic=None): - """Get the value of a specific key in a table + """Get the value of a specific key in a table. If the key does not + exist, raise a DBKeyNotFound error. + + topic is an optional value which may be used to optimise the search + for the key. :param table: table name :type table: string :param key: key name :type key: string - :param topic: topic for key + :param topic: optional topic to aid in key lookup :type topic: string :returns: string - the key value :raises DragonflowException.DBKeyNotFound: if key not found @@ -66,7 +72,11 @@ class DbApi(object): @abc.abstractmethod def set_key(self, table, key, value, topic=None): - """Set a specific key in a table with value + """Set a specific key in a table with value. If the key does not + exist, the implementation may either: + 1. Raise a DBLeyNotFound error + 2. Create the key as if create_key was called. + Exactly one of these two option must be implemented :param table: table name :type table: string @@ -74,10 +84,11 @@ class DbApi(object): :type key: string :param value: value to set for the key :type value: string - :param topic: topic for key + :param topic: optional topic to aid in key lookup :type topic: string :returns: None - :raises DragonflowException.DBKeyNotFound: if key not found + :raises DragonflowException.DBKeyNotFound: if key not found, and was + not created """ @abc.abstractmethod @@ -90,20 +101,21 @@ class DbApi(object): :type key: string :param value: value to set for the created key :type value: string - :param topic: topic for key + :param topic: optional topic to aid in key lookup :type topic: string :returns: None """ @abc.abstractmethod def delete_key(self, table, key, topic=None): - """Delete a specific key from a table + """Delete a specific key from a table. If the key does not exist, + raise a DBKeyNotFound error. :param table: table name :type table: string :param key: key name :type key: string - :param topic: topic for key + :param topic: optional topic to aid in key lookup :type topic: string :returns: None :raises DragonflowException.DBKeyNotFound: if key not found @@ -111,26 +123,26 @@ class DbApi(object): @abc.abstractmethod def get_all_entries(self, table, topic=None): - """Returns a list of all table entries values + """Returns a list of all table entries values. If the table does + not exist, or is empty, return an empty list. :param table: table name :type table: string :param topic: get only entries matching this topic :type topic: string :returns: list of values - :raises DragonflowException.DBKeyNotFound: if key not found """ @abc.abstractmethod def get_all_keys(self, table, topic=None): - """Returns a list of all table entries keys + """Returns a list of all table entries keys. If the table does not + exist, or is empty, return an empty list. :param table: table name :type table: string :param topic: get all keys matching this topic :type topic: string :returns: list of keys - :raises DragonflowException.DBKeyNotFound: if key not found """ @abc.abstractmethod