spin 0.11__tar.gz → 0.12__tar.gz

{spin-0.11/spin.egg-info → spin-0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: spin
-Version: 0.11
+Version: 0.12
 Summary: Developer tool for scientific Python libraries
 Maintainer-email: Scientific Python <spin@discuss.scientific-python.org>
 License: BSD 3-Clause License
@@ -55,7 +55,7 @@ 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.7.1; extra == "lint"
+Requires-Dist: pre-commit==3.8.0; extra == "lint"
 Provides-Extra: dev
 Requires-Dist: changelist==0.5; extra == "dev"
 
@@ -147,15 +147,15 @@ python -m spin
 Available as `spin.cmds.meson.*`.
 
 ```
-  build    🔧 Build package with Meson/ninja
-  ipython  💻 Launch IPython shell with PYTHONPATH set
-  python   🐍 Launch Python shell with PYTHONPATH set
-  shell    💻 Launch shell with PYTHONPATH set
-  test     🔧 Run pytest
-  run      🏁 Run a shell command with PYTHONPATH set
-  docs     📖 Build Sphinx documentation
-  gdb      👾 Execute a Python snippet with GDB
-  lldb     👾 Execute a Python snippet with LLDB
+build      🔧 Build package with Meson/ninja
+ipython    💻 Launch IPython shell with PYTHONPATH set
+python     🐍 Launch Python shell with PYTHONPATH set
+shell      💻 Launch shell with PYTHONPATH set
+test       🔧 Run pytest
+run        🏁 Run a shell command with PYTHONPATH set
+docs       📖 Build Sphinx documentation
+gdb        👾 Execute a Python snippet with GDB
+lldb       👾 Execute a Python snippet with LLDB
 ```
 
 ### [Build](https://pypa-build.readthedocs.io/en/stable/) (PEP 517 builder)
@@ -163,7 +163,7 @@ Available as `spin.cmds.meson.*`.
 Available as `spin.cmds.build.*`:
 
 ```
-  sdist    📦 Build a source distribution in `dist/`
+sdist      📦 Build a source distribution in `dist/`
 ```
 
 ### [pip](https://pip.pypa.io) (Package Installer for Python)
@@ -174,7 +174,15 @@ development workflow.
 Available as `spin.cmds.pip.*`:
 
 ```
-  install  💽 Build and install package using pip.
+install    💽 Build and install package using pip.
+```
+
+### Meta (commands that operate on commands)
+
+Available as `spin.cmds.meta.*`:
+
+```
+introspect 🔍 Print a command's location and source code
 ```
 
 ## 🧪 Custom commands
@@ -310,6 +318,13 @@ fc-cache -f -v
 nox -s test
 ```
 
+Other examples:
+
+```
+nox -s test -- -v
+nox -s test -- -v spin/tests/test_meson.py
+```
+
 ## History
 
 The `dev.py` tool was [proposed for SciPy](https://github.com/scipy/scipy/issues/15489) by Ralf Gommers and [implemented](https://github.com/scipy/scipy/pull/15959) by Sayantika Banik, Eduardo Naufel Schettino, and Ralf Gommers (also see [Sayantika's blog post](https://labs.quansight.org/blog/the-evolution-of-the-scipy-developer-cli)).

{spin-0.11 → spin-0.12}/README.md

@@ -86,15 +86,15 @@ python -m spin
 Available as `spin.cmds.meson.*`.
 
 ```
-  build    🔧 Build package with Meson/ninja
-  ipython  💻 Launch IPython shell with PYTHONPATH set
-  python   🐍 Launch Python shell with PYTHONPATH set
-  shell    💻 Launch shell with PYTHONPATH set
-  test     🔧 Run pytest
-  run      🏁 Run a shell command with PYTHONPATH set
-  docs     📖 Build Sphinx documentation
-  gdb      👾 Execute a Python snippet with GDB
-  lldb     👾 Execute a Python snippet with LLDB
+build      🔧 Build package with Meson/ninja
+ipython    💻 Launch IPython shell with PYTHONPATH set
+python     🐍 Launch Python shell with PYTHONPATH set
+shell      💻 Launch shell with PYTHONPATH set
+test       🔧 Run pytest
+run        🏁 Run a shell command with PYTHONPATH set
+docs       📖 Build Sphinx documentation
+gdb        👾 Execute a Python snippet with GDB
+lldb       👾 Execute a Python snippet with LLDB
 ```
 
 ### [Build](https://pypa-build.readthedocs.io/en/stable/) (PEP 517 builder)
@@ -102,7 +102,7 @@ Available as `spin.cmds.meson.*`.
 Available as `spin.cmds.build.*`:
 
 ```
-  sdist    📦 Build a source distribution in `dist/`
+sdist      📦 Build a source distribution in `dist/`
 ```
 
 ### [pip](https://pip.pypa.io) (Package Installer for Python)
@@ -113,7 +113,15 @@ development workflow.
 Available as `spin.cmds.pip.*`:
 
 ```
-  install  💽 Build and install package using pip.
+install    💽 Build and install package using pip.
+```
+
+### Meta (commands that operate on commands)
+
+Available as `spin.cmds.meta.*`:
+
+```
+introspect 🔍 Print a command's location and source code
 ```
 
 ## 🧪 Custom commands
@@ -249,6 +257,13 @@ fc-cache -f -v
 nox -s test
 ```
 
+Other examples:
+
+```
+nox -s test -- -v
+nox -s test -- -v spin/tests/test_meson.py
+```
+
 ## History
 
 The `dev.py` tool was [proposed for SciPy](https://github.com/scipy/scipy/issues/15489) by Ralf Gommers and [implemented](https://github.com/scipy/scipy/pull/15959) by Sayantika Banik, Eduardo Naufel Schettino, and Ralf Gommers (also see [Sayantika's blog post](https://labs.quansight.org/blog/the-evolution-of-the-scipy-developer-cli)).

{spin-0.11 → spin-0.12}/pyproject.toml

@@ -34,12 +34,15 @@ dynamic = ['version']
 spin = "spin.__main__:main"
 
 [project.optional-dependencies]
-lint = ["pre-commit == 3.7.1"]
+lint = ["pre-commit == 3.8.0"]
 dev = ["changelist == 0.5"]
 
 [project.urls]
 homepage = "https://github.com/scientific-python/spin"
 
+[tool.changelist]
+ignored_user_logins = ["dependabot[bot]", "pre-commit-ci[bot]", "web-flow"]
+
 [tool.setuptools.dynamic.version]
 attr = 'spin.__version__'
 
@@ -47,13 +50,13 @@ attr = 'spin.__version__'
 include = ["spin*"]
 
 [tool.pytest.ini_options]
+minversion = "8.0"
+addopts = ["-ra", "--showlocals", "--strict-markers", "--strict-config"]
+xfail_strict = true
 filterwarnings = [
   "ignore:cannot collect 'test' because it is not a function:",
 ]
-
-[tool.ruff]
-line-length = 88
-target-version = "py38"
+log_cli_level = "info"
 
 [tool.ruff.lint]
 select = [
@@ -63,6 +66,11 @@ select = [
     "W",
     "B",
     "I",
+    "C4",
+    "ISC",
+    "PGH",
     "UP",
+    "FURB",
+    "PYI",
 ]
 ignore = ["B006", "C901", "E501", "E722"]

{spin-0.11 → spin-0.12}/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.11"
+__version__ = "0.12"
 
 from .cmds import util
 

{spin-0.11 → spin-0.12}/spin/__main__.py

@@ -2,9 +2,11 @@ import collections
 import importlib
 import importlib.util
 import os
+import pathlib
 import sys
 import textwrap
 import traceback
+from typing import Union
 
 import click
 
@@ -19,8 +21,26 @@ if sys.version_info >= (3, 11):
 else:
     import tomli as tomllib
 
+
 click.Context.formatter_class = ColorHelpFormatter
 
+config_filenames = (
+    ".spin.toml",
+    "spin.toml",
+    "pyproject.toml",
+)
+
+
+def _detect_config_dir(path: pathlib.Path) -> Union[pathlib.Path, None]:
+    path = path.resolve()
+    files = os.listdir(path)
+    if any(f in files for f in config_filenames):
+        return path
+    elif path.parent != path:
+        return _detect_config_dir(path.parent)
+    else:
+        return None
+
 
 def main():
     # Alias `spin help` to `spin --help`
@@ -38,15 +58,25 @@ def main():
 
     toml_config = collections.ChainMap()
     toml_config.maps.extend(
-        DotDict(cfg)
-        for filename in (
-            ".spin.toml",
-            "spin.toml",
-            "pyproject.toml",
-        )
-        if (cfg := load_toml(filename))
+        DotDict(cfg) for filename in config_filenames if (cfg := load_toml(filename))
     )
 
+    if not toml_config:
+        click.secho(
+            f"Could not load configuration from one of: {', '.join(config_filenames)}",
+            file=sys.stderr,
+            fg="red",
+        )
+        config_dir = _detect_config_dir(pathlib.Path("."))
+        if config_dir:
+            print()
+            print(
+                "Are you running `spin` from the correct directory? Perhaps you'd like to\n"
+            )
+            click.secho(f" $ cd {os.path.relpath(config_dir, '.')}\n")
+            print("and try again.")
+        sys.exit(1)
+
     # Basic configuration validation
     version_query = len(sys.argv) == 2 and (sys.argv[1] == "--version")
 
@@ -55,15 +85,18 @@ def main():
         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",
+                click.secho(
+                    "Error: configuration is missing section [tool.spin.commands]\n"
+                    "See https://github.com/scientific-python/spin/blob/main/README.md\n",
                     file=sys.stderr,
+                    fg="red",
                 )
         else:
-            print(
+            click.secho(
                 "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,
+                fg="red",
             )
 
     proj_name = (
@@ -132,10 +165,14 @@ def main():
 
                 try:
                     cmd_func = getattr(mod, func)
+                    cmd_func.module = mod  # metadata for use by `introspect` command
                 except AttributeError:
                     print(f"!! Could not load command `{func}` from file `{path}`.\n")
                     continue
 
+                # Save command definition for use in `introspect`
+                cmd_func.spec = cmd
+
                 default_kwargs = cmd_default_kwargs.get(cmd)
                 import functools
 

spin-0.12/spin/cmds/build.py

@@ -0,0 +1,15 @@
+import click
+
+from .util import run
+
+
+@click.command()
+@click.argument("pyproject-build-args", metavar="", nargs=-1)
+def sdist(pyproject_build_args):
+    """📦 Build a source distribution in `dist/`
+
+    Extra arguments are passed to `pyproject-build`, e.g.
+
+      spin sdist -- -x -n
+    """
+    run(["pyproject-build", ".", "--sdist"] + list(pyproject_build_args))

{spin-0.11 → spin-0.12}/spin/cmds/meson.py

@@ -13,9 +13,6 @@ import click
 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"
@@ -68,16 +65,15 @@ def _is_editable_install_of_same_source(distname):
     return editable_path and os.path.samefile(_editable_install_path(distname), ".")
 
 
-def _set_pythonpath(quiet=False):
+def _set_pythonpath(build_dir, quiet=False):
     """Set first entry of PYTHONPATH to site packages directory.
 
+    For editable installs, leave the PYTHONPATH alone.
+
     Returns
     -------
     site_packages
     """
-    site_packages = _get_site_packages()
-    env = os.environ
-
     cfg = get_config()
     distname = cfg.get("project.name", None)
     if distname:
@@ -101,6 +97,9 @@ def _set_pythonpath(quiet=False):
                     fg="bright_red",
                 )
 
+    site_packages = _get_site_packages(build_dir)
+    env = os.environ
+
     if "PYTHONPATH" in env:
         env["PYTHONPATH"] = f"{site_packages}{os.pathsep}{env['PYTHONPATH']}"
     else:
@@ -114,7 +113,12 @@ def _set_pythonpath(quiet=False):
     return site_packages
 
 
-def _get_site_packages():
+def _get_install_dir(build_dir):
+    return f"{build_dir}-install"
+
+
+def _get_site_packages(build_dir):
+    install_dir = _get_install_dir(build_dir)
     try:
         cfg = get_config()
         distname = cfg.get("project.name", None)
@@ -168,9 +172,9 @@ def _meson_version():
         pass
 
 
-def _meson_version_configured():
+def _meson_version_configured(build_dir):
     try:
-        meson_info_fn = os.path.join("build", "meson-info", "meson-info.json")
+        meson_info_fn = os.path.join(build_dir, "meson-info", "meson-info.json")
         with open(meson_info_fn) as f:
             meson_info = json.load(f)
         return meson_info["meson_version"]["full"]
@@ -194,7 +198,7 @@ def _meson_coverage_configured() -> bool:
     return False
 
 
-def _check_coverage_tool_installation(coverage_type: GcovReportFormat):
+def _check_coverage_tool_installation(coverage_type: GcovReportFormat, build_dir):
     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)"],
@@ -226,6 +230,16 @@ def _check_coverage_tool_installation(coverage_type: GcovReportFormat):
         )
 
 
+build_dir_option = click.option(
+    "-C",
+    "--build-dir",
+    default="build",
+    show_envvar=True,
+    envvar="SPIN_BUILD_DIR",
+    help="Meson build directory; package is installed into './{build-dir}-install'.",
+)
+
+
 @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")
@@ -238,12 +252,21 @@ def _check_coverage_tool_installation(coverage_type: GcovReportFormat):
     help="Enable C code coverage using `gcov`. Use `spin test --gcov` to generate reports.",
 )
 @click.argument("meson_args", nargs=-1)
+@build_dir_option
 def build(
-    *, meson_args, jobs=None, clean=False, verbose=False, gcov=False, quiet=False
+    *,
+    meson_args,
+    jobs=None,
+    clean=False,
+    verbose=False,
+    gcov=False,
+    quiet=False,
+    build_dir=None,
 ):
     """🔧 Build package with Meson/ninja
 
-    The package is installed to `build-install`.
+    The package is installed to `build-install` (unless a different
+    build directory is specified with `-C`).
 
     MESON_ARGS are passed through e.g.:
 
@@ -257,7 +280,23 @@ def build(
     or set CFLAGS appropriately:
 
       CFLAGS="-O0 -g" spin build
+
+    Build into a different build/build-install directory via the
+    `-C/--build-dir` flag:
+
+      spin build -C build-for-feature-x
+
+    This feature is useful in combination with a shell alias, e.g.:
+
+      $ alias spin-clang="SPIN_BUILD_DIR=build-clang CC=clang spin"
+
+    Which can then be used to build (`spin-clang build`), to test (`spin-clang test ...`), etc.
+
     """
+    abs_build_dir = os.path.abspath(build_dir)
+    install_dir = _get_install_dir(build_dir)
+    abs_install_dir = os.path.abspath(install_dir)
+
     cfg = get_config()
     distname = cfg.get("project.name", None)
     if distname and _is_editable_install_of_same_source(distname):
@@ -283,7 +322,7 @@ def build(
         if os.path.isdir(install_dir):
             shutil.rmtree(install_dir)
 
-    if not (os.path.exists(build_dir) and _meson_version_configured()):
+    if not (os.path.exists(build_dir) and _meson_version_configured(build_dir)):
         p = _run(setup_cmd, sys_exit=False, output=not quiet)
         if p.returncode != 0:
             raise RuntimeError(
@@ -293,7 +332,7 @@ def build(
         # Build dir has been configured; check if it was configured by
         # current version of Meson
 
-        if (_meson_version() != _meson_version_configured()) or (
+        if (_meson_version() != _meson_version_configured(build_dir)) or (
             gcov and not _meson_coverage_configured()
         ):
             _run(setup_cmd + ["--reconfigure"], output=not quiet)
@@ -301,6 +340,9 @@ def build(
         # Any other conditions that warrant a reconfigure?
 
     compile_flags = ["-v"] if verbose else []
+    if jobs:
+        compile_flags += ["-j", str(jobs)]
+
     p = _run(
         _meson_cli() + ["compile"] + compile_flags + ["-C", build_dir],
         sys_exit=True,
@@ -314,7 +356,9 @@ def build(
             "-C",
             build_dir,
             "--destdir",
-            f"../{install_dir}",
+            install_dir
+            if os.path.isabs(install_dir)
+            else os.path.relpath(abs_install_dir, abs_build_dir),
         ],
         output=(not quiet) and verbose,
     )
@@ -334,7 +378,7 @@ def _get_configured_command(command_name):
     metavar="N_JOBS",
     default="1",
     help=(
-        "Number of parallel jobs for testing. " "Can be set to `auto` to use all cores."
+        "Number of parallel jobs for testing. Can be set to `auto` to use all cores."
     ),
 )
 @click.option(
@@ -372,6 +416,7 @@ Which tests to run. Can be a module, function, class, or method:
     default="html",
     help=f"Format of the gcov report. Can be one of {', '.join(e.value for e in GcovReportFormat)}.",
 )
+@build_dir_option
 @click.pass_context
 def test(
     ctx,
@@ -383,6 +428,7 @@ def test(
     coverage=False,
     gcov=None,
     gcov_format=None,
+    build_dir=None,
 ):
     """🔧 Run tests
 
@@ -420,10 +466,6 @@ def test(
 
       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()
@@ -469,13 +511,11 @@ def test(
             "Invoking `build` prior to running tests:", bold=True, fg="bright_green"
         )
         if gcov is not None:
-            ctx.invoke(build_cmd, gcov=bool(gcov))
+            ctx.invoke(build_cmd, build_dir=build_dir, gcov=bool(gcov))
         else:
-            ctx.invoke(build_cmd)
+            ctx.invoke(build_cmd, build_dir=build_dir)
 
-    site_path = _set_pythonpath()
-    if site_path:
-        print(f'$ export PYTHONPATH="{site_path}"')
+    site_path = _set_pythonpath(build_dir)
 
     # Sanity check that library built properly
     #
@@ -520,6 +560,7 @@ def test(
     else:
         cmd = ["pytest"]
 
+    install_dir = _get_install_dir(build_dir)
     if not os.path.exists(install_dir):
         os.mkdir(install_dir)
 
@@ -534,7 +575,7 @@ def test(
             bold=True,
             fg="bright_yellow",
         )
-        _check_coverage_tool_installation(gcov_format)
+        _check_coverage_tool_installation(gcov_format, build_dir)
 
         # Generate report
         click.secho(
@@ -568,8 +609,9 @@ def test(
 @click.command()
 @click.option("--code", "-c", help="Python program passed in as a string")
 @click.argument("gdb_args", nargs=-1)
+@build_dir_option
 @click.pass_context
-def gdb(ctx, *, code, gdb_args):
+def gdb(ctx, *, code, gdb_args, build_dir):
     """👾 Execute code through GDB
 
       spin gdb -c 'import numpy as np; print(np.__version__)'
@@ -595,9 +637,9 @@ def gdb(ctx, *, code, gdb_args):
         click.secho(
             "Invoking `build` prior to invoking gdb:", bold=True, fg="bright_green"
         )
-        ctx.invoke(build_cmd)
+        ctx.invoke(build_cmd, build_dir=build_dir)
 
-    _set_pythonpath()
+    _set_pythonpath(build_dir)
     gdb_args = list(gdb_args)
 
     if gdb_args and gdb_args[0].endswith(".py"):
@@ -620,8 +662,9 @@ def gdb(ctx, *, code, gdb_args):
 
 @click.command()
 @click.argument("ipython_args", nargs=-1)
+@build_dir_option
 @click.pass_context
-def ipython(ctx, *, ipython_args):
+def ipython(ctx, *, ipython_args, build_dir):
     """💻 Launch IPython shell with PYTHONPATH set
 
     IPYTHON_ARGS are passed through directly to IPython, e.g.:
@@ -633,9 +676,9 @@ def ipython(ctx, *, ipython_args):
         click.secho(
             "Invoking `build` prior to invoking ipython:", bold=True, fg="bright_green"
         )
-        ctx.invoke(build_cmd)
+        ctx.invoke(build_cmd, build_dir=build_dir)
 
-    p = _set_pythonpath()
+    p = _set_pythonpath(build_dir)
     if p:
         print(f'💻 Launching IPython with PYTHONPATH="{p}"')
     _run(["ipython", "--ignore-cwd"] + list(ipython_args), replace=True)
@@ -643,8 +686,9 @@ def ipython(ctx, *, ipython_args):
 
 @click.command()
 @click.argument("shell_args", nargs=-1)
+@build_dir_option
 @click.pass_context
-def shell(ctx, shell_args=[]):
+def shell(ctx, shell_args=[], build_dir=None):
     """💻 Launch shell with PYTHONPATH set
 
     SHELL_ARGS are passed through directly to the shell, e.g.:
@@ -659,9 +703,9 @@ def shell(ctx, shell_args=[]):
         click.secho(
             "Invoking `build` prior to invoking shell:", bold=True, fg="bright_green"
         )
-        ctx.invoke(build_cmd)
+        ctx.invoke(build_cmd, build_dir=build_dir)
 
-    p = _set_pythonpath()
+    p = _set_pythonpath(build_dir)
     if p:
         print(f'💻 Launching shell with PYTHONPATH="{p}"')
 
@@ -674,8 +718,9 @@ def shell(ctx, shell_args=[]):
 
 @click.command()
 @click.argument("python_args", nargs=-1)
+@build_dir_option
 @click.pass_context
-def python(ctx, *, python_args):
+def python(ctx, *, python_args, build_dir):
     """🐍 Launch Python shell with PYTHONPATH set
 
     PYTHON_ARGS are passed through directly to Python, e.g.:
@@ -687,9 +732,9 @@ def python(ctx, *, python_args):
         click.secho(
             "Invoking `build` prior to invoking Python:", bold=True, fg="bright_green"
         )
-        ctx.invoke(build_cmd)
+        ctx.invoke(build_cmd, build_dir=build_dir)
 
-    p = _set_pythonpath()
+    p = _set_pythonpath(build_dir)
     if p:
         print(f'🐍 Launching Python with PYTHONPATH="{p}"')
 
@@ -714,9 +759,10 @@ def python(ctx, *, python_args):
 
 
 @click.command(context_settings={"ignore_unknown_options": True})
+@build_dir_option
 @click.argument("args", nargs=-1)
 @click.pass_context
-def run(ctx, *, args):
+def run(ctx, *, args, build_dir=None):
     """🏁 Run a shell command with PYTHONPATH set
 
     \b
@@ -740,7 +786,7 @@ def run(ctx, *, args):
         # Redirect spin generated output
         with contextlib.redirect_stdout(sys.stderr):
             # Also ask build to be quiet
-            ctx.invoke(build_cmd, quiet=True)
+            ctx.invoke(build_cmd, build_dir=build_dir, quiet=True)
 
     is_posix = sys.platform in ("linux", "darwin")
     shell = len(args) == 1
@@ -751,7 +797,7 @@ def run(ctx, *, args):
             # On Windows, we're going to try to use bash
             cmd_args = ["bash", "-c", cmd_args]
 
-    _set_pythonpath(quiet=True)
+    _set_pythonpath(build_dir, quiet=True)
     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?
@@ -789,6 +835,7 @@ def run(ctx, *, args):
     help="Sphinx gallery: enable/disable plots",
 )
 @click.option("--jobs", "-j", default="auto", help="Number of parallel build jobs")
+@build_dir_option
 @click.pass_context
 def docs(
     ctx,
@@ -799,6 +846,7 @@ def docs(
     jobs,
     sphinx_gallery_plot,
     clean_dirs=None,
+    build_dir=None,
 ):
     """📖 Build Sphinx documentation
 
@@ -853,12 +901,14 @@ def docs(
         click.secho(
             "Invoking `build` prior to building docs:", bold=True, fg="bright_green"
         )
-        ctx.invoke(build_cmd)
+        ctx.invoke(build_cmd, build_dir=build_dir)
 
     try:
-        site_path = _get_site_packages()
+        site_path = _get_site_packages(build_dir)
     except FileNotFoundError:
-        print("No built numpy found; run `spin build` first.")
+        cfg = get_config()
+        distname = cfg.get("project.name", None)
+        print(f"{distname} build not found; run `spin build` or `spin install` first.")
         sys.exit(1)
 
     opts = os.environ.get("SPHINXOPTS", "-W")
@@ -889,8 +939,9 @@ def docs(
 @click.command()
 @click.option("--code", "-c", help="Python program passed in as a string")
 @click.argument("lldb_args", nargs=-1)
+@build_dir_option
 @click.pass_context
-def lldb(ctx, *, code, lldb_args):
+def lldb(ctx, *, code, lldb_args, build_dir=None):
     """👾 Execute code through LLDB
 
       spin lldb -c 'import numpy as np; print(np.__version__)'
@@ -918,9 +969,9 @@ def lldb(ctx, *, code, lldb_args):
         click.secho(
             "Invoking `build` prior to invoking lldb:", bold=True, fg="bright_green"
         )
-        ctx.invoke(build_cmd)
+        ctx.invoke(build_cmd, build_dir=build_dir)
 
-    _set_pythonpath()
+    _set_pythonpath(build_dir)
     lldb_args = list(lldb_args)
 
     if code:

spin-0.12/spin/cmds/meta.py

@@ -0,0 +1,60 @@
+import inspect
+
+import click
+
+from .util import get_commands, get_config
+
+
+def _highlight(src):
+    from pygments import highlight
+    from pygments.formatters import TerminalFormatter
+    from pygments.lexers import PythonLexer
+
+    return highlight(src, PythonLexer(), TerminalFormatter())
+
+
+@click.command()
+@click.argument("cmd", nargs=1)
+def introspect(*, cmd):
+    """🔍 Print a command's location and source code."""
+    cmds_by_section = get_commands()
+    overrides = get_config().get("tool.spin.kwargs")
+
+    cmds = {}
+    for section in cmds_by_section:
+        cmds.update({cmd.name: cmd for cmd in cmds_by_section[section]})
+
+    if cmd not in cmds:
+        raise SystemExit(f"Command `{cmd}` not found. Exiting.")
+
+    cmd_func = cmds[cmd]
+    try:
+        code = inspect.getsource(cmd_func.callback)
+    except TypeError:
+        # Perhaps a partial, try again
+        code = inspect.getsource(cmd_func.callback.func)
+
+    try:
+        code = _highlight(code)
+    except ImportError:
+        pass
+
+    print(code)
+
+    click.secho(
+        f"The `{cmd}` command is defined as `{cmd_func.spec}`.",
+        bold=True,
+        fg="magenta",
+    )
+
+    click.secho(
+        f"The code is in `{cmd_func.module.__file__}`.", bold=True, fg="magenta"
+    )
+
+    if cmd_func.spec in overrides:
+        click.secho(
+            "\nThe function has the following keyword overrides defined:\n",
+            bold=True,
+            fg="magenta",
+        )
+        print("  ", overrides[cmd_func.spec], "\n")

{spin-0.11 → spin-0.12}/spin/cmds/pip.py

@@ -9,7 +9,13 @@ from .util import run as _run
     default=True,
     help="Install in editable mode.",
 )
-@click.option("-v", "--verbose", is_flag=True, help="Print detailed build output.")
+@click.option(
+    "-v/-q",
+    "--verbose/--quiet",
+    is_flag=True,
+    default=True,
+    help="Print detailed build output.",
+)
 @click.option(
     "--verbose-import/--no-verbose-import",
     is_flag=True,

{spin-0.11 → spin-0.12}/spin/cmds/util.py

@@ -1,15 +1,18 @@
+from __future__ import (
+    annotations,  # noqa: F401  # TODO: remove once only >3.8 is supported
+)
+
 import os
 import shlex
 import subprocess
 import sys
-from typing import Optional
 
 import click
 
 
 def run(
     cmd: list[str],
-    cwd: Optional[str] = None,  # in 3.10 and up: str | None
+    cwd: str | None = None,  # in 3.10 and up: str | None
     replace: bool = False,
     sys_exit: bool = True,
     output: bool = True,

{spin-0.11 → spin-0.12}/spin/color_format.py

@@ -36,7 +36,7 @@ class ColorHelpFormatter(click.formatting.HelpFormatter):
             },
             default={"bold": True, "fg": "cyan"},
         )
-        val_fmt = RegexpFormatter({r"\[default: .*?\]": {"dim": True}})
+        val_fmt = RegexpFormatter({r"\[(env var: .*?; )?default: .*?\]": {"dim": True}})
         items = [(key_fmt(key), val_fmt(val)) for (key, val) in items]
         super().write_dl(items)
 

{spin-0.11 → spin-0.12}/spin/tests/test_build_cmds.py

@@ -5,7 +5,14 @@ import tempfile
 from pathlib import Path
 
 import pytest
-from testutil import skip_on_windows, skip_unless_linux, skip_unless_macos, spin, stdout
+from testutil import (
+    skip_on_windows,
+    skip_py_lt_311,
+    skip_unless_linux,
+    skip_unless_macos,
+    spin,
+    stdout,
+)
 
 from spin.cmds.util import run
 
@@ -147,3 +154,23 @@ def test_lldb():
         "--batch",
     )
     assert "hi" in stdout(p)
+
+
+@skip_py_lt_311  # python command does not run on older pythons
+def test_parallel_builds():
+    spin("build")
+    spin("build", "-C", "parallel/build")
+    p = spin("python", "--", "-c", "import example_pkg; print(example_pkg.__file__)")
+    example_pkg_path = stdout(p).split("\n")[-1]
+    p = spin(
+        "python",
+        "-C",
+        "parallel/build",
+        "--",
+        "-c",
+        "import example_pkg; print(example_pkg.__file__)",
+    )
+    example_pkg_parallel_path = stdout(p).split("\n")[-1]
+    assert "build-install" in example_pkg_path
+    assert "parallel/build-install" in example_pkg_parallel_path
+    assert "parallel/build-install" not in example_pkg_path

spin-0.12/spin/tests/test_meson.py

@@ -0,0 +1,109 @@
+import os
+import sys
+import tempfile
+from os.path import join as pjoin
+from os.path import normpath
+
+import pytest
+
+from spin.cmds import meson
+from spin.containers import DotDict
+
+
+def make_paths(root, paths):
+    for p in paths:
+        os.makedirs(pjoin(root, p.lstrip("/")))
+
+
+def test_path_discovery():
+    version = sys.version_info
+    X, Y = version.major, version.minor
+
+    # With multiple site-packages, choose the one that matches the
+    # current Python version
+    with tempfile.TemporaryDirectory() as d:
+        build_dir = pjoin(d, "./build")
+        install_dir = pjoin(d, "./build-install")
+
+        make_paths(
+            install_dir,
+            [
+                f"/usr/lib64/python{X}.{Y}/site-packages",
+                f"/usr/lib64/python{X}.{Y + 1}/site-packages",
+                f"/usr/lib64/python{X}.{Y + 2}/site-packages",
+            ],
+        )
+        assert normpath(
+            f"/usr/lib64/python{X}.{Y}/site-packages"
+        ) in meson._get_site_packages(build_dir)
+
+    # Debian uses dist-packages
+    with tempfile.TemporaryDirectory() as d:
+        build_dir = pjoin(d, "./build")
+        install_dir = pjoin(d, "./build-install")
+
+        make_paths(
+            install_dir,
+            [
+                f"/usr/lib64/python{X}.{Y}/dist-packages",
+            ],
+        )
+        assert normpath(
+            f"/usr/lib64/python{X}.{Y}/dist-packages"
+        ) in meson._get_site_packages(build_dir)
+
+    # If there is no version information in site-packages,
+    # use whatever site-packages can be found
+    with tempfile.TemporaryDirectory() as d:
+        build_dir = pjoin(d, "./build")
+        install_dir = pjoin(d, "./build-install")
+
+        make_paths(install_dir, ["/Python3/site-packages"])
+        assert normpath("/Python3/site-packages") in meson._get_site_packages(build_dir)
+
+    # Raise if no site-package directory present
+    with tempfile.TemporaryDirectory() as d:
+        install_dir = pjoin(d, "-install")
+
+        with pytest.raises(FileNotFoundError):
+            meson._get_site_packages(build_dir)
+
+    # If there are multiple site-package paths, but without version information,
+    # refuse the temptation to guess
+    with tempfile.TemporaryDirectory() as d:
+        build_dir = pjoin(d, "./build")
+        install_dir = pjoin(d, "./build-install")
+        make_paths(
+            install_dir, ["/Python3/x/site-packages", "/Python3/y/site-packages"]
+        )
+        with pytest.raises(FileNotFoundError):
+            meson._get_site_packages(build_dir)
+
+    # Multiple site-package paths found, but none that matches our Python
+    with tempfile.TemporaryDirectory() as d:
+        build_dir = pjoin(d, "./build")
+        install_dir = pjoin(d, "./build-install")
+
+        make_paths(
+            install_dir,
+            [
+                f"/usr/lib64/python{X}.{Y + 1}/site-packages",
+                f"/usr/lib64/python{X}.{Y + 2}/site-packages",
+            ],
+        )
+        with pytest.raises(FileNotFoundError):
+            meson._get_site_packages(build_dir)
+
+
+def test_meson_cli_discovery(monkeypatch):
+    config0 = DotDict({"tool": {"spin": {"meson": {"cli": "~/envs/py311/bin/meson"}}}})
+    config1 = DotDict(
+        {"tool": {"spin": {"meson": {"cli": "~/envs/py311/bin/meson.py"}}}}
+    )
+
+    with monkeypatch.context() as m:
+        m.setattr(meson, "get_config", lambda: config0)
+        assert meson._meson_cli()[0] == os.path.expanduser("~/envs/py311/bin/meson")
+
+        m.setattr(meson, "get_config", lambda: config1)
+        assert meson._meson_cli()[0] == sys.executable

{spin-0.11 → spin-0.12}/spin/tests/testutil.py

@@ -17,6 +17,10 @@ skip_unless_macos = pytest.mark.skipif(
     not sys.platform.startswith("darwin"), reason="Skipped; platform not macOS"
 )
 
+skip_py_lt_311 = pytest.mark.skipif(
+    sys.version_info[:2] < (3, 11), reason="Skipped; Python < 3.11"
+)
+
 
 def spin(*args, **user_kwargs):
     args = (str(el) for el in args)

{spin-0.11 → spin-0.12/spin.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: spin
-Version: 0.11
+Version: 0.12
 Summary: Developer tool for scientific Python libraries
 Maintainer-email: Scientific Python <spin@discuss.scientific-python.org>
 License: BSD 3-Clause License
@@ -55,7 +55,7 @@ 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.7.1; extra == "lint"
+Requires-Dist: pre-commit==3.8.0; extra == "lint"
 Provides-Extra: dev
 Requires-Dist: changelist==0.5; extra == "dev"
 
@@ -147,15 +147,15 @@ python -m spin
 Available as `spin.cmds.meson.*`.
 
 ```
-  build    🔧 Build package with Meson/ninja
-  ipython  💻 Launch IPython shell with PYTHONPATH set
-  python   🐍 Launch Python shell with PYTHONPATH set
-  shell    💻 Launch shell with PYTHONPATH set
-  test     🔧 Run pytest
-  run      🏁 Run a shell command with PYTHONPATH set
-  docs     📖 Build Sphinx documentation
-  gdb      👾 Execute a Python snippet with GDB
-  lldb     👾 Execute a Python snippet with LLDB
+build      🔧 Build package with Meson/ninja
+ipython    💻 Launch IPython shell with PYTHONPATH set
+python     🐍 Launch Python shell with PYTHONPATH set
+shell      💻 Launch shell with PYTHONPATH set
+test       🔧 Run pytest
+run        🏁 Run a shell command with PYTHONPATH set
+docs       📖 Build Sphinx documentation
+gdb        👾 Execute a Python snippet with GDB
+lldb       👾 Execute a Python snippet with LLDB
 ```
 
 ### [Build](https://pypa-build.readthedocs.io/en/stable/) (PEP 517 builder)
@@ -163,7 +163,7 @@ Available as `spin.cmds.meson.*`.
 Available as `spin.cmds.build.*`:
 
 ```
-  sdist    📦 Build a source distribution in `dist/`
+sdist      📦 Build a source distribution in `dist/`
 ```
 
 ### [pip](https://pip.pypa.io) (Package Installer for Python)
@@ -174,7 +174,15 @@ development workflow.
 Available as `spin.cmds.pip.*`:
 
 ```
-  install  💽 Build and install package using pip.
+install    💽 Build and install package using pip.
+```
+
+### Meta (commands that operate on commands)
+
+Available as `spin.cmds.meta.*`:
+
+```
+introspect 🔍 Print a command's location and source code
 ```
 
 ## 🧪 Custom commands
@@ -310,6 +318,13 @@ fc-cache -f -v
 nox -s test
 ```
 
+Other examples:
+
+```
+nox -s test -- -v
+nox -s test -- -v spin/tests/test_meson.py
+```
+
 ## History
 
 The `dev.py` tool was [proposed for SciPy](https://github.com/scipy/scipy/issues/15489) by Ralf Gommers and [implemented](https://github.com/scipy/scipy/pull/15959) by Sayantika Banik, Eduardo Naufel Schettino, and Ralf Gommers (also see [Sayantika's blog post](https://labs.quansight.org/blog/the-evolution-of-the-scipy-developer-cli)).

{spin-0.11 → spin-0.12}/spin.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ spin.egg-info/top_level.txt
 spin/cmds/__init__.py
 spin/cmds/build.py
 spin/cmds/meson.py
+spin/cmds/meta.py
 spin/cmds/pip.py
 spin/cmds/util.py
 spin/tests/conftest.py

{spin-0.11 → spin-0.12}/spin.egg-info/requires.txt

@@ -11,4 +11,4 @@ tomli
 changelist==0.5
 
 [lint]
-pre-commit==3.7.1
+pre-commit==3.8.0

spin-0.11/spin/cmds/build.py

@@ -1,9 +0,0 @@
-import click
-
-from .util import run
-
-
-@click.command()
-def sdist():
-    """📦 Build a source distribution in `dist/`"""
-    run(["pyproject-build", ".", "--sdist"])

spin-0.11/spin/tests/test_meson.py

@@ -1,116 +0,0 @@
-import os
-import sys
-import tempfile
-from os.path import join as pjoin
-from os.path import normpath
-
-import pytest
-
-from spin.cmds import meson
-from spin.containers import DotDict
-
-
-def make_paths(root, paths):
-    for p in paths:
-        os.makedirs(pjoin(root, p.lstrip("/")))
-
-
-def test_path_discovery(monkeypatch):
-    version = sys.version_info
-    X, Y = version.major, version.minor
-
-    # With multiple site-packages, choose the one that
-    # matches the current Python version
-    with tempfile.TemporaryDirectory() as d:
-        with monkeypatch.context() as m:
-            install_dir = pjoin(d, "build-install")
-            m.setattr(meson, "install_dir", install_dir)
-
-            make_paths(
-                install_dir,
-                [
-                    f"/usr/lib64/python{X}.{Y}/site-packages",
-                    f"/usr/lib64/python{X}.{Y + 1}/site-packages",
-                    f"/usr/lib64/python{X}.{Y + 2}/site-packages",
-                ],
-            )
-            assert (
-                normpath(f"/usr/lib64/python{X}.{Y}/site-packages")
-                in meson._get_site_packages()
-            )
-
-    # Debian uses dist-packages
-    with tempfile.TemporaryDirectory() as d:
-        with monkeypatch.context() as m:
-            install_dir = pjoin(d, "build-install")
-            m.setattr(meson, "install_dir", install_dir)
-
-            make_paths(
-                install_dir,
-                [
-                    f"/usr/lib64/python{X}.{Y}/dist-packages",
-                ],
-            )
-            assert (
-                normpath(f"/usr/lib64/python{X}.{Y}/dist-packages")
-                in meson._get_site_packages()
-            )
-
-    # If there is no version information in site-packages,
-    # use whatever site-packages can be found
-    with tempfile.TemporaryDirectory() as d:
-        with monkeypatch.context() as m:
-            install_dir = pjoin(d, "build-install")
-            m.setattr(meson, "install_dir", install_dir)
-
-            make_paths(install_dir, ["/Python3/site-packages"])
-            assert normpath("/Python3/site-packages") in meson._get_site_packages()
-
-    # Raise if no site-package directory present
-    with tempfile.TemporaryDirectory() as d:
-        with monkeypatch.context() as m:
-            install_dir = pjoin(d, "build-install")
-            m.setattr(meson, "install_dir", install_dir)
-
-            with pytest.raises(FileNotFoundError):
-                meson._get_site_packages()
-
-    # If there are multiple site-package paths, but without version information,
-    # refuse the temptation to guess
-    with tempfile.TemporaryDirectory() as d:
-        install_dir = pjoin(d, "build-install")
-        make_paths(
-            install_dir, ["/Python3/x/site-packages", "/Python3/y/site-packages"]
-        )
-        with pytest.raises(FileNotFoundError):
-            meson._get_site_packages()
-
-    # Multiple site-package paths found, but none that matches our Python
-    with tempfile.TemporaryDirectory() as d:
-        with monkeypatch.context() as m:
-            install_dir = pjoin(d, "build-install")
-            m.setattr(meson, "install_dir", install_dir)
-
-            make_paths(
-                install_dir,
-                [
-                    f"/usr/lib64/python{X}.{Y + 1}/site-packages",
-                    f"/usr/lib64/python{X}.{Y + 2}/site-packages",
-                ],
-            )
-            with pytest.raises(FileNotFoundError):
-                meson._get_site_packages()
-
-
-def test_meson_cli_discovery(monkeypatch):
-    config0 = DotDict({"tool": {"spin": {"meson": {"cli": "~/envs/py311/bin/meson"}}}})
-    config1 = DotDict(
-        {"tool": {"spin": {"meson": {"cli": "~/envs/py311/bin/meson.py"}}}}
-    )
-
-    with monkeypatch.context() as m:
-        m.setattr(meson, "get_config", lambda: config0)
-        assert meson._meson_cli()[0] == os.path.expanduser("~/envs/py311/bin/meson")
-
-        m.setattr(meson, "get_config", lambda: config1)
-        assert meson._meson_cli()[0] == sys.executable