spin 0.7__tar.gz → 0.9__tar.gz

{spin-0.7 → 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.7/spin.egg-info → spin-0.9}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.1
 Name: spin
-Version: 0.7
+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
@@ -41,40 +41,40 @@ Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 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 :: Only
-Requires-Python: >=3.7
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 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.4.0; extra == "lint"
+Requires-Dist: pre-commit==3.7.0; extra == "lint"
 Provides-Extra: dev
-Requires-Dist: changelist==0.3; extra == "dev"
+Requires-Dist: changelist==0.5; extra == "dev"
 
 # 💫 Scientific Python INcantations (`spin`)
 
 ## A developer tool for scientific Python libraries
 
-**NOTE:** If you are looking for `devpy`, this is it! We had to rename
-the package to publish it on PyPi.
-
 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
 
 ```
@@ -83,9 +83,10 @@ pip install spin
 
 ## Configuration
 
-Settings are in your project's `pyproject.toml`.
+Settings are stored in `.spin.toml`, `spin.toml`, or your project's `pyproject.toml`.
 As an example, see the `[tool.spin]` section of [an example `pyproject.toml`](https://github.com/scientific-python/spin/blob/main/example_pkg/pyproject.toml).
 
+The `[project]` section should contain `name`.
 The `[tool.spin]` section should contain:
 
 ```
@@ -143,6 +144,8 @@ python -m spin
 
 ### [Meson](https://meson-python.readthedocs.io)
 
+Available as `spin.cmds.meson.*`.
+
 ```
   build    🔧 Build package with Meson/ninja and install to `build-install`
   ipython  💻 Launch IPython shell with PYTHONPATH set
@@ -151,17 +154,32 @@ python -m spin
   test     🔧 Run pytest
   run      🏁 Run a shell command with PYTHONPATH set
   docs     📖 Build Sphinx documentation
-  gdb  👾 Execute a Python snippet with GDB
+  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)
 
-`spin` was started with Meson in mind, but we're working on expanding commands for PEP 517 `build`.
+Available as `spin.cmds.build.*`:
 
 ```
   sdist    📦 Build a source distribution in `dist/`
 ```
 
+### [pip](https://pip.pypa.io) (Package Installer for Python)
+
+`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.*`:
+
+```
+  install  💽 Build and install package using pip.
+```
+
 ## 🧪 Custom commands
 
 `spin` can invoke custom commands. These commands define their own arguments, and have access to the `pyproject.toml` file for further configuration.
@@ -192,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.
@@ -251,6 +292,27 @@ Meson CLI can be set in `pyproject.toml`:
 cli = 'path/to/custom/meson'
 ```
 
+## FAQ
+
+- Running `spin`, the emojis in the command list don't show up.
+
+Your terminal font may not include emoji characters. E.g., if you use
+noto on Arch Linux the emojis are installed separately:
+
+```sh
+sudo pacman -S noto-fonts-emoji
+fc-cache -f -v
+```
+
+## For contributors
+
+`spin` development happens on GitHub at [scientific-python/spin](https://github.com/scientific-python/spin).
+`spin` tests are invoked using:
+
+```
+nox -s test
+```
+
 ## 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.7 → spin-0.9}/README.md

@@ -2,18 +2,18 @@
 
 ## A developer tool for scientific Python libraries
 
-**NOTE:** If you are looking for `devpy`, this is it! We had to rename
-the package to publish it on PyPi.
-
 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
 
 ```
@@ -22,9 +22,10 @@ pip install spin
 
 ## Configuration
 
-Settings are in your project's `pyproject.toml`.
+Settings are stored in `.spin.toml`, `spin.toml`, or your project's `pyproject.toml`.
 As an example, see the `[tool.spin]` section of [an example `pyproject.toml`](https://github.com/scientific-python/spin/blob/main/example_pkg/pyproject.toml).
 
+The `[project]` section should contain `name`.
 The `[tool.spin]` section should contain:
 
 ```
@@ -82,6 +83,8 @@ python -m spin
 
 ### [Meson](https://meson-python.readthedocs.io)
 
+Available as `spin.cmds.meson.*`.
+
 ```
   build    🔧 Build package with Meson/ninja and install to `build-install`
   ipython  💻 Launch IPython shell with PYTHONPATH set
@@ -90,17 +93,32 @@ python -m spin
   test     🔧 Run pytest
   run      🏁 Run a shell command with PYTHONPATH set
   docs     📖 Build Sphinx documentation
-  gdb  👾 Execute a Python snippet with GDB
+  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)
 
-`spin` was started with Meson in mind, but we're working on expanding commands for PEP 517 `build`.
+Available as `spin.cmds.build.*`:
 
 ```
   sdist    📦 Build a source distribution in `dist/`
 ```
 
+### [pip](https://pip.pypa.io) (Package Installer for Python)
+
+`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.*`:
+
+```
+  install  💽 Build and install package using pip.
+```
+
 ## 🧪 Custom commands
 
 `spin` can invoke custom commands. These commands define their own arguments, and have access to the `pyproject.toml` file for further configuration.
@@ -131,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.
@@ -190,6 +231,27 @@ Meson CLI can be set in `pyproject.toml`:
 cli = 'path/to/custom/meson'
 ```
 
+## FAQ
+
+- Running `spin`, the emojis in the command list don't show up.
+
+Your terminal font may not include emoji characters. E.g., if you use
+noto on Arch Linux the emojis are installed separately:
+
+```sh
+sudo pacman -S noto-fonts-emoji
+fc-cache -f -v
+```
+
+## For contributors
+
+`spin` development happens on GitHub at [scientific-python/spin](https://github.com/scientific-python/spin).
+`spin` tests are invoked using:
+
+```
+nox -s test
+```
+
 ## 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.7 → spin-0.9}/pyproject.toml

@@ -1,7 +1,6 @@
 [project]
 name = "spin"
-version = "0.7"
-requires-python = ">=3.7"
+requires-python = ">=3.8"
 description = "Developer tool for scientific Python libraries"
 readme = "README.md"
 license = {file = "LICENSE"}
@@ -16,7 +15,6 @@ classifiers = [
   "License :: OSI Approved :: BSD License",
   "Operating System :: OS Independent",
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.7",
   "Programming Language :: Python :: 3.8",
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
@@ -27,19 +25,24 @@ classifiers = [
 dependencies = [
   "click",
   "tomli; python_version < '3.11'",
-  "colorama; platform_system == 'Windows'"
+  "colorama; platform_system == 'Windows'",
+  "importlib_metadata >= 7"
 ]
+dynamic = ['version']
 
 [project.scripts]
 spin = "spin.__main__:main"
 
 [project.optional-dependencies]
-lint = ["pre-commit == 3.4.0"]
-dev = ["changelist == 0.3"]
+lint = ["pre-commit == 3.7.0"]
+dev = ["changelist == 0.5"]
 
 [project.urls]
 homepage = "https://github.com/scientific-python/spin"
 
+[tool.setuptools.dynamic.version]
+attr = 'spin.__version__'
+
 [tool.setuptools.packages.find]
 include = ["spin*"]
 
@@ -50,7 +53,7 @@ filterwarnings = [
 
 [tool.ruff]
 line-length = 88
-target-version = "py37"
+target-version = "py38"
 select = [
     "C",
     "E",

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

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

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

@@ -1,3 +1,4 @@
+import collections
 import importlib
 import importlib.util
 import os
@@ -5,6 +6,7 @@ import sys
 
 import click
 
+from spin import __version__
 from spin import cmds as _cmds
 from spin.color_format import ColorHelpFormatter
 from spin.containers import DotDict
@@ -19,35 +21,64 @@ click.Context.formatter_class = ColorHelpFormatter
 
 
 def main():
-    if not os.path.exists("pyproject.toml"):
-        print("Error: cannot find [pyproject.toml]")
-        sys.exit(1)
-
-    with open("pyproject.toml", "rb") as f:
-        try:
-            toml_config = tomllib.load(f)
-        except tomllib.TOMLDecodeError:
-            print("Cannot parse [pyproject.toml]")
-            sys.exit(1)
-
-    project_config = toml_config.get("project", {})
-
-    try:
-        config = toml_config["tool"]["spin"]
-    except KeyError:
-        print("No configuration found in [pyproject.toml] for [tool.spin]")
-        sys.exit(1)
-
-    proj_name = project_config.get("name", config["package"])
+    # Alias `spin help` to `spin --help`
+    if (len(sys.argv) == 2) and (sys.argv[1] == "help"):
+        sys.argv[1] = "--help"
+
+    def load_toml(filename):
+        if not os.path.exists(filename):
+            return None
+        with open(filename, "rb") as f:
+            try:
+                return tomllib.load(f)
+            except tomllib.TOMLDecodeError:
+                print(f"Error: cannot parse [{filename}]", file=sys.stderr)
+
+    toml_config = collections.ChainMap()
+    toml_config.maps.extend(
+        DotDict(cfg)
+        for filename in (
+            ".spin.toml",
+            "spin.toml",
+            "pyproject.toml",
+        )
+        if (cfg := load_toml(filename))
+    )
+
+    # Basic configuration validation
+    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,
+            )
+
+    proj_name = (
+        toml_config.get("project.name")
+        or spin_config.get("package")
+        or "[unknown project]"
+    )
 
     @click.group(help=f"Developer tool for {proj_name}", cls=SectionedHelpGroup)
+    @click.version_option(__version__, message="%(prog)s %(version)s")
     @click.pass_context
     def group(ctx):
-        ctx.meta["config"] = DotDict(toml_config)
+        ctx.meta["config"] = toml_config
         ctx.meta["commands"] = ctx.command.section_commands
         ctx.show_default = True
 
-    config_cmds = 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):
@@ -63,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:
@@ -102,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)
@@ -109,7 +153,7 @@ def main():
     try:
         group()
     except Exception as e:
-        print(f"{e}; aborting.")
+        print(f"Error: {e}; aborting.", file=sys.stderr)
         sys.exit(1)
 
 

{spin-0.7 → spin-0.9}/spin/cmds/build.py

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