commit 42b80dce5c418654bd275c2f11d8fb25d237def8 Author: Matt Traudt sirmatt@ksu.edu Date: Mon Jul 23 13:59:34 2018 -0400
Add docstring for State class --- sbws/util/state.py | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+)
diff --git a/sbws/util/state.py b/sbws/util/state.py index 85e223c..a13ee13 100644 --- a/sbws/util/state.py +++ b/sbws/util/state.py @@ -4,6 +4,43 @@ import json
class State: + ''' + State allows one to atomically access and update a simple state file on + disk across threads and across processes. + + To put it blunty, due to limited developer time and his inability to + quickly find a way to safely access and update more complex data types + (namely, collections like list, set, and dict), you may only store simple + types of data as enumerated in _ALLOWED_TYPES. Keys must be strings. + + Data is stored as JSON on disk in the provided file file. + + >>> state = State('foo.state') + >>> # state == {} + + >>> state['linux'] = True + >>> # 'foo.state' now exists on disk with the JSON for {'linux': True} + + >>> # We read 'foo.state' from disk in order to get the most up-to-date + >>> # state info. Pretend another process has updated 'linux' to be + >>> # False + >>> state['linux'] + >>> # returns False + + >>> # Pretend another process has added the user's age to the state file. + >>> # As before, we read the state file from disk for the most + >>> # up-to-date info. + >>> state['age'] + >>> # Returns 14 + + >>> # We now set their name. We read the state file first, set the option, + >>> # and then write it out. + >>> state['name'] = 'John' + + >>> # We can do many of the same things with a State object as with a dict + >>> for key in state: print(key) + >>> # Prints 'linux', 'age', and 'name' + ''' _ALLOWED_TYPES = (int, float, str, bool, type(None))
def __init__(self, fname):