spin 0.12__tar.gz → 0.13__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: spin
-Version: 0.12
+Version: 0.13
 Summary: Developer tool for scientific Python libraries
 Maintainer-email: Scientific Python <spin@discuss.scientific-python.org>
 License: BSD 3-Clause License
@@ -46,6 +46,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
@@ -55,7 +56,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.8.0; extra == "lint"
+Requires-Dist: pre-commit==4.0.1; extra == "lint"
 Provides-Extra: dev
 Requires-Dist: changelist==0.5; extra == "dev"
 
@@ -75,6 +76,28 @@ When many of the build and installation commands changed, it made sense to abstr
 _Note:_ We now have experimental builds for editable installs.
 Most of the Meson commands listed below should work "out of the box" for those.
 
+<!--TOC-->
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+  - [Command sections](#command-sections)
+- [Running](#running)
+- [Built-in commands](#built-in-commands)
+  - [Meson](#meson)
+  - [Build (PEP 517 builder)](#build-pep-517-builder)
+  - [pip (Package Installer for Python)](#pip-package-installer-for-python)
+  - [Meta (commands that operate on commands)](#meta-commands-that-operate-on-commands)
+- [🧪 Custom commands](#-custom-commands)
+  - [Configuration](#configuration-1)
+  - [Argument overrides](#argument-overrides)
+  - [Advanced: adding arguments to built-in commands](#advanced-adding-arguments-to-built-in-commands)
+  - [Advanced: override Meson CLI](#advanced-override-meson-cli)
+- [FAQ](#faq)
+- [For contributors](#for-contributors)
+- [History](#history)
+
+<!--TOC-->
+
 ## Installation
 
 ```
@@ -240,52 +263,39 @@ click options or function keywords:
 
 ### 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.
-For this, we have to use an internal Click concept called a [context](https://click.palletsprojects.com/en/8.1.x/complex/#contexts).
-Fortunately, we don't need to know anything about contexts other than that they allow us to execute commands within commands.
+Instead of rewriting a command from scratch, a project may simply want to add a flag to an existing `spin` command, or perhaps do some pre- or post-processing.
+For this purpose, we provide the `spin.util.extend_cmd` decorator.
 
-We proceed by duplicating the function header of the existing command, and adding our own flag:
+Here, we show how to add a `--extra` flag to the existing `build` function:
 
 ```python
-from spin.cmds import meson
-
-# Take this from the built-in implementation, in `spin.cmds.meson.build`:
-
+import spin
 
-@click.command()
-@click.argument("meson_args", nargs=-1)
-@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 all build output, even installation"
-)
-
-# This is our new option
-@click.option("--custom-arg/--no-custom-arg")
 
-# This tells spin that we will need a context, which we
-# can use to invoke the built-in command
-@click.pass_context
+@click.option("-e", "--extra", help="Extra test flag")
+@spin.util.extend_command(spin.cmds.meson.build)
+def build_extend(*, parent_callback, extra=None, **kwargs):
+    """
+    This version of build also provides the EXTRA flag, that can be used
+    to specify an extra integer argument.
+    """
+    print(f"Preparing for build with {extra=}")
+    parent_callback(**kwargs)
+    print("Finalizing build...")
+```
 
-# This is the original function signature, plus our new flag
-def build(ctx, meson_args, jobs=None, clean=False, verbose=False, custom_arg=False):
-    """Docstring goes here. You may want to copy and customize the original."""
+Note that `build_extend` receives the parent command callback (the function the `build` command would have executed) as its first argument.
 
-    # Do something with the new option
-    print("The value of custom arg is:", custom_arg)
+The matching entry in `pyproject.toml` is:
 
-    # The spin `build` command doesn't know anything about `custom_arg`,
-    # so don't send it on.
-    del ctx.params["custom_arg"]
+```
+"Build" = [".spin/cmds.py:build_extend"]
+```
 
-    # Call the built-in `build` command, passing along
-    # all arguments and options.
-    ctx.forward(meson.build)
+The `extend_cmd` decorator also accepts a `doc` argument, for setting the new command's `--help` description.
+The function documentation ("This version of build...") is also appended.
 
-    # Also see:
-    # - https://click.palletsprojects.com/en/8.1.x/api/#click.Context.forward
-    # - https://click.palletsprojects.com/en/8.1.x/api/#click.Context.invoke
-```
+Finally, `remove_args` is a tuple of arguments that are not inherited from the original command.
 
 ### Advanced: override Meson CLI
 

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

@@ -14,6 +14,28 @@ When many of the build and installation commands changed, it made sense to abstr
 _Note:_ We now have experimental builds for editable installs.
 Most of the Meson commands listed below should work "out of the box" for those.
 
+<!--TOC-->
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+  - [Command sections](#command-sections)
+- [Running](#running)
+- [Built-in commands](#built-in-commands)
+  - [Meson](#meson)
+  - [Build (PEP 517 builder)](#build-pep-517-builder)
+  - [pip (Package Installer for Python)](#pip-package-installer-for-python)
+  - [Meta (commands that operate on commands)](#meta-commands-that-operate-on-commands)
+- [🧪 Custom commands](#-custom-commands)
+  - [Configuration](#configuration-1)
+  - [Argument overrides](#argument-overrides)
+  - [Advanced: adding arguments to built-in commands](#advanced-adding-arguments-to-built-in-commands)
+  - [Advanced: override Meson CLI](#advanced-override-meson-cli)
+- [FAQ](#faq)
+- [For contributors](#for-contributors)
+- [History](#history)
+
+<!--TOC-->
+
 ## Installation
 
 ```
@@ -179,52 +201,39 @@ click options or function keywords:
 
 ### 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.
-For this, we have to use an internal Click concept called a [context](https://click.palletsprojects.com/en/8.1.x/complex/#contexts).
-Fortunately, we don't need to know anything about contexts other than that they allow us to execute commands within commands.
+Instead of rewriting a command from scratch, a project may simply want to add a flag to an existing `spin` command, or perhaps do some pre- or post-processing.
+For this purpose, we provide the `spin.util.extend_cmd` decorator.
 
-We proceed by duplicating the function header of the existing command, and adding our own flag:
+Here, we show how to add a `--extra` flag to the existing `build` function:
 
 ```python
-from spin.cmds import meson
-
-# Take this from the built-in implementation, in `spin.cmds.meson.build`:
-
+import spin
 
-@click.command()
-@click.argument("meson_args", nargs=-1)
-@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 all build output, even installation"
-)
-
-# This is our new option
-@click.option("--custom-arg/--no-custom-arg")
 
-# This tells spin that we will need a context, which we
-# can use to invoke the built-in command
-@click.pass_context
+@click.option("-e", "--extra", help="Extra test flag")
+@spin.util.extend_command(spin.cmds.meson.build)
+def build_extend(*, parent_callback, extra=None, **kwargs):
+    """
+    This version of build also provides the EXTRA flag, that can be used
+    to specify an extra integer argument.
+    """
+    print(f"Preparing for build with {extra=}")
+    parent_callback(**kwargs)
+    print("Finalizing build...")
+```
 
-# This is the original function signature, plus our new flag
-def build(ctx, meson_args, jobs=None, clean=False, verbose=False, custom_arg=False):
-    """Docstring goes here. You may want to copy and customize the original."""
+Note that `build_extend` receives the parent command callback (the function the `build` command would have executed) as its first argument.
 
-    # Do something with the new option
-    print("The value of custom arg is:", custom_arg)
+The matching entry in `pyproject.toml` is:
 
-    # The spin `build` command doesn't know anything about `custom_arg`,
-    # so don't send it on.
-    del ctx.params["custom_arg"]
+```
+"Build" = [".spin/cmds.py:build_extend"]
+```
 
-    # Call the built-in `build` command, passing along
-    # all arguments and options.
-    ctx.forward(meson.build)
+The `extend_cmd` decorator also accepts a `doc` argument, for setting the new command's `--help` description.
+The function documentation ("This version of build...") is also appended.
 
-    # Also see:
-    # - https://click.palletsprojects.com/en/8.1.x/api/#click.Context.forward
-    # - https://click.palletsprojects.com/en/8.1.x/api/#click.Context.invoke
-```
+Finally, `remove_args` is a tuple of arguments that are not inherited from the original command.
 
 ### Advanced: override Meson CLI
 

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

@@ -20,6 +20,7 @@ classifiers = [
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3 :: Only",
 ]
 dependencies = [
@@ -34,7 +35,7 @@ dynamic = ['version']
 spin = "spin.__main__:main"
 
 [project.optional-dependencies]
-lint = ["pre-commit == 3.8.0"]
+lint = ["pre-commit == 4.0.1"]
 dev = ["changelist == 0.5"]
 
 [project.urls]

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

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

@@ -131,6 +131,8 @@ def main():
     }
     cmd_default_kwargs = toml_config.get("tool.spin.kwargs", {})
 
+    custom_module_cache = {}
+
     for section, cmds in config_cmds.items():
         for cmd in cmds:
             if cmd not in commands:
@@ -147,11 +149,17 @@ def main():
                 else:
                     try:
                         path, func = cmd.split(":")
-                        spec = importlib.util.spec_from_file_location(
-                            "custom_mod", path
-                        )
-                        mod = importlib.util.module_from_spec(spec)
-                        spec.loader.exec_module(mod)
+
+                        if path not in custom_module_cache:
+                            spec = importlib.util.spec_from_file_location(
+                                "custom_mod", path
+                            )
+                            mod = importlib.util.module_from_spec(spec)
+                            spec.loader.exec_module(mod)
+                            custom_module_cache[path] = mod
+                        else:
+                            mod = custom_module_cache[path]
+
                     except FileNotFoundError:
                         print(
                             f"!! Could not find file `{path}` to load custom command `{cmd}`.\n"

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

@@ -4,6 +4,7 @@ import json
 import os
 import re
 import shutil
+import signal
 import sys
 from enum import Enum
 from pathlib import Path
@@ -230,18 +231,30 @@ def _check_coverage_tool_installation(coverage_type: GcovReportFormat, build_dir
         )
 
 
+if sys.platform.startswith("win"):
+    DEFAULT_PREFIX = "C:/"
+else:
+    DEFAULT_PREFIX = "/usr"
+
 build_dir_option = click.option(
     "-C",
     "--build-dir",
     default="build",
     show_envvar=True,
+    metavar="BUILD_DIR",
     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(
+    "-j",
+    "--jobs",
+    metavar="N_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"
@@ -251,6 +264,13 @@ build_dir_option = click.option(
     is_flag=True,
     help="Enable C code coverage using `gcov`. Use `spin test --gcov` to generate reports.",
 )
+@click.option(
+    "--prefix",
+    help="The build prefix, passed directly to meson.",
+    type=str,
+    metavar="PREFIX",
+    default=DEFAULT_PREFIX,
+)
 @click.argument("meson_args", nargs=-1)
 @build_dir_option
 def build(
@@ -262,6 +282,7 @@ def build(
     gcov=False,
     quiet=False,
     build_dir=None,
+    prefix=None,
 ):
     """🔧 Build package with Meson/ninja
 
@@ -312,7 +333,7 @@ def build(
     if gcov:
         meson_args = meson_args + ["-Db_coverage=true"]
 
-    setup_cmd = _meson_cli() + ["setup", build_dir, "--prefix=/usr"] + meson_args
+    setup_cmd = _meson_cli() + ["setup", build_dir, f"--prefix={prefix}"] + meson_args
 
     if clean:
         print(f"Removing `{build_dir}`")
@@ -480,18 +501,23 @@ def test(
 
     package = cfg.get("tool.spin.package", None)
     if package is None:
-        print(
-            "Please specify `package = packagename` under `tool.spin` section of `pyproject.toml`"
+        click.secho(
+            "Please specify `package = packagename` under `tool.spin` section of `pyproject.toml`",
+            fg="bright_red",
         )
         raise SystemExit(1)
 
     # User did not specify what to test, so we test
-    # the full package
+    # the full package, or the tests directory if that is present
     if not (pytest_args or tests):
-        pytest_args = ("--pyargs", package)
+        if os.path.isdir("./tests"):
+            # tests dir exists, presuming you are not shipping tests
+            # with your package, and prefer to run those instead
+            pytest_args = (os.path.abspath("./tests"),)
+        else:
+            pytest_args = ("--pyargs", package)
     elif tests:
         if (os.path.sep in tests) or ("/" in tests):
-            # Tests specified as file path
             pytest_args = pytest_args + (tests,)
         else:
             # Otherwise tests given as modules
@@ -503,7 +529,7 @@ def test(
             "Error: cannot generate coverage report for editable installs",
             fg="bright_red",
         )
-        raise SystemExit(-1)
+        raise SystemExit(1)
 
     build_cmd = _get_configured_command("build")
     if build_cmd:
@@ -536,9 +562,6 @@ def test(
     if (n_jobs != "1") and ("-n" not in pytest_args):
         pytest_args = ("-n", str(n_jobs)) + pytest_args
 
-    if not any("--import-mode" in arg for arg in pytest_args):
-        pytest_args = ("--import-mode=importlib",) + pytest_args
-
     if verbose:
         pytest_args = ("-v",) + pytest_args
 
@@ -564,8 +587,11 @@ def test(
     if not os.path.exists(install_dir):
         os.mkdir(install_dir)
 
+    # Unless we have a src layout, we need to switch away from the current directory into build install to avoid importing ./package instead of the built package.
+    test_path = site_path if not os.path.isdir("./src") else None
+
     cwd = os.getcwd()
-    pytest_p = _run(cmd + list(pytest_args), cwd=site_path)
+    pytest_p = _run(cmd + list(pytest_args), cwd=test_path)
     os.chdir(cwd)
 
     if gcov:
@@ -607,7 +633,9 @@ def test(
 
 
 @click.command()
-@click.option("--code", "-c", help="Python program passed in as a string")
+@click.option(
+    "--code", "-c", metavar="CODE", help="Python program passed in as a string"
+)
 @click.argument("gdb_args", nargs=-1)
 @build_dir_option
 @click.pass_context
@@ -664,7 +692,7 @@ def gdb(ctx, *, code, gdb_args, build_dir):
 @click.argument("ipython_args", nargs=-1)
 @build_dir_option
 @click.pass_context
-def ipython(ctx, *, ipython_args, build_dir):
+def ipython(ctx, *, ipython_args, build_dir, pre_import=""):
     """💻 Launch IPython shell with PYTHONPATH set
 
     IPYTHON_ARGS are passed through directly to IPython, e.g.:
@@ -674,13 +702,15 @@ def ipython(ctx, *, ipython_args, build_dir):
     build_cmd = _get_configured_command("build")
     if build_cmd:
         click.secho(
-            "Invoking `build` prior to invoking ipython:", bold=True, fg="bright_green"
+            "Invoking `build` prior to launching ipython:", bold=True, fg="bright_green"
         )
         ctx.invoke(build_cmd, build_dir=build_dir)
 
     p = _set_pythonpath(build_dir)
     if p:
         print(f'💻 Launching IPython with PYTHONPATH="{p}"')
+    if pre_import:
+        ipython_args = (f"--TerminalIPythonApp.exec_lines={pre_import}",) + ipython_args
     _run(["ipython", "--ignore-cwd"] + list(ipython_args), replace=True)
 
 
@@ -798,7 +828,27 @@ def run(ctx, *, args, build_dir=None):
             cmd_args = ["bash", "-c", cmd_args]
 
     _set_pythonpath(build_dir, quiet=True)
-    p = _run(cmd_args, echo=False, shell=shell, sys_exit=False)
+
+    is_windows = sys.platform == "win32"
+
+    if not is_windows:
+        # Let the subprocess handle its own signals
+        # Except on Windows, where it already seems to work as intended,
+        # and `preexec_fn` is not supported
+        signal.signal(signal.SIGINT, signal.SIG_IGN)
+
+    def attach_sigint():
+        # Reset SIGINT handler to default
+        signal.signal(signal.SIGINT, signal.SIG_DFL)
+
+    # --- launch subprocess ---
+    p = _run(
+        cmd_args,
+        echo=False,
+        shell=shell,
+        sys_exit=False,
+        preexec_fn=None if is_windows else attach_sigint,
+    )
 
     # Is the user trying to run a Python script, without calling the Python interpreter?
     executable = args[0]
@@ -834,7 +884,13 @@ def run(ctx, *, args, build_dir=None):
     default=True,
     help="Sphinx gallery: enable/disable plots",
 )
-@click.option("--jobs", "-j", default="auto", help="Number of parallel build jobs")
+@click.option(
+    "--jobs",
+    "-j",
+    default="auto",
+    metavar="N_JOBS",
+    help="Number of parallel build jobs",
+)
 @build_dir_option
 @click.pass_context
 def docs(
@@ -937,7 +993,9 @@ def docs(
 
 
 @click.command()
-@click.option("--code", "-c", help="Python program passed in as a string")
+@click.option(
+    "--code", "-c", metavar="CODE", help="Python program passed in as a string"
+)
 @click.argument("lldb_args", nargs=-1)
 @build_dir_option
 @click.pass_context

{spin-0.12 → spin-0.13}/spin/cmds/meta.py

@@ -29,7 +29,11 @@ def introspect(*, cmd):
 
     cmd_func = cmds[cmd]
     try:
-        code = inspect.getsource(cmd_func.callback)
+        if hasattr(cmd_func.callback, "_parent"):
+            # `util.extend_command` was used
+            code = inspect.getsource(cmd_func.callback._parent)
+        else:
+            code = inspect.getsource(cmd_func.callback)
     except TypeError:
         # Perhaps a partial, try again
         code = inspect.getsource(cmd_func.callback.func)