DEV: add spin bench command for local benchmarks

.spin/cmds.py

@@ -1,5 +1,30 @@
+import os
+import sys
+
 import click
 import spin
+from spin.cmds import meson
+
+
+@click.command()
+@click.option('--tests', '-t', multiple=True,
+              help='Select benchmarks by name or regular expression.')
+@meson.build_dir_option
+@click.pass_context
+def bench(ctx, tests, build_dir):
+    """Run benchmarks against the local build without saving results."""
+    args = [sys.executable, '-m', 'asv', 'run', '--python=same',
+            '--dry-run', '--show-stderr']
+    for test in tests:
+        args.extend(['--bench', test])
+    ctx.invoke(meson.build, build_dir=build_dir)
+    meson._set_pythonpath(build_dir)
+    env = os.environ.copy()
+    # ASV removes PYTHONPATH unless it is explicitly passed this way.
+    if env.get('PYTHONPATH'):
+        env['ASV_PYTHONPATH'] = env['PYTHONPATH']
+    spin.util.run(args, env=env)
+
 
 @click.command()
 @click.option(

doc/source/dev/running_the_benchmarks.md

@@ -4,42 +4,46 @@ This document outlines how to setup and run the benchmarks using [asv](https://a
 
 ## Running the benchmarks
 
-To run the benchmarks with ``asv``, simply enter:
+With the development environment activated, register your machine once:
 
 ```shell
-asv run
+asv machine --yes
 ```
 
-## Viewing the results
+Then run:
 
-There are two steps to viewing the results locally. The results need to be published and the launched in a local web browser.
+```shell
+spin bench
+```
 
-To publish the results use:
+This builds the local checkout and runs the benchmarks against that build,
+including uncommitted changes. It uses the current Python environment and
+does not save results. Because it is a dry run, the timings are only a rough guide and are not meant to be compared across sessions or machines. To select benchmarks by name or regular expression:
 
 ```shell
-asv publish
+spin bench -t Npv2D.time_broadcast
 ```
 
-And then to view the results:
+To benchmark committed revisions and save results for publishing, use ASV:
 
 ```shell
-asv preview
+asv run
 ```
 
-This will launch a local web browser from which you can view the results
+## Viewing the results
 
-## Dry runs
+There are two steps to viewing the results locally. The results need to be published and then launched in a local web browser.
 
-One common use case is to use ``asv`` in development, there are several useful flags that should be used:
+To publish the results use:
 
 ```shell
-asv --python=same --quick --dry-run
+asv publish
 ```
 
-We are adding three flags, these flags are:
+And then to view the results:
 
-1. `--python=same` uses the same environment as your development environment (saves time to avoid building environments)
-2. `--quick` only runs the benchmarks once
-3. `--dry-run` to not save the results of the benchmarks
+```shell
+asv preview
+```
 
-These can be useful for getting quick feedback during development, but should not be used as anything other than a rough guide.
+This will launch a local web browser from which you can view the results

pyproject.toml

@@ -101,6 +101,9 @@ package = 'numpy_financial'
 "Documentation" = [
   "spin.cmds.meson.docs"
 ]
+"Benchmarks" = [
+  ".spin/cmds.py:bench"
+]
 "Environments" = [
   "spin.cmds.meson.shell",
   "spin.cmds.meson.ipython",