shep

Multi-state key stores using bit masks for python3
git clone git://git.defalsify.org/shep.git
Log | Files | Refs | LICENSE

commit 7937cadaef9b9d89dcb2ff489de6bac95929e8bb
parent 5cc0af80d64381084a72be73632f6e4fb8b7ba96
Author: lash <dev@holbrook.no>
Date:   Wed,  9 Feb 2022 17:30:41 +0000

Complete docstrings

Diffstat:
Mshep/error.py | 10++++++++++
Mshep/persist.py | 2+-
Mshep/store/file.py | 67+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------
3 files changed, 72 insertions(+), 7 deletions(-)

diff --git a/shep/error.py b/shep/error.py @@ -1,18 +1,28 @@ class StateExists(Exception): + """Attempt to add state that already exists. + """ pass class StateInvalid(Exception): + """Attempt to operate on or move to a state that does not exist. + """ pass class StateItemExists(Exception): + """A content key attempted added that already exists. + """ pass class StateItemNotFound(Exception): + """A content key attempted read that does not exist. + """ pass class StateCorruptionError(RuntimeError): + """An irrecoverable discrepancy between persisted state and memory state has occurred. + """ pass diff --git a/shep/persist.py b/shep/persist.py @@ -150,7 +150,7 @@ class PersistedState(State): """ k = self.name(state) self.__ensure_store(k) - return self.__stores[k].path(key=key) + return self.__stores[k].path(k=key) def next(self, key=None): diff --git a/shep/store/file.py b/shep/store/file.py @@ -3,13 +3,24 @@ import os class SimpleFileStore: + """Filesystem store of contents for state, with one directory per state. + :param path: Filesystem base path for all state directory + :type path: str + """ def __init__(self, path): self.__path = path os.makedirs(self.__path, exist_ok=True) def add(self, k, contents=None): + """Add a new key and optional contents + + :param k: Content key to add + :type k: str + :param contents: Optional contents to assign for content key + :type contents: any + """ fp = os.path.join(self.__path, k) if contents == None: contents = '' @@ -20,11 +31,25 @@ class SimpleFileStore: def remove(self, k): + """Remove a content key from a state. + + :param k: Content key to remove from the state + :type k: str + :raises FileNotFoundError: Content key does not exist in the state + """ fp = os.path.join(self.__path, k) os.unlink(fp) - + def get(self, k): + """Retrieve the content for the given content key. + + :param k: Content key to retrieve content for + :type k: str + :raises FileNotFoundError: Content key does not exist for the state + :rtype: any + :return: Contents + """ fp = os.path.join(self.__path, k) f = open(fp, 'r') r = f.read() @@ -33,6 +58,11 @@ class SimpleFileStore: def list(self): + """List all content keys persisted for the state. + + :rtype: list of str + :return: Content keys in state + """ files = [] for p in os.listdir(self.__path): fp = os.path.join(self.__path, p) @@ -45,14 +75,28 @@ class SimpleFileStore: return files - def path(self, key=None): - if key == None: + def path(self, k=None): + """Return filesystem path for persisted state or state item. + + :param k: If given, will return filesystem path to specified content key + :type k: str + :rtype: str + :return: File path + """ + if k == None: return self.__path - return os.path.join(self.__path, key) + return os.path.join(self.__path, k) + + def replace(self, k, contents): + """Replace persisted content for persisted content key. - def replace(self, key, contents): - fp = os.path.join(self.__path, key) + :param k: Content key to replace contents for + :type k: str + :param contents: Contents + :type contents: any + """ + fp = os.path.join(self.__path, k) os.stat(fp) f = open(fp, 'w') r = f.write(contents) @@ -60,12 +104,23 @@ class SimpleFileStore: class SimpleFileStoreFactory: + """Provide a method to instantiate SimpleFileStore instances that provide persistence for individual states. + :param path: Filesystem path as base path for states + :type path: str + """ def __init__(self, path): self.__path = path def add(self, k): + """Create a new SimpleFileStore for a state. + + :param k: Identifier for the state + :type k: str + :rtype: SimpleFileStore + :return: A filesystem persistence instance with the given identifier as subdirectory + """ k = str(k) store_path = os.path.join(self.__path, k) return SimpleFileStore(store_path)