Add option to build with uv

README.rst

@@ -22,6 +22,11 @@ in the `PEP 518 <https://peps.python.org/pep-0518/>`_ standardized ``pyproject.t
 Jobs can be run on multiple Python versions at once, and independent steps can be
 executed in parallel for faster results.
 
+When installed, `thx` uses the `uv <https://github.com/astral-sh/uv>`_ package
+manager to create virtual environments and install dependencies. The default
+``builder`` setting will auto-detect ``uv`` and fall back to ``pip`` when
+necessary.
+
 Watch `thx` format the codebase, build sphinx docs, run the test and linter suites on
 five Python versions, and generate a final coverage report:
 

docs/config.rst

@@ -103,6 +103,15 @@ The following project-level options are supported in the ``[tool.thx]`` table:
     ``.gitignore`` will not trigger watch behavior, even if specified in
     :attr:`watch_paths`.
 
+.. attribute:: builder
+    :type: Literal['auto', 'pip', 'uv']
+    :value: auto
+
+    Selects the tool used to create and manage virtual environments. When set to
+    ``auto`` (the default), `thx` will prefer ``uv`` if it is available on the
+    system ``PATH`` and fall back to ``pip`` and the standard library ``venv``.
+    Set this to ``uv`` or ``pip`` to force a specific builder. If ``uv`` is
+    requested but not found, `thx` will raise :class:`ConfigError`.
 
 Jobs
 ----

docs/index.rst

@@ -6,6 +6,9 @@
 .. include:: ../README.rst
     :start-after: Demo of thx in watch mode
 
+`thx` will use the `uv <https://github.com/astral-sh/uv>`_ package manager for
+creating virtual environments when it is available.
+
 .. toctree::
     :hidden:
     :maxdepth: 2

thx/config.py

@@ -7,7 +7,7 @@
 import tomli
 from trailrunner.core import project_root
 
-from .types import Config, ConfigError, Job, Version
+from .types import Builder, Config, ConfigError, Job, Version
 
 
 def ensure_dict(value: Any, key: str) -> Dict[str, Any]:
@@ -134,6 +134,15 @@ def load_config(path: Optional[Path] = None) -> Config:
     content = pyproject.read_text()
     data = tomli.loads(content).get("tool", {}).get("thx", {})
 
+    try:
+        builder_str = data.pop("builder", Builder.AUTO.value)
+        builder = Builder(builder_str)
+    except ValueError:
+        raise ConfigError(
+            f"Option tool.thx.builder: invalid value {builder_str!r}; "
+            f"expected one of {', '.join(b.value for b in Builder)}"
+        )
+
     default: List[str] = ensure_listish(data.pop("default", None), "tool.thx.default")
     jobs: List[Job] = parse_jobs(data.pop("jobs", {}))
     versions: List[Version] = sorted(
@@ -170,6 +179,7 @@ def load_config(path: Optional[Path] = None) -> Config:
             requirements=requirements,
             extras=extras,
             watch_paths=watch_paths,
+            builder=builder,
         )
     )