Improve the documentation a little. (c9a9f88) - kvs.git

Improve the documentation a little.

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

LICENSE.txt 0000000..a4726db
README.md 9db9663..b816831
index.py 9138bce..00ed85e

LICENSE.txt

...	...	@@ -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.

README.md

View file @ c9a9f88

@@ -1,4 +1,4 @@
-# kvs
+# Key Value Store
 
 kvs is a rudimentary key/value store written in Python.
 
@@ -15,18 +15,30 @@ If you're me, and you want to contribute to the repo, then you can clone it like
 
 # Building it
 
-1. Enable Python pages at your web server.
-2. Move auth\_sample.txt to auth.txt.
+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.
+2. Move auth\_sample.txt to auth.txt, and replace "yourauthorizationhere" with a passcode you choose.
+3. Optional: Use secure HTTP. I reccommend getting a free SSL certificate from [Let's Encrypt](https://letsencrypt.org/).
+4. If you don't have the YAML module, pip install pyyaml.
 
-# Is it any good?
+# Using it
 
-[Yes](https://news.ycombinator.com/item?id=3067434).
+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:
+
+    https://kvs.dlma.com/?k=1GM35N000010
+
+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. 
+
+    https://kvs.dlma.com/?k=1GM35N000010,1GU44N010910
 
-# To Do
+Here's the recipe for a cURL command to store a new value for a key: 
 
-1. Better document it.
-2. PEP-8
-3. Productize it.
+    curl --data "key=value&auth={authorization}" https://{url}
+
+Here's [the source code for a Roku channel client of such a service](http://git.dlma.com/roku_ip_tagger.git/). 
+
+# Is it any good?
+
+[Yes](https://news.ycombinator.com/item?id=3067434).
 
 # Licence
 

index.py

View file @ c9a9f88

@@ -7,7 +7,7 @@ import datetime
 import cgi, cgitb
 import filelock
 import tempfile
-import yaml
+import yaml  # You may need to "pip install pyyaml"
 import texttime
 
 cgitb.enable(display=0, logdir="/tmp")
@@ -15,6 +15,7 @@ store_name = 'store.txt'
 
 
 def read_file(full_pathname):
+    """ The file must be a YAML file containing a dict. """
     store = dict()
     if os.path.isfile(full_pathname):
         try:
@@ -27,7 +28,7 @@ def read_file(full_pathname):
 
 
 def write_file(full_pathname, data):
-    ''' See http://david.dlma.com/blog/dads-project-in-the-garage '''
+    """ See http://david.dlma.com/blog/dads-project-in-the-garage """
     try:
         with filelock.FileLock(full_pathname):
             with tempfile.NamedTemporaryFile(mode='w',
@@ -139,7 +140,6 @@ if __name__ == '__main__':
                         'YY': '(Da)',
                         '2N': '(Li)',
                         '1R': '(Ty)',
-                        '1R': '(Ty)',
                         'YU': '(Lf)',
                         'YP': '(C4)',
                       }


...	...	@@ -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