Document insta-science & fix Windows cache location. (#15)

python/CHANGES.md

@@ -1,5 +1,9 @@
 # insta-science
 
+## 0.4.1
+
+Fix cache location on Windows and document `insta-science` configuration.
+
 ## 0.4.0
 
 Flesh out the `insta-science-util` script adding support for downloading `science` executables for

python/README.md

@@ -18,6 +18,36 @@ bootstrapping `science` for use in Python project easier:
 This project is under active early development and APIs and configuration are likely to change
 rapidly in breaking ways until the 1.0 release.
 
+## Configuration
+
+By default, `insta-science` downloads the latest science binary release appropriate for the current
+platform from the `science` [GitHub Releases](https://github.com/a-scie/lift/releases) and caches it
+before executing for the 1st time. You can control aspects of this process using the
+`[tool.insta-science]` table in your `pyproject.toml` file. Available configuration options are
+detailed below:
+
+| Option             | Default                                   | `pyproject.toml` entry                  | Environment Variable  |
+|--------------------|-------------------------------------------|-----------------------------------------|-----------------------|
+| `science` version  | latest                                    | [tool.insta-science.science] `version`  |                       |
+| `science` Base URL | https://github.com/a-scie/lift/releases   | [tool.insta-science.science] `base-url` |                       |
+| Cache directory    | Unix:    `~/.cache/insta-science`         | [tool.insta-science] `cache`            | `INSTA_SCIENCE_CACHE` |
+|                    | Mac:     `~/Library/Caches/insta-science` |                                         |                       |
+|                    | Windows: `~\AppData\Local\insta-science`  |                                         |                       |
+
+## Offline Use
+
+There is partial support for offline or firewalled `science` use with `insta-science`. You can seed
+a repository of science binaries by using the `insta-science-util download` command to download
+`science` binaries for one or more versions and one or more target platforms. The directory you
+download these binaries to will have the appropriate structure for `insta-science` to use if you
+serve up that directory using your method of choice at the configured base url.
+
+Full offline use requires similar support in `science` for downloading offline copies of the
+[`scie-jump` binaries](https://github.com/a-scie/jump/releases), [`ptex` binaries](
+https://github.com/a-scie/ptex/releases) and interpreter provider provided archives; e.g.
+[PythonBuildStandalone](https://science.scie.app/_/providers/PythonBuildStandalone.html)
+distributions. That support is tracked in [science issue #114](https://github.com/a-scie/lift/issues/114).
+
 ## Development
 
 Development uses [`uv`](https://docs.astral.sh/uv/getting-started/installation/). Install as you

python/insta_science/_internal/cache.py

@@ -108,6 +108,8 @@ def usage(self) -> DiskUsage:
 
 DOWNLOAD_CACHE = DownloadCache(
     base_dir=Path(
-        os.environ.get("INSTA_SCIENCE_CACHE", appdirs.user_cache_dir(appname="insta-science"))
+        os.environ.get(
+            "INSTA_SCIENCE_CACHE", appdirs.user_cache_dir(appname="insta-science", appauthor=False)
+        )
     )
 )

python/insta_science/version.py

@@ -1,4 +1,4 @@
 # Copyright 2024 Science project contributors.
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"