[tor-commits] [sbws/master] Add docstring for State class

[pastly@xxxxxxxxxxxxxx]

commit 42b80dce5c418654bd275c2f11d8fb25d237def8
Author: Matt Traudt <sirmatt@xxxxxxx>
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):



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits