From 49d349f5c32ae25d6f5a36279c8f0c5090242da2 Mon Sep 17 00:00:00 2001 From: Dima Gerasimov Date: Sat, 20 Mar 2021 17:08:16 +0000 Subject: [PATCH] refresh docs --- README.ipynb | 8 +++++++- README.md | 38 +++++++++++++++++++++----------------- 2 files changed, 28 insertions(+), 18 deletions(-) diff --git a/README.ipynb b/README.ipynb index e15233b..4d46465 100644 --- a/README.ipynb +++ b/README.ipynb @@ -71,7 +71,13 @@ }, "outputs": [], "source": [ - "dmd(f'')" + "dmd(f'''\n", + "\n", + "''')" ] }, { diff --git a/README.md b/README.md index 0fb281e..1f08378 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,8 @@ - + # 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,17 +157,17 @@ 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. @@ -171,7 +175,7 @@ Some useful (but optional) arguments of `@cachew` decorator: 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.