Merge branch 'main' into paddy/issue-292

.github/ISSUE_TEMPLATE/blank.yaml

@@ -0,0 +1,11 @@
+---
+name: Anything Else
+description:
+  Create a blank issue for anything that does not fit into the other categories
+body:
+  - id: anything_else
+    type: textarea
+    attributes:
+      label: Add your issue here
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -1,2 +1,12 @@
 ---
 blank_issues_enabled: false
+contact_links:
+  - name: Raise a GLASS Discussion
+    url: https://github.com/orgs/glass-dev/discussions
+    about:
+      If you would like to start a discussion with the wider GLASS community
+      about e.g. a design decision or API change, you can use our Discussions
+      page.
+  - name: Join the GLASS Slack
+    url: https://glass-dev.github.io/slack
+    about: We have a public Slack workspace for discussions about the project.

.github/workflows/examples.yml

@@ -23,6 +23,11 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
 
+env:
+  # The "FORCE_COLOR" variable, when set to 1,
+  # tells Nox to colorize itself.
+  FORCE_COLOR: "1"
+
 jobs:
   test-examples:
     name: Test examples
@@ -36,4 +41,7 @@ jobs:
         with:
           python-version: 3.x
           cache: pip
-      - run: pipx run --spec '.[examples]' jupyter execute examples/**/*.ipynb
+      - name: Install nox
+        run: pip install nox
+      - name: Run examples
+        run: nox -s examples

.github/workflows/test.yml

@@ -19,6 +19,11 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
 
+env:
+  # The "FORCE_COLOR" variable, when set to 1,
+  # tells Nox to colorize itself.
+  FORCE_COLOR: "1"
+
 jobs:
   tests:
     name: Tests
@@ -39,8 +44,18 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-      - run: pip install -c .github/test-constraints.txt -e '.[test]'
-      - run: pytest --cov=glass --doctest-plus
+      - name: Install nox and coverage.py
+        run: pip install coverage[toml] nox
+      - name: Run doctests
+        run:
+          nox -s doctests-${{ matrix.python-version.key || matrix.python-version
+          }} --verbose
+      - name: Run tests and generate coverage report
+        run:
+          nox -s coverage-${{ matrix.python-version.key || matrix.python-version
+          }} --verbose
+      - name: Coveralls requires XML report
+        run: coverage xml
       - uses: coverallsapp/github-action@v2
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -53,7 +68,10 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - run: pipx run build
+      - name: Install nox
+        run: pip install nox
+      - name: Build SDist and wheel
+        run: nox -s build --verbose
 
   docs:
     name: Docs
@@ -63,7 +81,10 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - run: |
+      - name: Install dependencies
+        run: |
           sudo apt-get update
           sudo apt-get install pandoc
-      - run: pipx run --spec '.[docs]' sphinx-build -W -b html docs _build/html
+          pip install nox
+      - name: Build docs
+        run: nox -s docs --verbose

.gitignore

@@ -8,3 +8,4 @@ build
 dist
 .env
 .coverage*
+coverage*

.pre-commit-config.yaml

@@ -1,5 +1,6 @@
 ---
 ci:
+  autofix_prs: false
   autoupdate_commit_msg: "MNT: update pre-commit hooks"
   autofix_commit_msg: "STY: pre-commit fixes"
 
@@ -30,49 +31,9 @@ repos:
     hooks:
       - id: yamllint
         args:
-          - >-
-            --config-data={
-              extends: default,
-              rules: {
-                anchors: enable,
-                braces: {
-                  forbid: non-empty
-                },
-                brackets: {
-                  forbid: non-empty
-                },
-                colons: enable,
-                commas: enable,
-                comments: {
-                  min-spaces-from-content: 1
-                },
-                comments-indentation: enable,
-                document-end: disable,
-                document-start: enable,
-                empty-lines: enable,
-                empty-values: disable,
-                float-values: enable,
-                hyphens: enable,
-                indentation: enable,
-                key-duplicates: enable,
-                key-ordering: disable,
-                line-length: enable,
-                new-line-at-end-of-file: enable,
-                new-lines: enable,
-                octal-values: enable,
-                quoted-strings: {
-                  quote-type: double,
-                  required: only-when-needed
-                },
-                trailing-spaces: enable,
-                truthy: {
-                  check-keys: false
-                }
-              }
-            }
           - --strict
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.7
+    rev: v0.6.8
     hooks:
       - id: ruff
       - id: ruff-format
@@ -86,18 +47,10 @@ repos:
     rev: v0.23.1
     hooks:
       - id: toml-sort-fix
-        args:
-          - --all
-          - --in-place
-          - --spaces-indent-inline-array=4
-          - --trailing-comma-inline-array
   - repo: https://github.com/rbubley/mirrors-prettier
     rev: v3.3.3
     hooks:
       - id: prettier
-        args:
-          - --prose-wrap=always
-          - --quote-props=as-needed
   - repo: https://github.com/igorshubovych/markdownlint-cli
     rev: v0.41.0
     hooks:

.prettierrc.yaml

@@ -0,0 +1,3 @@
+---
+proseWrap: always
+quoteProps: as-needed

.yamllint.yaml

@@ -0,0 +1,33 @@
+---
+extends: default
+
+rules:
+  anchors: enable
+  braces:
+    forbid: non-empty
+  brackets:
+    forbid: non-empty
+  colons: enable
+  commas: enable
+  comments:
+    min-spaces-from-content: 1
+  comments-indentation: enable
+  document-end: disable
+  document-start: enable
+  empty-lines: enable
+  empty-values: disable
+  float-values: enable
+  hyphens: enable
+  indentation: enable
+  key-duplicates: enable
+  key-ordering: disable
+  line-length: enable
+  new-line-at-end-of-file: enable
+  new-lines: enable
+  octal-values: enable
+  quoted-strings:
+    quote-type: double
+    required: only-when-needed
+  trailing-spaces: enable
+  truthy:
+    check-keys: false

CONTRIBUTING.md

@@ -138,6 +138,52 @@ long as there have been changes.
 The current version number is automatically inferred from the last release (i.e.
 git tag), subsequent unreleased commits, and local changes, if any.
 
+## Nox
+
+`GLASS` supports running various critical commands using
+[nox](https://github.com/wntrblm/nox) to make them less intimidating for new
+developers. All of these commands (or sessions in the language of `nox`) -
+`lint`, `tests`, `coverage`, `doctests`, `docs`, and `build` - are defined in
+[noxfile.py](https://github.com/glass-dev/glass/main/noxfile.py).
+
+`nox` can be installed via `pip` using -
+
+```bash
+pip install nox
+```
+
+The default sessions (`lint` and `tests`) can be executed using -
+
+```bash
+nox
+```
+
+A particular session (for example `tests`) can be run with `nox` on all
+supported Python versions using -
+
+```bash
+nox -s tests
+```
+
+Only `tests`, `coverage`, and the `doctests` session run on all supported Python
+versions by default.
+
+To specify a particular Python version (for example `3.11`), use the following
+syntax -
+
+```bash
+nox -s tests-3.11
+```
+
+The following command can be used to deploy the docs on `localhost` -
+
+```bash
+nox -s docs -- serve
+```
+
+The `nox` environments created for each type of session on the first run is
+saved under `.nox/` and reused by default.
+
 ## Contributing workflow
 
 Every change to the repository should come out of an issue where the change is

noxfile.py

@@ -0,0 +1,75 @@
+"""Nox config."""
+
+from __future__ import annotations
+
+import nox
+
+# Options to modify nox behaviour
+nox.options.default_venv_backend = "uv|virtualenv"
+nox.options.reuse_existing_virtualenvs = True
+nox.options.sessions = ["lint", "tests"]
+
+ALL_PYTHON = ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+
+@nox.session
+def lint(session: nox.Session) -> None:
+    """Run the linter."""
+    session.install("pre-commit")
+    session.run("pre-commit", "run", "--all-files", *session.posargs)
+
+
+@nox.session(python=ALL_PYTHON)
+def tests(session: nox.Session) -> None:
+    """Run the unit tests."""
+    session.install("-c", ".github/test-constraints.txt", "-e", ".[test]")
+    session.run(
+        "pytest",
+        *session.posargs,
+    )
+
+
+@nox.session(python=ALL_PYTHON)
+def coverage(session: nox.Session) -> None:
+    """Run tests and compute coverage."""
+    session.posargs.append("--cov=glass")
+    tests(session)
+
+
+@nox.session(python=ALL_PYTHON)
+def doctests(session: nox.Session) -> None:
+    """Run the doctests."""
+    session.posargs.append("--doctest-plus")
+    session.posargs.append("glass")
+    tests(session)
+
+
+@nox.session
+def examples(session: nox.Session) -> None:
+    """Run the example notebooks."""
+    session.install("-e", ".[examples]")
+    session.run("jupyter", "execute", "examples/**/*.ipynb", *session.posargs)
+
+
+@nox.session
+def docs(session: nox.Session) -> None:
+    """Build the docs. Pass "serve" to serve."""
+    session.install("-e", ".[docs]")
+    session.chdir("docs")
+    session.run("sphinx-build", "-M", "html", ".", "_build")
+
+    port = 8001
+
+    if session.posargs:
+        if "serve" in session.posargs:
+            print(f"Launching docs at http://localhost:{port}/ - use Ctrl-C to quit")
+            session.run("python", "-m", "http.server", f"{port}", "-d", "_build/html")
+        else:
+            print("Unsupported argument to docs")
+
+
+@nox.session
+def build(session: nox.Session) -> None:
+    """Build an SDist and wheel."""
+    session.install("build")
+    session.run("python", "-m", "build")

pyproject.toml

@@ -141,6 +141,8 @@ lint.per-file-ignores = {"__init__.py" = [
     "T201", # print
 ], "glass*" = [
     "PLR2004", # TODO: magic-value-comparison
+], "noxfile.py" = [
+    "T201", # print
 ], "tests*" = [
     "ANN001", # TODO: missing-type-function-argument
     "ANN201", # TODO: issing-return-type-undocumented-public-function
@@ -159,5 +161,9 @@ lint.select = [
 lint.mccabe.max-complexity = 18
 
 [tool.tomlsort]
+all = true
+in_place = true
+spaces_indent_inline_array = 4
+trailing_comma_inline_array = true
 overrides."project.classifiers".inline_arrays = false
 overrides."tool.ruff.lint.isort.section-order".inline_arrays = false

tests/core/test_algorithm.py

@@ -17,10 +17,21 @@ def test_nnls(rng):
 
     from glass.core.algorithm import nnls as nnls_glass
 
+    # cross-check output with scipy's nnls
+
     a = rng.standard_normal((100, 20))
     b = rng.standard_normal((100,))
 
     x_glass = nnls_glass(a, b)
     x_scipy, _ = nnls_scipy(a, b)
 
     np.testing.assert_allclose(x_glass, x_scipy)
+
+    # check matrix and vector's shape
+
+    with pytest.raises(ValueError, match="input `a` is not a matrix"):
+        nnls_glass(b, a)
+    with pytest.raises(ValueError, match="input `b` is not a vector"):
+        nnls_glass(a, a)
+    with pytest.raises(ValueError, match="the shapes of `a` and `b` do not match"):
+        nnls_glass(a.T, b)