Untrack stale docs/ tree; make README examples real

README.md

@@ -1,75 +1,57 @@
-
 # focal
 Data Access Objects for local files.
 
+`focal` re-exports the file-system stores of [`dol`](https://github.com/i2mint/dol) (`Files`, `TextFiles`, `PickleFiles`, ...) and adds `multi_extension_wrap`, which serializes by file extension.
+
 # Examples
 
-## quick store
+The examples below run as doctests (`pytest tests/test_readme.py`).
+
+## a dict-like view of a folder
 
 ```pydocstring
->>> from py2store import QuickStore
+>>> import os, tempfile
+>>> from focal import Files, TextFiles
 >>>
->>> store = QuickStore()  # will print what (tmp) rootdir it is choosing
->>> # Write something and then read it out again
->>> store['foo'] = 'baz'
->>> 'foo' in store  # do you have the key 'foo' in your store?
+>>> rootdir = tempfile.mkdtemp()
+>>> store = Files(rootdir)  # keys are relative paths, values are bytes
+>>> store['foo'] = b'baz'
+>>> 'foo' in store
 True
->>> store['foo']  # what is the value for 'foo'?
+>>> store['foo']
+b'baz'
+>>> os.listdir(rootdir)  # it is a real file
+['foo']
+>>> texts = TextFiles(rootdir)  # same folder, values are str
+>>> texts['foo']
 'baz'
->>>
->>> # Okay, it behaves like a dict, but go have a look in your file system,  
->>> # and see that there is now a file in the rootdir, named 'foo'!
->>> 
->>> # Write something more complicated
->>> store['hello/world'] = [1, 'flew', {'over': 'a', "cuckoo's": map}]
->>> stored_val = store['hello/world']
->>> stored_val == [1, 'flew', {'over': 'a', "cuckoo's": map}]  # was it retrieved correctly?
-True
->>>
->>> # how many items do you have now?
->>> assert len(store) >= 2  # can't be sure there were no elements before, so can't assert == 2
->>> 
->>> # delete the stuff you've written
 >>> del store['foo']
->>> del store['hello/world']
-```
 
-## iterate over files
-
-```pydocstring
->>> import os
->>> filepath = __file__  # path to this module
->>> dirpath = os.path.dirname(__file__)  # path of the directory where I (the module file) am
->>> s = FileCollection(dirpath, max_levels=0)
->>>
->>> files_in_this_dir = list(s)
->>> filepath in files_in_this_dir
-True
 ```
-##  bytes contents of the file
+
+## bytes contents of a file, and key validation
 
 ```pydocstring
->>> import os
->>> filepath = __file__
->>> dirpath = os.path.dirname(__file__)  # path of the directory where I (the module file) am
->>> s = FileBytesReader(dirpath, max_levels=0)
->>>
->>> ####### Get the first 9 characters (as bytes) of this module #####################
->>> s[filepath][:9]
-b'import os'
+>>> import os, tempfile
+>>> from focal import Files
 >>>
->>> ####### Test key validation #####################
->>> s['not_a_valid_key']  # this key is not valid since not under the dirpath folder
+>>> rootdir = tempfile.mkdtemp()
+>>> s = Files(rootdir)
+>>> s['hello.txt'] = b'import os'
+>>> s['hello.txt'][:6]
+b'import'
+>>> s['../escape']  # keys outside the root folder are refused
 Traceback (most recent call last):
     ...
-filesys.KeyValidationError: 'Key not valid (usually because does not exist or access not permitted): not_a_valid_key'
->>>
->>> ####### Test further exceptions (that should be wrapped in KeyError) #####################
->>> # this key is valid, since under dirpath, but the file itself doesn't exist (hopefully for this test)
->>> non_existing_file = os.path.join(dirpath, 'non_existing_file')
+dol.filesys.KeyValidationError: ...
 >>> try:
-...     s[non_existing_file]
+...     s['no_such_file']
 ... except KeyError:
 ...     print("KeyError (not FileNotFoundError) was raised.")
 KeyError (not FileNotFoundError) was raised.
+
 ```
+
+## serialize by extension
+
+See `focal.extension_store.multi_extension_wrap`.