spin 0.8__tar.gz → 0.9__tar.gz

{spin-0.8 → spin-0.9}/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2021--2022, Scientific Python project
+Copyright (c) 2021--2024, Scientific Python project
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

{spin-0.8/spin.egg-info → spin-0.9}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.1
 Name: spin
-Version: 0.8
+Version: 0.9
 Summary: Developer tool for scientific Python libraries
 Maintainer-email: Scientific Python <spin@discuss.scientific-python.org>
 License: BSD 3-Clause License
         
-        Copyright (c) 2021--2022, Scientific Python project
+        Copyright (c) 2021--2024, Scientific Python project
         All rights reserved.
         
         Redistribution and use in source and binary forms, with or without
@@ -53,24 +53,28 @@ License-File: LICENSE
 Requires-Dist: click
 Requires-Dist: tomli; python_version < "3.11"
 Requires-Dist: colorama; platform_system == "Windows"
+Requires-Dist: importlib_metadata>=7
 Provides-Extra: lint
-Requires-Dist: pre-commit==3.5.0; extra == "lint"
+Requires-Dist: pre-commit==3.7.0; extra == "lint"
 Provides-Extra: dev
-Requires-Dist: changelist==0.4; extra == "dev"
+Requires-Dist: changelist==0.5; extra == "dev"
 
 # 💫 Scientific Python INcantations (`spin`)
 
 ## A developer tool for scientific Python libraries
 
 Developers need to memorize a whole bunch of magic command-line incantations.
-And these incantations change from time to time!
-Typically, their lives are made simpler by a Makefile, but Makefiles can be convoluted, are not written in Python, and are hard to extend.
-The rationale behind `spin` is therefore to provide a simple interface for common development tasks.
+These incantations may also change over time.
+Often, Makefiles are used to provide aliases, but Makefiles can be convoluted, are not written in Python, and are hard to extend.
+The goal of `spin` is therefore to provide a simple, user-friendly, extendable interface for common development tasks.
 It comes with a few common build commands out the box, but can easily be customized per project.
 
 As a curiosity: the impetus behind developing the tool was the mass migration of scientific Python libraries (SciPy, scikit-image, and NumPy, etc.) to Meson, after distutils was deprecated.
 When many of the build and installation commands changed, it made sense to abstract away the nuisance of having to re-learn them.
 
+_Note:_ We now have experimental builds for editable installs.
+Most of the Meson commands listed below should work "out of the box" for those.
+
 ## Installation
 
 ```
@@ -152,7 +156,6 @@ Available as `spin.cmds.meson.*`.
   docs     📖 Build Sphinx documentation
   gdb      👾 Execute a Python snippet with GDB
   lldb     👾 Execute a Python snippet with LLDB
-  install  💽 Build and install package using pip.
 ```
 
 ### [Build](https://pypa-build.readthedocs.io/en/stable/) (PEP 517 builder)
@@ -207,6 +210,29 @@ def example():
     print(config["tool.spin"])
 ```
 
+### Argument overrides
+
+Default arguments can be overridden for any command.
+The custom command above, e.g., has the following signature:
+
+```python
+@click.command()
+@click.option("-f", "--flag")
+@click.option("-t", "--test", default="not set")
+def example(flag, test, default_kwd=None):
+    """🧪 Example custom command.
+    ...
+    """
+```
+
+Use the `[tool.spin.kwargs]` section to override default values for
+click options or function keywords:
+
+```toml
+[tool.spin.kwargs]
+".spin/cmds.py:example" = {"test" = "default override", "default_kwd" = 3}
+```
+
 ### Advanced: adding arguments to built-in commands
 
 Instead of rewriting a command from scratch, a project may want to add a flag to a built-in `spin` command, or perhaps do some pre- or post-processing.
@@ -284,7 +310,7 @@ fc-cache -f -v
 `spin` tests are invoked using:
 
 ```
-nox -s tests
+nox -s test
 ```
 
 ## History

{spin-0.8 → spin-0.9}/README.md

@@ -3,14 +3,17 @@
 ## A developer tool for scientific Python libraries
 
 Developers need to memorize a whole bunch of magic command-line incantations.
-And these incantations change from time to time!
-Typically, their lives are made simpler by a Makefile, but Makefiles can be convoluted, are not written in Python, and are hard to extend.
-The rationale behind `spin` is therefore to provide a simple interface for common development tasks.
+These incantations may also change over time.
+Often, Makefiles are used to provide aliases, but Makefiles can be convoluted, are not written in Python, and are hard to extend.
+The goal of `spin` is therefore to provide a simple, user-friendly, extendable interface for common development tasks.
 It comes with a few common build commands out the box, but can easily be customized per project.
 
 As a curiosity: the impetus behind developing the tool was the mass migration of scientific Python libraries (SciPy, scikit-image, and NumPy, etc.) to Meson, after distutils was deprecated.
 When many of the build and installation commands changed, it made sense to abstract away the nuisance of having to re-learn them.
 
+_Note:_ We now have experimental builds for editable installs.
+Most of the Meson commands listed below should work "out of the box" for those.
+
 ## Installation
 
 ```
@@ -92,7 +95,6 @@ Available as `spin.cmds.meson.*`.
   docs     📖 Build Sphinx documentation
   gdb      👾 Execute a Python snippet with GDB
   lldb     👾 Execute a Python snippet with LLDB
-  install  💽 Build and install package using pip.
 ```
 
 ### [Build](https://pypa-build.readthedocs.io/en/stable/) (PEP 517 builder)
@@ -147,6 +149,29 @@ def example():
     print(config["tool.spin"])
 ```
 
+### Argument overrides
+
+Default arguments can be overridden for any command.
+The custom command above, e.g., has the following signature:
+
+```python
+@click.command()
+@click.option("-f", "--flag")
+@click.option("-t", "--test", default="not set")
+def example(flag, test, default_kwd=None):
+    """🧪 Example custom command.
+    ...
+    """
+```
+
+Use the `[tool.spin.kwargs]` section to override default values for
+click options or function keywords:
+
+```toml
+[tool.spin.kwargs]
+".spin/cmds.py:example" = {"test" = "default override", "default_kwd" = 3}
+```
+
 ### Advanced: adding arguments to built-in commands
 
 Instead of rewriting a command from scratch, a project may want to add a flag to a built-in `spin` command, or perhaps do some pre- or post-processing.
@@ -224,7 +249,7 @@ fc-cache -f -v
 `spin` tests are invoked using:
 
 ```
-nox -s tests
+nox -s test
 ```
 
 ## History

{spin-0.8 → spin-0.9}/pyproject.toml

@@ -25,7 +25,8 @@ classifiers = [
 dependencies = [
   "click",
   "tomli; python_version < '3.11'",
-  "colorama; platform_system == 'Windows'"
+  "colorama; platform_system == 'Windows'",
+  "importlib_metadata >= 7"
 ]
 dynamic = ['version']
 
@@ -33,8 +34,8 @@ dynamic = ['version']
 spin = "spin.__main__:main"
 
 [project.optional-dependencies]
-lint = ["pre-commit == 3.5.0"]
-dev = ["changelist == 0.4"]
+lint = ["pre-commit == 3.7.0"]
+dev = ["changelist == 0.5"]
 
 [project.urls]
 homepage = "https://github.com/scientific-python/spin"

{spin-0.8 → spin-0.9}/spin/__init__.py

@@ -6,7 +6,7 @@ For usage information see `python -m spin`.
 Read more at https://github.com/scientific-python/spin
 """
 
-__version__ = "0.8"
+__version__ = "0.9"
 
 from .cmds import util
 

{spin-0.8 → spin-0.9}/spin/__main__.py

@@ -25,10 +25,6 @@ def main():
     if (len(sys.argv) == 2) and (sys.argv[1] == "help"):
         sys.argv[1] = "--help"
 
-    def error(message):
-        print(f"Error: {message}", file=sys.stderr)
-        sys.exit(1)
-
     def load_toml(filename):
         if not os.path.exists(filename):
             return None
@@ -36,7 +32,7 @@ def main():
             try:
                 return tomllib.load(f)
             except tomllib.TOMLDecodeError:
-                error("cannot parse [{filename}]")
+                print(f"Error: cannot parse [{filename}]", file=sys.stderr)
 
     toml_config = collections.ChainMap()
     toml_config.maps.extend(
@@ -50,18 +46,28 @@ def main():
     )
 
     # Basic configuration validation
-    if "tool.spin" not in toml_config:
-        error(
-            "needs valid configuration in [.spin.toml], [spin.toml] or [pyproject.toml]"
-        )
-    if "tool.spin.commands" not in toml_config:
-        error("configuration is missing section [tool.spin.commands]")
+    version_query = len(sys.argv) == 2 and (sys.argv[1] == "--version")
+
+    spin_config = {}
+    if not version_query:
+        if "tool.spin" in toml_config:
+            spin_config = toml_config["tool.spin"]
+            if "tool.spin.commands" not in toml_config:
+                print(
+                    "Error: configuration is missing section [tool.spin.commands]\n",
+                    file=sys.stderr,
+                )
+        else:
+            print(
+                "Error: need valid configuration in [.spin.toml], [spin.toml], or [pyproject.toml]\n"
+                "See https://github.com/scientific-python/spin/blob/main/README.md\n",
+                file=sys.stderr,
+            )
 
-    spin_config = toml_config["tool.spin"]
     proj_name = (
         toml_config.get("project.name")
         or spin_config.get("package")
-        or "unknown project"
+        or "[unknown project]"
     )
 
     @click.group(help=f"Developer tool for {proj_name}", cls=SectionedHelpGroup)
@@ -72,7 +78,7 @@ def main():
         ctx.meta["commands"] = ctx.command.section_commands
         ctx.show_default = True
 
-    config_cmds = spin_config["commands"]
+    config_cmds = spin_config.get("commands", [])
     # Commands can be provided as a list, or as a dictionary
     # so that they can be sorted into sections
     if isinstance(config_cmds, list):
@@ -88,6 +94,7 @@ def main():
         "spin.python": _cmds.meson.python,
         "spin.shell": _cmds.meson.shell,
     }
+    cmd_default_kwargs = toml_config.get("tool.spin.kwargs", {})
 
     for section, cmds in config_cmds.items():
         for cmd in cmds:
@@ -127,6 +134,18 @@ def main():
                     print(f"!! Could not load command `{func}` from file `{path}`.\n")
                     continue
 
+                default_kwargs = cmd_default_kwargs.get(cmd)
+                import functools
+
+                if default_kwargs:
+                    callback = cmd_func.callback
+                    cmd_func.callback = functools.partial(callback, **default_kwargs)
+
+                    # Also override option defaults
+                    for option in cmd_func.params:
+                        if option.name in default_kwargs:
+                            option.default = default_kwargs[option.name]
+
                 commands[cmd] = cmd_func
 
             group.add_command(commands[cmd], section=section)
@@ -134,7 +153,8 @@ def main():
     try:
         group()
     except Exception as e:
-        error(f"{e}; aborting.")
+        print(f"Error: {e}; aborting.", file=sys.stderr)
+        sys.exit(1)
 
 
 if __name__ == "__main__":

{spin-0.8 → spin-0.9}/spin/cmds/meson.py

@@ -1,8 +1,12 @@
 import contextlib
+import copy
 import json
 import os
+import re
 import shutil
 import sys
+from enum import Enum
+from pathlib import Path
 
 import click
 
@@ -10,6 +14,14 @@ from .util import get_commands, get_config
 from .util import run as _run
 
 install_dir = "build-install"
+build_dir = "build"
+
+
+class GcovReportFormat(str, Enum):
+    html = "html"
+    xml = "xml"
+    text = "text"
+    sonarqube = "sonarqube"
 
 
 # Allow specification of meson binary in configuration
@@ -25,6 +37,32 @@ def _meson_cli():
         return [meson_cli]
 
 
+def _editable_install_path(distname):
+    import importlib_metadata
+
+    try:
+        dist = importlib_metadata.Distribution.from_name(distname)
+    except importlib_metadata.PackageNotFoundError:
+        return None
+
+    if getattr(dist.origin.dir_info, "editable", False):
+        if sys.platform == "win32":
+            return dist.origin.url.removeprefix("file:///")
+        else:
+            return dist.origin.url.removeprefix("file://")
+    else:
+        return None
+
+
+def _is_editable_install(distname):
+    return _editable_install_path(distname) is not None
+
+
+def _is_editable_install_of_same_source(distname):
+    editable_path = _editable_install_path(distname)
+    return editable_path and os.path.samefile(_editable_install_path(distname), ".")
+
+
 def _set_pythonpath(quiet=False):
     """Set first entry of PYTHONPATH to site packages directory.
 
@@ -35,6 +73,29 @@ def _set_pythonpath(quiet=False):
     site_packages = _get_site_packages()
     env = os.environ
 
+    cfg = get_config()
+    distname = cfg.get("project.name", None)
+    if distname:
+        if _is_editable_install(distname):
+            if _is_editable_install_of_same_source(distname):
+                if not (quiet):
+                    click.secho(
+                        "Editable install of same source directory detected; not setting PYTHONPATH",
+                        fg="bright_red",
+                    )
+                return ""
+            else:
+                # Ignoring the quiet flag, because picking up the wrong package is problematic
+                click.secho(
+                    f"Warning! Editable install of `{distname}`, from a different source location, detected.",
+                    fg="bright_red",
+                )
+                click.secho("Spin commands will pick up that version.", fg="bright_red")
+                click.secho(
+                    f"Try removing the other installation by switching to its source and running `pip uninstall {distname}`.",
+                    fg="bright_red",
+                )
+
     if "PYTHONPATH" in env:
         env["PYTHONPATH"] = f"{site_packages}{os.pathsep}{env['PYTHONPATH']}"
     else:
@@ -49,6 +110,15 @@ def _set_pythonpath(quiet=False):
 
 
 def _get_site_packages():
+    try:
+        cfg = get_config()
+        distname = cfg.get("project.name", None)
+        if _is_editable_install_of_same_source(distname):
+            return ""
+    except RuntimeError:
+        # Probably not running in click
+        pass
+
     candidate_paths = []
     for root, dirs, _files in os.walk(install_dir):
         for subdir in dirs:
@@ -103,14 +173,67 @@ def _meson_version_configured():
         pass
 
 
+def _meson_coverage_configured() -> bool:
+    try:
+        build_options_fn = os.path.join(
+            "build", "meson-info", "intro-buildoptions.json"
+        )
+        with open(build_options_fn) as f:
+            build_options = json.load(f)
+        for b in build_options:
+            if (b["name"] == "b_coverage") and (b["value"] is True):
+                return True
+    except:
+        pass
+
+    return False
+
+
+def _check_coverage_tool_installation(coverage_type: GcovReportFormat):
+    requirements = {  # https://github.com/mesonbuild/meson/blob/6e381714c7cb15877e2bcaa304b93c212252ada3/docs/markdown/Unit-tests.md?plain=1#L49-L62
+        GcovReportFormat.html: ["Gcovr/GenHTML", "lcov"],
+        GcovReportFormat.xml: ["Gcovr (version 3.3 or higher)"],
+        GcovReportFormat.text: ["Gcovr (version 3.3 or higher)"],
+        GcovReportFormat.sonarqube: ["Gcovr (version 4.2 or higher)"],
+    }
+
+    # First check the presence of a valid build
+    if not (os.path.exists(build_dir)):
+        raise click.ClickException(
+            f"`{build_dir}` folder not found, cannot generate coverage reports. "
+            "Generate coverage artefacts by running `spin test --gcov`"
+        )
+
+    debug_files = Path(build_dir).rglob("*.gcno")
+    if len(list(debug_files)) == 0:
+        raise click.ClickException(
+            "Debug build not found, cannot generate coverage reports.\n\n"
+            "Please rebuild using `spin build --clean --gcov` first."
+        )
+
+    # Verify the tools are installed prior to the build
+    p = _run(["ninja", "-C", build_dir, "-t", "targets", "all"], output=False)
+    if f"coverage-{coverage_type.value}" not in p.stdout.decode("ascii"):
+        raise click.ClickException(
+            f"coverage-{coverage_type.value} is not supported... "
+            f"Ensure the following are installed: {', '.join(requirements[coverage_type])} "
+            "and rerun `spin test --gcov`"
+        )
+
+
 @click.command()
 @click.option("-j", "--jobs", help="Number of parallel tasks to launch", type=int)
 @click.option("--clean", is_flag=True, help="Clean build directory before build")
 @click.option(
     "-v", "--verbose", is_flag=True, help="Print detailed build and installation output"
 )
+@click.option(
+    "--gcov",
+    is_flag=True,
+    help="Enable C code coverage using `gcov`. Use `spin test --gcov` to generate reports.",
+)
 @click.argument("meson_args", nargs=-1)
-def build(meson_args, jobs=None, clean=False, verbose=False, quiet=False):
+def build(meson_args, jobs=None, clean=False, verbose=False, gcov=False, quiet=False):
     """🔧 Build package with Meson/ninja and install
 
     MESON_ARGS are passed through e.g.:
@@ -128,8 +251,22 @@ def build(meson_args, jobs=None, clean=False, verbose=False, quiet=False):
 
       CFLAGS="-O0 -g" spin build
     """
-    build_dir = "build"
-    setup_cmd = _meson_cli() + ["setup", build_dir, "--prefix=/usr"] + list(meson_args)
+    cfg = get_config()
+    distname = cfg.get("project.name", None)
+    if distname and _is_editable_install_of_same_source(distname):
+        if not quiet:
+            click.secho(
+                "Editable install of same source detected; skipping build",
+                fg="bright_red",
+            )
+        return
+
+    meson_args = list(meson_args)
+
+    if gcov:
+        meson_args = meson_args + ["-Db_coverage=true"]
+
+    setup_cmd = _meson_cli() + ["setup", build_dir, "--prefix=/usr"] + meson_args
 
     if clean:
         print(f"Removing `{build_dir}`")
@@ -149,7 +286,9 @@ def build(meson_args, jobs=None, clean=False, verbose=False, quiet=False):
         # Build dir has been configured; check if it was configured by
         # current version of Meson
 
-        if _meson_version() != _meson_version_configured():
+        if (_meson_version() != _meson_version_configured()) or (
+            gcov and not _meson_coverage_configured()
+        ):
             _run(setup_cmd + ["--reconfigure"], output=not quiet)
 
         # Any other conditions that warrant a reconfigure?
@@ -213,10 +352,30 @@ Which tests to run. Can be a module, function, class, or method:
     "-c",
     "--coverage",
     is_flag=True,
-    help="Generate a coverage report of executed tests. An HTML copy of the report is written to `build/coverage`.",
+    help="Generate a Python coverage report of executed tests. An HTML copy of the report is written to `build/coverage`.",
+)
+@click.option(
+    "--gcov",
+    is_flag=True,
+    help="Generate a C coverage report in `build/meson-logs/coveragereport`.",
+)
+@click.option(
+    "--gcov-format",
+    type=click.Choice(GcovReportFormat),
+    default="html",
+    help=f"Format of the gcov report. Can be one of {', '.join(e.value for e in GcovReportFormat)}.",
 )
 @click.pass_context
-def test(ctx, pytest_args, n_jobs, tests, verbose, coverage=False):
+def test(
+    ctx,
+    pytest_args,
+    n_jobs,
+    tests,
+    verbose,
+    coverage=False,
+    gcov=None,
+    gcov_format=None,
+):
     """🔧 Run tests
 
     PYTEST_ARGS are passed through directly to pytest, e.g.:
@@ -253,16 +412,28 @@ def test(ctx, pytest_args, n_jobs, tests, verbose, coverage=False):
 
       spin test -j auto
 
+    To run a test inside of LLDB:
+
+      spin lldb -- python -mspin test ...
+
     For more, see `pytest --help`.
     """  # noqa: E501
     cfg = get_config()
+    distname = cfg.get("project.name", None)
+
+    if gcov and distname and _is_editable_install_of_same_source(distname):
+        click.secho(
+            "Error: cannot generate coverage report for editable installs",
+            fg="bright_red",
+        )
+        raise SystemExit(-1)
 
     build_cmd = _get_configured_command("build")
     if build_cmd:
         click.secho(
             "Invoking `build` prior to running tests:", bold=True, fg="bright_green"
         )
-        ctx.invoke(build_cmd)
+        ctx.invoke(build_cmd, gcov=bool(gcov))
 
     package = cfg.get("tool.spin.package", None)
     if (not pytest_args) and (not tests):
@@ -274,6 +445,8 @@ def test(ctx, pytest_args, n_jobs, tests, verbose, coverage=False):
             sys.exit(1)
 
     site_path = _set_pythonpath()
+    if site_path:
+        print(f'$ export PYTHONPATH="{site_path}"')
 
     # Sanity check that library built properly
     #
@@ -313,12 +486,54 @@ def test(ctx, pytest_args, n_jobs, tests, verbose, coverage=False):
             f"--cov={package}",
         ]
 
-    print(f'$ export PYTHONPATH="{site_path}"')
-    _run(
-        [sys.executable, "-m", "pytest", f"--rootdir={site_path}"] + list(pytest_args),
+    if sys.version_info[:2] >= (3, 11):
+        cmd = [sys.executable, "-P", "-m", "pytest"]
+    else:
+        cmd = ["pytest"]
+
+    cwd = os.getcwd()
+    pytest_p = _run(
+        cmd + ([f"--rootdir={site_path}"] if site_path else []) + list(pytest_args),
         cwd=site_path,
-        replace=True,
     )
+    os.chdir(cwd)
+
+    if gcov:
+        # Verify the tools are present
+        click.secho(
+            "Verifying gcov dependencies...",
+            bold=True,
+            fg="bright_yellow",
+        )
+        _check_coverage_tool_installation(gcov_format)
+
+        # Generate report
+        click.secho(
+            f"Generating {gcov_format.value} coverage report...",
+            bold=True,
+            fg="bright_yellow",
+        )
+        p = _run(
+            [
+                "ninja",
+                "-C",
+                build_dir,
+                f"coverage-{gcov_format.value.lower()}",
+            ],
+            output=False,
+        )
+        coverage_folder = click.style(
+            re.search(r"file://(.*)", p.stdout.decode("utf-8")).group(1),
+            bold=True,
+            fg="bright_yellow",
+        )
+        click.secho(
+            f"Coverage report generated successfully and written to {coverage_folder}",
+            bold=True,
+            fg="bright_green",
+        )
+
+    raise SystemExit(pytest_p.returncode)
 
 
 @click.command()
@@ -392,7 +607,8 @@ def ipython(ctx, ipython_args):
         ctx.invoke(build_cmd)
 
     p = _set_pythonpath()
-    print(f'💻 Launching IPython with PYTHONPATH="{p}"')
+    if p:
+        print(f'💻 Launching IPython with PYTHONPATH="{p}"')
     _run(["ipython", "--ignore-cwd"] + list(ipython_args), replace=True)
 
 
@@ -417,9 +633,11 @@ def shell(ctx, shell_args=[]):
         ctx.invoke(build_cmd)
 
     p = _set_pythonpath()
+    if p:
+        print(f'💻 Launching shell with PYTHONPATH="{p}"')
+
     shell = os.environ.get("SHELL", "sh")
     cmd = [shell] + list(shell_args)
-    print(f'💻 Launching shell with PYTHONPATH="{p}"')
     print("⚠  Change directory to avoid importing source instead of built package")
     print("⚠  Ensure that your ~/.shellrc does not unset PYTHONPATH")
     _run(cmd, replace=True)
@@ -443,6 +661,9 @@ def python(ctx, python_args):
         ctx.invoke(build_cmd)
 
     p = _set_pythonpath()
+    if p:
+        print(f'🐍 Launching Python with PYTHONPATH="{p}"')
+
     v = sys.version_info
     if (v.major < 3) or (v.major == 3 and v.minor < 11):
         print("We're sorry, but this feature only works on Python 3.11 and greater 😢")
@@ -460,9 +681,7 @@ def python(ctx, python_args):
         print("import sys; del(sys.path[0])")
         sys.exit(-1)
 
-    print(f'🐍 Launching Python with PYTHONPATH="{p}"')
-
-    _run(["/usr/bin/env", "python", "-P"] + list(python_args), replace=True)
+    _run([sys.executable, "-P"] + list(python_args), replace=True)
 
 
 @click.command(context_settings={"ignore_unknown_options": True})
@@ -496,15 +715,28 @@ def run(ctx, args):
 
     is_posix = sys.platform in ("linux", "darwin")
     shell = len(args) == 1
+    cmd_args = copy.copy(args)
     if shell:
-        args = args[0]
-
-    if shell and not is_posix:
-        # On Windows, we're going to try to use bash
-        args = ["bash", "-c", args]
+        cmd_args = args[0]
+        if not is_posix:
+            # On Windows, we're going to try to use bash
+            cmd_args = ["bash", "-c", cmd_args]
 
     _set_pythonpath(quiet=True)
-    _run(args, echo=False, shell=shell)
+    p = _run(cmd_args, echo=False, shell=shell, sys_exit=False)
+
+    # Is the user trying to run a Python script, without calling the Python interpreter?
+    executable = args[0]
+    if (
+        (p.returncode != 0)
+        and args[0].endswith(".py")
+        and os.path.exists(executable)
+        and (not os.access(executable, os.X_OK))
+    ):
+        click.secho(
+            f"Did you mean to call `spin run python {' '.join(args)}`?", fg="bright_red"
+        )
+    sys.exit(p.returncode)
 
 
 @click.command()
@@ -562,15 +794,15 @@ def docs(ctx, sphinx_target, clean, first_build, jobs, sphinx_gallery_plot):
 
     if clean:
         doc_dirs = [
-            "./doc/build/",
-            "./doc/source/api/",
-            "./doc/source/auto_examples/",
-            "./doc/source/jupyterlite_contents/",
+            f"./{doc_dir}/build/",
+            f"./{doc_dir}/source/api/",
+            f"./{doc_dir}/source/auto_examples/",
+            f"./{doc_dir}/source/jupyterlite_contents/",
         ]
-        for doc_dir in doc_dirs:
-            if os.path.isdir(doc_dir):
-                print(f"Removing {doc_dir!r}")
-                shutil.rmtree(doc_dir)
+        for target_dir in doc_dirs:
+            if os.path.isdir(target_dir):
+                print(f"Removing {target_dir!r}")
+                shutil.rmtree(target_dir)
 
     build_cmd = _get_configured_command("build")
 
@@ -596,11 +828,16 @@ def docs(ctx, sphinx_target, clean, first_build, jobs, sphinx_gallery_plot):
         f"$ export SPHINXOPTS={os.environ['SPHINXOPTS']}", bold=True, fg="bright_blue"
     )
 
-    os.environ["PYTHONPATH"] = f'{site_path}{os.sep}:{os.environ.get("PYTHONPATH", "")}'
-    click.secho(
-        f"$ export PYTHONPATH={os.environ['PYTHONPATH']}", bold=True, fg="bright_blue"
-    )
-    _run(["make", "-C", "doc", sphinx_target], replace=True)
+    if site_path:
+        os.environ["PYTHONPATH"] = (
+            f'{site_path}{os.sep}:{os.environ.get("PYTHONPATH", "")}'
+        )
+        click.secho(
+            f"$ export PYTHONPATH={os.environ['PYTHONPATH']}",
+            bold=True,
+            fg="bright_blue",
+        )
+    _run(["make", "-C", doc_dir, sphinx_target], replace=True)
 
 
 @click.command()

spin-0.9/spin/tests/conftest.py

@@ -0,0 +1,20 @@
+import os
+
+import pytest
+
+from spin import util
+
+
+@pytest.fixture(autouse=True)
+def pre_post_test():
+    # Pre-test code
+    cwd = os.getcwd()
+    os.chdir("example_pkg")
+
+    try:
+        yield
+    finally:
+        # Post test code
+        os.chdir(cwd)
+        util.run(["git", "clean", "-xdf"], cwd="example_pkg")
+        os.chdir(cwd)

spin-0.9/spin/tests/test_build_cmds.py

@@ -0,0 +1,145 @@
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+import pytest
+from testutil import skip_on_windows, skip_unless_linux, spin, stdout
+
+from spin.cmds.util import run
+
+
+def test_basic_build():
+    """Does the package build?"""
+    spin("build")
+
+    assert Path("build").exists(), "`build` folder not created after `spin build`"
+    assert Path(
+        "build-install"
+    ).exists(), "`build-install` folder not created after `spin build`"
+
+
+def test_debug_builds():
+    """Does spin generate gcov debug output files?"""
+    spin("build", "--gcov")
+
+    debug_files = Path(".").rglob("*.gcno")
+    assert len(list(debug_files)) != 0, "debug files not generated for gcov build"
+
+
+def test_coverage_builds():
+    """Does gcov test generate coverage files?"""
+    spin("test", "--gcov")
+
+    coverage_files = Path(".").rglob("*.gcda")
+    assert len(list(coverage_files)) != 0, "coverage files not generated for gcov build"
+
+
+@pytest.mark.parametrize(
+    "report_type,output_file",
+    [
+        ("html", Path("coveragereport/index.html")),
+        ("xml", Path("coverage.xml")),
+        ("text", Path("coverage.txt")),
+        ("sonarqube", Path("sonarqube.xml")),
+    ],
+)
+def test_coverage_reports(report_type, output_file):
+    """Does gcov test generate coverage reports?"""
+    spin("test", "--gcov", f"--gcov-format={report_type}")
+
+    coverage_report = Path("./build/meson-logs", output_file)
+    assert (
+        coverage_report.exists()
+    ), f"coverage report not generated for gcov build ({report_type})"
+
+
+def test_expand_pythonpath():
+    """Does an $ENV_VAR get expanded in `spin run`?"""
+    output = spin("run", "echo $PYTHONPATH")
+    assert any(
+        p in stdout(output) for p in ("site-packages", "dist-packages")
+    ), f"Expected value of $PYTHONPATH, got {stdout(output)} instead"
+
+
+def test_run_stdout():
+    """Ensure `spin run` only includes command output on stdout."""
+    p = spin(
+        "run",
+        sys.executable,
+        "-c",
+        "import sys; del sys.path[0]; import example_pkg; print(example_pkg.__version__)",
+    )
+    assert (
+        stdout(p) == "0.0.0dev0"
+    ), f"`spin run` stdout did not yield version, but {stdout(p)}"
+
+
+# Detecting whether a file is executable is not that easy on Windows,
+# as it seems to take into consideration whether that file is associated as an executable.
+@skip_on_windows
+def test_recommend_run_python():
+    """If `spin run file.py` is called, is `spin run python file.py` recommended?"""
+    with tempfile.NamedTemporaryFile(suffix=".py") as f:
+        p = spin("run", f.name, sys_exit=False)
+        assert "Did you mean to call" in stdout(
+            p
+        ), "Failed to recommend `python run python file.py`"
+
+
+def test_test():
+    """Does the test command run?"""
+    spin("test")
+
+
+def test_test_with_pythonpath():
+    """Does `spin test` work when PYTHONPATH is set?"""
+    spin("test", env={**os.environ, "PYTHONPATH": "/tmp"})
+
+
+def test_sdist():
+    spin("sdist")
+
+
+def test_example():
+    spin("example")
+
+
+def test_docs():
+    run(["pip", "install", "--quiet", "sphinx"])
+    spin("docs")
+
+
+def test_spin_install():
+    cwd = os.getcwd()
+    spin("install")
+    with tempfile.TemporaryDirectory() as d:
+        try:
+            os.chdir(d)
+            p = run(
+                [
+                    sys.executable,
+                    "-c",
+                    "import example_pkg; print(example_pkg.__version__)",
+                ],
+                stdout=subprocess.PIPE,
+            )
+            assert stdout(p) == "0.0.0dev0"
+        finally:
+            os.chdir(cwd)
+            run(["pip", "uninstall", "-y", "--quiet", "example_pkg"])
+
+
+@skip_unless_linux
+def test_gdb():
+    p = spin(
+        "gdb",
+        "-c",
+        'import example_pkg; example_pkg.echo("hi")',
+        "--",
+        "--eval",
+        "run",
+        "--batch",
+    )
+    assert "hi" in stdout(p)

spin-0.9/spin/tests/test_cli.py

@@ -0,0 +1,17 @@
+from testutil import spin, stdout
+
+import spin as libspin
+
+
+def test_get_version():
+    p = spin("--version")
+    assert stdout(p) == f"spin {libspin.__version__}"
+
+
+def test_arg_override():
+    p = spin("example")
+    assert "--test is: default override" in stdout(p)
+    assert "Default kwd is: 3" in stdout(p)
+
+    p = spin("example", "-t", 6)
+    assert "--test is: 6" in stdout(p)

spin-0.9/spin/tests/test_editable.py

@@ -0,0 +1,21 @@
+import pytest
+from testutil import spin, stdout
+
+from spin.cmds.util import run
+
+
+@pytest.fixture
+def editable_install():
+    run(["pip", "install", "--quiet", "--no-build-isolation", "-e", "."])
+    yield
+    run(["pip", "uninstall", "--quiet", "-y", "example_pkg"])
+
+
+def test_detect_editable(editable_install):
+    assert "Editable install of same source detected" in stdout(
+        spin("build")
+    ), "Failed to detect and warn about editable install"
+
+
+def test_editable_tests(editable_install):
+    spin("test")

spin-0.9/spin/tests/testutil.py

@@ -0,0 +1,32 @@
+import subprocess
+import sys
+
+import pytest
+
+from spin.cmds.util import run
+
+skip_on_windows = pytest.mark.skipif(
+    sys.platform.startswith("win"), reason="Skipped; platform is Windows"
+)
+
+skip_unless_linux = pytest.mark.skipif(
+    not sys.platform.startswith("linux"), reason="Skipped; platform not Linux"
+)
+
+
+def spin(*args, **user_kwargs):
+    args = (str(el) for el in args)
+    default_kwargs = {
+        "stdout": subprocess.PIPE,
+        "stderr": subprocess.PIPE,
+        "sys_exit": True,
+    }
+    return run(["spin"] + list(args), **{**default_kwargs, **user_kwargs})
+
+
+def stdout(p):
+    return p.stdout.decode("utf-8").strip()
+
+
+def stderr(p):
+    return p.stderr.decode("utf-8").strip()

{spin-0.8 → spin-0.9/spin.egg-info}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.1
 Name: spin
-Version: 0.8
+Version: 0.9
 Summary: Developer tool for scientific Python libraries
 Maintainer-email: Scientific Python <spin@discuss.scientific-python.org>
 License: BSD 3-Clause License
         
-        Copyright (c) 2021--2022, Scientific Python project
+        Copyright (c) 2021--2024, Scientific Python project
         All rights reserved.
         
         Redistribution and use in source and binary forms, with or without
@@ -53,24 +53,28 @@ License-File: LICENSE
 Requires-Dist: click
 Requires-Dist: tomli; python_version < "3.11"
 Requires-Dist: colorama; platform_system == "Windows"
+Requires-Dist: importlib_metadata>=7
 Provides-Extra: lint
-Requires-Dist: pre-commit==3.5.0; extra == "lint"
+Requires-Dist: pre-commit==3.7.0; extra == "lint"
 Provides-Extra: dev
-Requires-Dist: changelist==0.4; extra == "dev"
+Requires-Dist: changelist==0.5; extra == "dev"
 
 # 💫 Scientific Python INcantations (`spin`)
 
 ## A developer tool for scientific Python libraries
 
 Developers need to memorize a whole bunch of magic command-line incantations.
-And these incantations change from time to time!
-Typically, their lives are made simpler by a Makefile, but Makefiles can be convoluted, are not written in Python, and are hard to extend.
-The rationale behind `spin` is therefore to provide a simple interface for common development tasks.
+These incantations may also change over time.
+Often, Makefiles are used to provide aliases, but Makefiles can be convoluted, are not written in Python, and are hard to extend.
+The goal of `spin` is therefore to provide a simple, user-friendly, extendable interface for common development tasks.
 It comes with a few common build commands out the box, but can easily be customized per project.
 
 As a curiosity: the impetus behind developing the tool was the mass migration of scientific Python libraries (SciPy, scikit-image, and NumPy, etc.) to Meson, after distutils was deprecated.
 When many of the build and installation commands changed, it made sense to abstract away the nuisance of having to re-learn them.
 
+_Note:_ We now have experimental builds for editable installs.
+Most of the Meson commands listed below should work "out of the box" for those.
+
 ## Installation
 
 ```
@@ -152,7 +156,6 @@ Available as `spin.cmds.meson.*`.
   docs     📖 Build Sphinx documentation
   gdb      👾 Execute a Python snippet with GDB
   lldb     👾 Execute a Python snippet with LLDB
-  install  💽 Build and install package using pip.
 ```
 
 ### [Build](https://pypa-build.readthedocs.io/en/stable/) (PEP 517 builder)
@@ -207,6 +210,29 @@ def example():
     print(config["tool.spin"])
 ```
 
+### Argument overrides
+
+Default arguments can be overridden for any command.
+The custom command above, e.g., has the following signature:
+
+```python
+@click.command()
+@click.option("-f", "--flag")
+@click.option("-t", "--test", default="not set")
+def example(flag, test, default_kwd=None):
+    """🧪 Example custom command.
+    ...
+    """
+```
+
+Use the `[tool.spin.kwargs]` section to override default values for
+click options or function keywords:
+
+```toml
+[tool.spin.kwargs]
+".spin/cmds.py:example" = {"test" = "default override", "default_kwd" = 3}
+```
+
 ### Advanced: adding arguments to built-in commands
 
 Instead of rewriting a command from scratch, a project may want to add a flag to a built-in `spin` command, or perhaps do some pre- or post-processing.
@@ -284,7 +310,7 @@ fc-cache -f -v
 `spin` tests are invoked using:
 
 ```
-nox -s tests
+nox -s test
 ```
 
 ## History

{spin-0.8 → spin-0.9}/spin.egg-info/SOURCES.txt

@@ -17,4 +17,9 @@ spin/cmds/build.py
 spin/cmds/meson.py
 spin/cmds/pip.py
 spin/cmds/util.py
-spin/tests/test_meson.py
+spin/tests/conftest.py
+spin/tests/test_build_cmds.py
+spin/tests/test_cli.py
+spin/tests/test_editable.py
+spin/tests/test_meson.py
+spin/tests/testutil.py

{spin-0.8 → spin-0.9}/spin.egg-info/requires.txt

@@ -1,4 +1,5 @@
 click
+importlib_metadata>=7
 
 [:platform_system == "Windows"]
 colorama
@@ -7,7 +8,7 @@ colorama
 tomli
 
 [dev]
-changelist==0.4
+changelist==0.5
 
 [lint]
-pre-commit==3.5.0
+pre-commit==3.7.0