feat: cache remote styles to avoid HTTP requests (#312)

* feat: option to cache styles forever, never and with a time unit
* test: fixture: project with a remote style (loaded from a URL)
* feat: read cache config from [tool.nitpick]cache
* feat: default cache is 1 hour
* test: cache option with pytest instead of doctest
* docs: document cache options and default

.bumpversion.cfg

@@ -11,19 +11,19 @@ replace = {new_version}
 search = version = "{current_version}"
 replace = version = "{new_version}"
 
-[bumpversion:file:docs/examples.rst]
+[bumpversion:file:docs/configuration.rst]
 search = {current_version}
 replace = {new_version}
 
-[bumpversion:file:docs/quickstart.rst]
+[bumpversion:file:docs/examples.rst]
 search = {current_version}
 replace = {new_version}
 
-[bumpversion:file:docs/targets.rst]
+[bumpversion:file:docs/quickstart.rst]
 search = {current_version}
 replace = {new_version}
 
-[bumpversion:file:docs/tool_nitpick_section.rst]
+[bumpversion:file:docs/targets.rst]
 search = {current_version}
 replace = {new_version}
 

docs/tool_nitpick_section.rst → docs/configuration.rst

@@ -1,7 +1,7 @@
-.. _tool_nitpick:
+.. _configuration:
 
-The [tool.nitpick] section
-==========================
+Configuration
+=============
 
 :ref:`the-style-file` for your project should be configured in the ``[tool.nitpick]`` section of your ``pyproject.toml`` file.
 
@@ -31,6 +31,72 @@ You can also use the raw URL of a `GitHub Gist <https://gist.github.com>`_:
     [tool.nitpick]
     style = "https://gist.githubusercontent.com/andreoliwa/f4fccf4e3e83a3228e8422c01a48be61/raw/ff3447bddfc5a8665538ddf9c250734e7a38eabb/remote-style.toml"
 
+Cache
+-----
+
+Remote styles can be cached to avoid unnecessary HTTP requests.
+The cache can be configured with the ``cache`` key; see the examples below.
+
+By default, remote styles will be cached for **one hour**.
+This default will also be used if the ``cache`` key has an invalid value.
+
+Expiring after a predefined time
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The cache can be set to expire after a defined time unit.
+Use the format ``cache = "<integer> <time unit>"``.
+*Time unit* can be one of these (plural or singular, it doesn't matter):
+
+- ``minutes`` / ``minute``
+- ``hours`` / ``hour``
+- ``days`` / ``day``
+- ``weeks`` / ``week``
+
+To cache for 15 minutes:
+
+.. code-block:: toml
+
+    [tool.nitpick]
+    style = "https://example.com/remote-style.toml"
+    cache = "15 minutes"
+
+To cache for 1 day:
+
+.. code-block:: toml
+
+    [tool.nitpick]
+    style = "https://example.com/remote-style.toml"
+    cache = "1 day"
+
+Forever
+~~~~~~~
+
+With this option, once the style(s) are cached, they never expire.
+
+.. code-block:: toml
+
+    [tool.nitpick]
+    style = "https://example.com/remote-style.toml"
+    cache = "forever"
+
+Never
+~~~~~
+
+With this option, the cache is never used.
+The remote style file(s) are always looked-up and a HTTP request is always executed.
+
+.. code-block:: toml
+
+    [tool.nitpick]
+    style = "https://example.com/remote-style.toml"
+    cache = "never"
+
+Clearing
+~~~~~~~~
+
+The cache files live in a subdirectory of your project: ``/path/to/your/project/.cache/nitpick/``.
+To clear the cache, simply remove this directory.
+
 Local style
 -----------
 
@@ -41,6 +107,13 @@ Using a file in your home directory:
     [tool.nitpick]
     style = "~/some/path/to/another-style.toml"
 
+Using a relative path from another project in your hard drive:
+
+.. code-block:: toml
+
+    [tool.nitpick]
+    style = "../another-project/another-style.toml"
+
 .. _multiple_styles:
 
 Multiple styles

docs/index.rst

@@ -54,9 +54,9 @@ Useful if you maintain multiple projects and want to use the same configs in all
 
    quickstart
    styles
+   configuration
    examples
    auto_detection
-   tool_nitpick_section
    nitpick_section
    cli
    plugins

docs/styles.rst

@@ -43,14 +43,14 @@ This example style will assert that:
 Configure your own style
 ------------------------
 
-After creating your own TOML_ file with your style, add it to your ``pyproject.toml`` file. See :ref:`the [tool.nitpick] section <tool_nitpick>` for details.
+After creating your own TOML_ file with your style, add it to your ``pyproject.toml`` file. See :ref:`configuration` for details.
 
 You can also check :ref:`some pre-configured examples <examples>`, and copy/paste/change configuration from them.
 
 Default search order for a style
 --------------------------------
 
-1. A file or URL configured in the ``pyproject.toml`` file, ``[tool.nitpick]`` section, ``style`` key, as described in :ref:`tool_nitpick`.
+1. A file or URL configured in the ``pyproject.toml`` file, ``[tool.nitpick]`` section, ``style`` key, as described in :ref:`configuration`.
 
 2. Any `nitpick-style.toml`_ file found in the current directory (the one in which flake8_ runs from) or above.
 

package.json

@@ -31,10 +31,10 @@
             "CHANGELOG.md",
             "README.md",
             "docs/conf.py",
+            "docs/configuration.rst",
             "docs/examples.rst",
             "docs/quickstart.rst",
             "docs/targets.rst",
-            "docs/tool_nitpick_section.rst",
             "nitpick-style.toml",
             "package.json",
             "pyproject.toml",