Improve the documentation a little.
David Blume

David Blume commited on 2016-09-09 10:52:19
Showing 3 changed files, with 45 additions and 12 deletions.

... ...
@@ -0,0 +1,21 @@
1
+The MIT License (MIT)
2
+
3
+Copyright (c) 2016 David Blume
4
+
5
+Permission is hereby granted, free of charge, to any person obtaining a copy 
6
+of this software and associated documentation files (the "Software"), to deal 
7
+in the Software without restriction, including without limitation the rights
8
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
9
+copies of the Software, and to permit persons to whom the Software is 
10
+furnished to do so, subject to the following conditions:
11
+
12
+The above copyright notice and this permission notice shall be included in all 
13
+copies or substantial portions of the Software.
14
+
15
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
16
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
17
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
18
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
19
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+SOFTWARE.
... ...
@@ -1,4 +1,4 @@
1
-# kvs
1
+# Key Value Store
2 2
 
3 3
 kvs is a rudimentary key/value store written in Python.
4 4
 
... ...
@@ -15,18 +15,30 @@ If you're me, and you want to contribute to the repo, then you can clone it like
15 15
 
16 16
 # Building it
17 17
 
18
-1. Enable Python pages at your web server.
19
-2. Move auth\_sample.txt to auth.txt.
18
+1. Enable Python pages at your web server. See [How to use Python in the web](https://docs.python.org/2/howto/webservers.html#). My configuration is for Apache, hence the .htaccess file.
19
+2. Move auth\_sample.txt to auth.txt, and replace "yourauthorizationhere" with a passcode you choose.
20
+3. Optional: Use secure HTTP. I reccommend getting a free SSL certificate from [Let's Encrypt](https://letsencrypt.org/).
21
+4. If you don't have the YAML module, pip install pyyaml.
20 22
 
21
-# Is it any good?
23
+# Using it
22 24
 
23
-[Yes](https://news.ycombinator.com/item?id=3067434).
25
+Here is [a live instance that serves an index page](https://kvs.dlma.com/).  You can send a key to get a value like so:
26
+
27
+    https://kvs.dlma.com/?k=1GM35N000010
28
+
29
+Special use case, here's how to get the value for the most-recently updated key of a list of keys. The list could contain any number of keys, but only one value will be returned. 
30
+
31
+    https://kvs.dlma.com/?k=1GM35N000010,1GU44N010910
24 32
 
25
-# To Do
33
+Here's the recipe for a cURL command to store a new value for a key: 
26 34
 
27
-1. Better document it.
28
-2. PEP-8
29
-3. Productize it.
35
+    curl --data "key=value&auth={authorization}" https://{url}
36
+
37
+Here's [the source code for a Roku channel client of such a service](http://git.dlma.com/roku_ip_tagger.git/). 
38
+
39
+# Is it any good?
40
+
41
+[Yes](https://news.ycombinator.com/item?id=3067434).
30 42
 
31 43
 # Licence
32 44
 
... ...
@@ -7,7 +7,7 @@ import datetime
7 7
 import cgi, cgitb
8 8
 import filelock
9 9
 import tempfile
10
-import yaml
10
+import yaml  # You may need to "pip install pyyaml"
11 11
 import texttime
12 12
 
13 13
 cgitb.enable(display=0, logdir="/tmp")
... ...
@@ -15,6 +15,7 @@ store_name = 'store.txt'
15 15
 
16 16
 
17 17
 def read_file(full_pathname):
18
+    """ The file must be a YAML file containing a dict. """
18 19
     store = dict()
19 20
     if os.path.isfile(full_pathname):
20 21
         try:
... ...
@@ -27,7 +28,7 @@ def read_file(full_pathname):
27 28
 
28 29
 
29 30
 def write_file(full_pathname, data):
30
-    ''' See http://david.dlma.com/blog/dads-project-in-the-garage '''
31
+    """ See http://david.dlma.com/blog/dads-project-in-the-garage """
31 32
     try:
32 33
         with filelock.FileLock(full_pathname):
33 34
             with tempfile.NamedTemporaryFile(mode='w',
... ...
@@ -139,7 +140,6 @@ if __name__ == '__main__':
139 140
                         'YY': '(Da)',
140 141
                         '2N': '(Li)',
141 142
                         '1R': '(Ty)',
142
-                        '1R': '(Ty)',
143 143
                         'YU': '(Lf)',
144 144
                         'YP': '(C4)',
145 145
                       }
146 146