Add introspection command (#228)

Partially addresses #226

Author: stefanv

README.md

@@ -86,23 +86,23 @@ 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)
 
 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

example_pkg/pyproject.toml

@@ -47,6 +47,9 @@ package = 'example_pkg'
 "Pip" = [
   "spin.cmds.pip.install"
 ]
+"Meta" = [
+  "spin.cmds.meta.introspect"
+]
 
 [tool.spin.kwargs]
 ".spin/cmds.py:example" = {"test" = "default override", "default_kwd" = 3}

spin/__main__.py

@@ -132,10 +132,14 @@ def group(ctx):
 
                 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/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")