refresh docs

README.ipynb

@@ -71,7 +71,13 @@
    },
    "outputs": [],
    "source": [
-    "dmd(f'<!--THIS FILE IS AUTOGENERATED BY README.ipynb. Use generate-readme to update it.-->')"
+    "dmd(f'''\n",
+    "<!--\n",
+    "THIS FILE IS AUTOGENERATED BY README.ipynb.\n",
+    "Ideally you should edit README.ipynb and use 'generate-readme' to produce README.md. \n",
+    "But it's okay to edit README.md too directly if you want to fix something -- I can run generate-readme myself later.\n",
+    "-->\n",
+    "''')"
    ]
   },
   {

README.md

@@ -1,4 +1,8 @@
-<!--THIS FILE IS AUTOGENERATED BY README.ipynb. Use generate-readme to update it.-->
+<!--
+THIS FILE IS AUTOGENERATED BY README.ipynb.
+Ideally you should edit README.ipynb and use 'generate-readme' to produce README.md. 
+But it's okay to edit README.md too directly if you want to fix something -- I can run generate-readme myself later.
+-->
 
 
 # What is Cachew?
@@ -116,10 +120,10 @@ Cachew gives the best of two worlds and makes it both **easy and efficient**. Th
 
 
 # How it works
-Basically, your data objects get [flattened out](src/cachew/__init__.py#L447)
-and python types are mapped [onto sqlite types and back](src/cachew/__init__.py#L517).
+Basically, your data objects get [flattened out](src/cachew/__init__.py#L452)
+and python types are mapped [onto sqlite types and back](src/cachew/__init__.py#L522).
 
-When the function is called, cachew [computes the hash of your function's arguments ](src/cachew/__init__.py:#L839)
+When the function is called, cachew [computes the hash of your function's arguments ](src/cachew/__init__.py:#L841)
 and compares it against the previously stored hash value.
 
 - If they match, it would deserialize and yield whatever is stored in the cache database
@@ -131,18 +135,18 @@ and compares it against the previously stored hash value.
 
 
 
-* automatic schema inference: [1](src/cachew/tests/test_cachew.py#L281), [2](src/cachew/tests/test_cachew.py#L295)
+* automatic schema inference: [1](src/cachew/tests/test_cachew.py#L341), [2](src/cachew/tests/test_cachew.py#L355)
 * supported types:    
 
     * primitive: `str`, `int`, `float`, `bool`, `datetime`, `date`, `dict`, `list`, `Exception`
 
-      See [tests.test_types](src/cachew/tests/test_cachew.py#L561), [tests.test_primitive](src/cachew/tests/test_cachew.py#L608), [tests.test_dates](src/cachew/tests/test_cachew.py#L521)
-    * [Optional](src/cachew/tests/test_cachew.py#L420) types
-    * [Union](src/cachew/tests/test_cachew.py#L678) types
-    * [nested datatypes](src/cachew/tests/test_cachew.py#L337)
-    * [Exceptions](src/cachew/tests/test_cachew.py#L920)
+      See [tests.test_types](src/cachew/tests/test_cachew.py#L621), [tests.test_primitive](src/cachew/tests/test_cachew.py#L668), [tests.test_dates](src/cachew/tests/test_cachew.py#L581)
+    * [Optional](src/cachew/tests/test_cachew.py#L480) types
+    * [Union](src/cachew/tests/test_cachew.py#L738) types
+    * [nested datatypes](src/cachew/tests/test_cachew.py#L397)
+    * [Exceptions](src/cachew/tests/test_cachew.py#L995)
 
-* detects [datatype schema changes](src/cachew/tests/test_cachew.py#L367) and discards old data automatically
+* detects [datatype schema changes](src/cachew/tests/test_cachew.py#L427) and discards old data automatically
 
 
 # Performance
@@ -153,25 +157,25 @@ During reading cache all that happens is reading rows from sqlite and mapping th
 I haven't set up proper benchmarks/performance regressions yet, so don't want to make specific claims, however that would almost certainly make your programm faster if computations take more than several seconds.
 
 
-If you want to experiment for youself, check out [tests.test_many](src/cachew/tests/test_cachew.py#L226)
+If you want to experiment for youself, check out [tests.test_many](src/cachew/tests/test_cachew.py#L286)
 
 
 
 # Using
-See [docstring](src/cachew/__init__.py#L711) for up-to-date documentation on parameters and return types. 
+See [docstring](src/cachew/__init__.py#L713) for up-to-date documentation on parameters and return types. 
 You can also use [extensive unit tests](src/cachew/tests/test_cachew.py) as a reference.
 
 Some useful (but optional) arguments of `@cachew` decorator:
 
-* `cache_path` can be a directory, or a callable that [returns a path](src/cachew/tests/test_cachew.py#L317) and depends on function's arguments.
+* `cache_path` can be a directory, or a callable that [returns a path](src/cachew/tests/test_cachew.py#L377) and depends on function's arguments.
 
    By default, `settings.DEFAULT_CACHEW_DIR` is used.
 
 * `depends_on` is a function which determines whether your inputs have changed, and the cache needs to be invalidated.
 
    By default it just uses string representation of the arguments, you can also specify a custom callable.
 
-   For instance, it can be used to [discard cache](src/cachew/tests/test_cachew.py#L91) if the input file was modified.
+   For instance, it can be used to [discard cache](src/cachew/tests/test_cachew.py#L92) if the input file was modified.
 
 * `cls` is the type that would be serialized.
 
@@ -256,10 +260,10 @@ Now you can use `@mcachew` in place of `@cachew`, and be certain things don't br
 ## Settings
 
 
-[cachew.settings](src/cachew/__init__.py#L61) exposes some parameters that allow you to control `cachew` behaviour:
+[cachew.settings](src/cachew/__init__.py#L64) exposes some parameters that allow you to control `cachew` behaviour:
 - `ENABLE`: set to `False` if you want to disable caching for without removing the decorators (useful for testing and debugging).
    You can also use [cachew.extra.disabled_cachew](src/cachew/__init__.py#L18) context manager to do it temporarily.
-- `DEFAULT_CACHEW_DIR`: override to set a different base directory.
+- `DEFAULT_CACHEW_DIR`: override to set a different base directory. The default is the "user cache directory" (see [appdirs docs](https://github.com/ActiveState/appdirs#some-example-output)).
 - `THROW_ON_ERROR`: by default, cachew is defensive and simply attemps to cause the original function on caching issues.
    Set to `True` to catch errors earlier.