Created Nox settings TOML file. Automatic conversion of old settings.…

… Added an option to select a different Nox environment directory.

.gitignore

@@ -1,5 +1,6 @@
 ### Project ###
 noxenv.txt
+noxsettings.toml
 
 ### Python ###
 *.pyc

CONTRIBUTING.rst

@@ -90,21 +90,25 @@ Steps without :bash:`sudo` access (e.g. on a cluster):
 #. Install the project, dependencies and extras: :bash:`poetry install --with test,docs -E cuda -E opencl -E hip`, leaving out :bash:`-E cuda`, :bash:`-E opencl` or :bash:`-E hip` if this does not apply on your system. To go all-out, use :bash:`--all-extras`.
     * If you run into "keyring" or other seemingly weird issues, this is a known issue with Poetry on some systems. Do: :bash:`pip install keyring`, :bash:`python3 -m keyring --disable`.
     * Depending on the environment, it may be necessary or convenient to install extra packages such as :bash:`cupy-cuda11x` / :bash:`cupy-cuda12x`, and :bash:`cuda-python`. These are currently not defined as dependencies for kernel-tuner, but can be part of tests.
+    * Verify that your development environment has no missing installs or updates with :bash:`poetry install --sync --dry-run --with test`. 
 #. Check if the environment is setup correctly by running :bash:`pytest`. All tests should pass, except if you're not on a GPU node, or one or more extras has been left out in the previous step, then these tests will skip gracefully.
-#. Set Nox to use the correct backend:
-    * If you used Mamba in step 2: :bash:`echo "mamba" > noxenv.txt`.
-    * If you used Miniconda or Anaconda in step 2: :bash:`echo "conda" > noxenv.txt`.
-    * If you alternatively set up with Venv: :bash:`echo "venv" > noxenv.txt`.
-    * If you set up with Virtualenv, do not create this file, as this is already the default.
-    * Be sure to adjust or remove this file when changing backends.
+#. Set Nox to use the correct backend and location:
+    * Run :bash:`conda -- create-settings-file` to automatically create a settings file. 
+    * In this settings file :bash:`noxsettings.toml`, change the :bash:`venvbackend`:
+        * If you used Mamba in step 2, to :bash:`mamba`.
+        * If you used Miniconda or Anaconda in step 2, to :bash:`conda`.
+        * If you used Venv in step 2, to :bash:`venv`.
+        * If you used Virtualenv in step 2, this is already the default.
+    * Be sure to adjust this when changing backends.
+    * The settings file also has :bash:`envdir`, which allows you to `change the directory Nox caches environments in<https://nox.thea.codes/en/stable/usage.html#opt-envdir>`_, particularly helpful if you have a diskquota on your user directory. 
 #. [Optional] Run the tests on Nox as described below.
 
 
 Running tests
 -------------
 To run the tests you can use :bash:`nox` (to run against all supported Python versions in isolated environments) and :bash:`pytest` (to run against the local Python version, see below) in the top-level directory.
 For full coverage, make Nox use the additional tests (such as cupy and cuda-python) with :bash:`nox -- additional-tests`.
-The Nox isolated environments can take up to 1 gigabyte in size, so users tight on diskspace can run :bash:`nox` with the :bash:`small-disk` option. This removes the other environment caches before each session is ran (note that this will take longer to run).
+The Nox isolated environments can take up to 1 gigabyte in size, so users tight on diskspace can run :bash:`nox` with the :bash:`small-disk` option. This removes the other environment caches before each session is ran (note that this will take longer to run). A better option would be to change the location environments are stored in with :bash:`envdir` in the :bash:`noxsettings.toml` file. 
 Please note that the command-line options can be combined, e.g. :bash:`nox -- additional-tests skip-hip small-disk`. 
 If you do not have fully compatible hardware or environment, you can use the following options:
 * :bash:`nox -- skip-cuda` to skip tests involving CUDA.

noxfile.py

@@ -17,25 +17,57 @@
 python_versions_to_test = ["3.8", "3.9", "3.10", "3.11"]
 nox.options.stop_on_first_error = True
 nox.options.error_on_missing_interpreters = True
+nox.options.default_venv_backend = 'virtualenv'
 
-# set the default environment from the 'noxenv' file, if it exists
-environment_file_path = Path("./noxenv.txt")
-if environment_file_path.exists():
-    env_values = ('none', 'virtualenv', 'conda', 'mamba', 'venv')  # from https://nox.thea.codes/en/stable/usage.html#changing-the-sessions-default-backend
-    environment = environment_file_path.read_text()
-    assert isinstance(environment, str), "File 'noxenv.txt' does not contain text"
-    environment = environment.strip()
-    assert environment in env_values, f"File 'noxenv.txt' contains {environment}, must be one of {','.join(env_values)}"
-    nox.options.default_venv_backend = environment
+# workspace level settings
+settings_file_path = Path("./noxsettings.toml")
+venvbackend_values = ('none', 'virtualenv', 'conda', 'mamba', 'venv')  # from https://nox.thea.codes/en/stable/usage.html#changing-the-sessions-default-backend
 
-
-# @session
+@session    # to only run on the current python interpreter
+def create_settings(session: Session) -> None:
+    """One-time creation of noxsettings.toml."""
+    if session.posargs:
+        # check if the trigger argument was used
+        arg_trigger = any(arg.lower() == "create-settings-file" for arg in session.posargs)
+    # create settings file if the trigger is used or old settings exist
+    noxenv_file_path = Path("./noxenv.txt")
+    if arg_trigger or (noxenv_file_path.exists() and not settings_file_path.exists()):
+        # default values
+        venvbackend = nox.options.default_venv_backend
+        envdir = ""
+        # conversion from old notenv.txt
+        if noxenv_file_path.exists(): 
+            venvbackend = noxenv_file_path.read_text().strip()
+            noxenv_file_path.unlink()
+        # write the settings
+        assert venvbackend in venvbackend_values, f"{venvbackend=}, must be one of {','.join(venvbackend_values)}"
+        settings = (f'venvbackend = "{venvbackend}"\n'
+                    f'envdir = "{envdir}"\n')
+        settings_file_path.write_text(settings)
+        # exit to make sure the user checks the settings are correct
+        if arg_trigger:
+            session.warn(f"Settings file '{settings_file_path}' created, exiting. Please check settings are correct before running Nox again.")
+            exit(1)
+
+# obtain workspace level settings from the 'noxsettings.toml' file
+if settings_file_path.exists():
+    with settings_file_path.open(mode="rb") as fp:
+        import tomli
+        nox_settings = tomli.load(fp)
+        venvbackend = nox_settings['venvbackend']
+        envdir = nox_settings['envdir']
+        assert venvbackend in venvbackend_values, f"File '{settings_file_path}' has {venvbackend=}, must be one of {','.join(venvbackend_values)}"
+        nox.options.default_venv_backend = venvbackend
+        if envdir is not None and len(envdir) > 0:
+            nox.options.envdir = envdir
+
+# @session    # to only run on the current python interpreter
 # def lint(session: Session) -> None:
 #     """Ensure the code is formatted as expected."""
 #     session.install("ruff")
 #     session.run("ruff", "--output-format=github", "--config=pyproject.toml", ".")
 
-@session
+@session    # to only run on the current python interpreter
 def check_poetry(session: Session) -> None:
     """Check whether Poetry is correctly configured."""
     session.run("poetry", "check", "--no-interaction", external=True)