developer docs for tskit need to clarify `uv run prek install`

[bhaller]

I'm attempting to work on a PR for tskit for the first time, following the docs at https://tskit.dev/tskit/docs/stable/development.html#getting-started. I've installed meson, ninja, and uv, but have no idea what they are. :-> Next, at https://tskit.dev/tskit/docs/stable/development.html#environment, I am told to run uv run prek install. That fails:

bhaller@glass % uv run prek install
error: Failed to spawn: `prek`
  Caused by: No such file or directory (os error 2)

I have no idea what to do with this. Perhaps this doc could use some clarification/improvement? It's not clear to me whether I actually need to install this or not, since above the doc says "It is not strictly necessary to use uv in order to make small changes...", but now I'm told to do this uv command. I guess I'll forge ahead without this whatever-it-is installed, and see what happens. :->

[petrelharp]

I've installed meson, ninja, and uv, but have no idea what they are. :->

Fair enough, but the first occurence of those in the docs have links to their pages, which do say what they are, so I won't try to fix this.

error: Failed to spawn: prek``

Which directory were you in? I get this error if I'm in the root directory rather than python/. If that's the problem, I've fixed it already in #3428.

[bhaller]

I've installed meson, ninja, and uv, but have no idea what they are. :->

Fair enough, but the first occurence of those in the docs have links to their pages, which do say what they are, so I won't try to fix this.

Yes. I'm just trying to emphasize the learning curve involved here for me to do a simple PR. Given that many developers, like me, have zero experience with any of these tools, and that it isn't really reasonable to say "Step 1: read the docs for meson, ninja, and uv before proceeding", the tskit developer docs need to be sure to help people over the likely hurdles, otherwise people will just bottom out and flail (as I am doing).

error: Failed to spawn: prek``

Which directory were you in? I get this error if I'm in the root directory rather than python/. If that's the problem, I've fixed it already in #3428.

This does seem to be the initial issue, at least. Switching to the python directory, I then get a different error:

bhaller@glass tskit % cd python
bhaller@glass python % uv run prek install
Using CPython 3.14.3 interpreter at: /opt/local/bin/python3
Creating virtual environment at: .venv
  × Failed to build `tskit @ file:///Users/bhaller/Documents/Research/MesserLab/other%20software/tskit/python`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `setuptools.build_meta.build_editable` failed (exit status: 1)

      [stderr]
      Traceback (most recent call last):
        File "/Users/bhaller/Library/Python/3.13/lib/python/site-packages/numpy/_core/__init__.py", line 23, in <module>
          from . import multiarray
        File "/Users/bhaller/Library/Python/3.13/lib/python/site-packages/numpy/_core/multiarray.py", line 10, in <module>
          from . import overrides
        File "/Users/bhaller/Library/Python/3.13/lib/python/site-packages/numpy/_core/overrides.py", line 7, in <module>
          from numpy._core._multiarray_umath import (
              add_docstring,  _get_implementing_args, _ArrayFunctionDispatcher)
      ModuleNotFoundError: No module named 'numpy._core._multiarray_umath'

      During handling of the above exception, another exception occurred:

      Traceback (most recent call last):
        File "/Users/bhaller/Library/Python/3.13/lib/python/site-packages/numpy/__init__.py", line 114, in <module>
          from numpy.__config__ import show_config
        File "/Users/bhaller/Library/Python/3.13/lib/python/site-packages/numpy/__config__.py", line 4, in <module>
          from numpy._core._multiarray_umath import (
          ...<3 lines>...
          )
        File "/Users/bhaller/Library/Python/3.13/lib/python/site-packages/numpy/_core/__init__.py", line 49, in <module>
          raise ImportError(msg)
      ImportError:

      IMPORTANT: PLEASE READ THIS FOR ADVICE ON HOW TO SOLVE THIS ISSUE!

      Importing the numpy C-extensions failed. This error can happen for
      many reasons, often due to issues with your setup or how NumPy was
      installed.

      We have compiled some common reasons and troubleshooting tips at:

          https://numpy.org/devdocs/user/troubleshooting-importerror.html

      Please note and check the following:

        * The Python version is: Python3.14 from "/Users/bhaller/.cache/uv/builds-v0/.tmpTDvm0Q/bin/python"
        * The NumPy version is: "2.2.6"

      and make sure that they are the versions you expect.
      Please carefully study the documentation linked above for further help.

      Original error was: No module named 'numpy._core._multiarray_umath'


      The above exception was the direct cause of the following exception:

      Traceback (most recent call last):
        File "<string>", line 14, in <module>
          requires = get_requires_for_build({})
        File "/opt/local/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/site-packages/setuptools/build_meta.py", line 479, in
      get_requires_for_build_editable
          return self.get_requires_for_build_wheel(config_settings)
                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
        File "/opt/local/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/site-packages/setuptools/build_meta.py", line 333, in
      get_requires_for_build_wheel
          return self._get_build_requires(config_settings, requirements=[])
                 ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/opt/local/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/site-packages/setuptools/build_meta.py", line 301, in
      _get_build_requires
          self.run_setup()
          ~~~~~~~~~~~~~~^^
        File "/opt/local/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/site-packages/setuptools/build_meta.py", line 317, in run_setup
          exec(code, locals())
          ~~~~^^^^^^^^^^^^^^^^
        File "<string>", line 4, in <module>
          sys.path.pop(0)
          ^^^^^^^^
        File "/Users/bhaller/Library/Python/3.13/lib/python/site-packages/numpy/__init__.py", line 119, in <module>
          raise ImportError(msg) from e
      ImportError: Error importing numpy: you should not try to import numpy from
              its source directory; please exit the numpy source tree, and relaunch
              your python interpreter from there.

      hint: This usually indicates a problem with the package or the build environment.

Of course I have no idea what any of this means, either, since I'm not a Python developer.

[bhaller]

It looks like maybe my numpy install is broken. Last time I tried to use python, it was working fine. So, now I guess I get to embark on the adventure of un-installing and re-installing all my Python stuff, for no apparent reason. Sigh.

[petrelharp]

Hm. The point of uv is that it doesn't use any pre-existing stuff (and does this very fast, somehow). So you should not have to un- and re-install everything. Perhaps we should clarify this in the docs.

[petrelharp]

Okay. Could you, from within the python/ directory, do

rm -rf .venv
uv cache clean
uv sync
uv run prek install

and see if the same thing happens?

[bhaller]

Sorry, I didn't see your comment above until just now. I burned down my python install and redid it from scratch. The uv run prek install command inside the python directory now works. (So, maybe uv isn't supposed to depend on any of the pre-existing stuff, but it seems like it does...?) So, since the doc issue about needing to be inside the python subdirectory has been fixed, I think this issue is mostly resolved. Maybe it would be good to clarify this, though:

It's not clear to me whether I actually need to install this or not, since above the doc says "It is not strictly necessary to use uv in order to make small changes...", but now I'm told to do this uv command.

I.e., is uv actually needed or not? Is uv run prek install needed or not? Anyhow, do with this what you will; the main issue here is apparently resolved, so close this if you don't see anything else you want to fix. Thanks!

[bhaller]

(Maybe burning python to the ground wasn't necessary for uv in some way, but it needed to happen anyway since apparently it was corrupted somehow. If it can't load numpy, it ain't worth much. :->)