spin 0.8__tar.gz → 0.10__tar.gz

{spin-0.8 → spin-0.10}/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.10}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.1
 Name: spin
-Version: 0.8
+Version: 0.10
 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
 
 ```
@@ -116,7 +120,7 @@ These commands will then be rendered as:
 
 ```
 Build:
-  build  🔧 Build package with Meson/ninja and install
+  build  🔧 Build package with Meson/ninja
   test   🔧 Run tests
 
 Environments:
@@ -143,7 +147,7 @@ python -m spin
 Available as `spin.cmds.meson.*`.
 
 ```
-  build    🔧 Build package with Meson/ninja and install to `build-install`
+  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
@@ -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)
@@ -168,9 +171,6 @@ Available as `spin.cmds.build.*`:
 `pip` allows for editable installs, another common
 development workflow.
 
-Note that, for now, the meson commands above do not work with an
-editable install of the package. We're [working on changing that](https://github.com/scientific-python/spin/pull/141).
-
 Available as `spin.cmds.pip.*`:
 
 ```
@@ -207,6 +207,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 +307,7 @@ fc-cache -f -v
 `spin` tests are invoked using:
 
 ```
-nox -s tests
+nox -s test
 ```
 
 ## History

{spin-0.8 → spin-0.10}/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
 
 ```
@@ -56,7 +59,7 @@ These commands will then be rendered as:
 
 ```
 Build:
-  build  🔧 Build package with Meson/ninja and install
+  build  🔧 Build package with Meson/ninja
   test   🔧 Run tests
 
 Environments:
@@ -83,7 +86,7 @@ python -m spin
 Available as `spin.cmds.meson.*`.
 
 ```
-  build    🔧 Build package with Meson/ninja and install to `build-install`
+  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
@@ -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)
@@ -108,9 +110,6 @@ Available as `spin.cmds.build.*`:
 `pip` allows for editable installs, another common
 development workflow.
 
-Note that, for now, the meson commands above do not work with an
-editable install of the package. We're [working on changing that](https://github.com/scientific-python/spin/pull/141).
-
 Available as `spin.cmds.pip.*`:
 
 ```
@@ -147,6 +146,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 +246,7 @@ fc-cache -f -v
 `spin` tests are invoked using:
 
 ```
-nox -s tests
+nox -s test
 ```
 
 ## History

{spin-0.8 → spin-0.10}/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"
@@ -53,6 +54,8 @@ filterwarnings = [
 [tool.ruff]
 line-length = 88
 target-version = "py38"
+
+[tool.ruff.lint]
 select = [
     "C",
     "E",

{spin-0.8 → spin-0.10}/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.10"
 
 from .cmds import util
 

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

@@ -3,6 +3,8 @@ import importlib
 import importlib.util
 import os
 import sys
+import textwrap
+import traceback
 
 import click
 
@@ -25,10 +27,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 +34,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 +48,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 +80,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 +96,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,14 +136,44 @@ 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)
 
     try:
         group()
-    except Exception as e:
-        error(f"{e}; aborting.")
+    except Exception:
+        click.secho("\n" + traceback.format_exc(limit=-3), fg="red", file=sys.stderr)
+        click.secho(
+            textwrap.dedent(
+                f"""\
+        An internal error has occurred. Please file a bug report at
+
+          https://github.com/scientific-python/spin
+
+        including the above traceback and the following information:
+
+          spin: {__version__}, package: {proj_name}
+
+        Aborting."""
+            ),
+            fg="red",
+            bold=True,
+            file=sys.stderr,
+        )
+        sys.exit(1)
 
 
 if __name__ == "__main__":