Rewrite with standalone py_discovery from virtualenv

Copy the self-contained py_discovery package extracted from
virtualenv into this repo as its new source. All imports are
relative-only with zero virtualenv dependencies. Tests rewritten
to import from py_discovery directly.

Tooling updated to follow the pytest-env pattern:
- hatchling + hatch-vcs build
- tox.toml with tox-uv
- ruff for format/lint
- GitHub Actions with setup-uv
- Diataxis docs with furo theme
- ReadTheDocs via uv/tox

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: gaborbernat

.github/workflows/check.yaml

@@ -0,0 +1,51 @@
+name: check
+on:
+  workflow_dispatch:
+  push:
+    branches: ["main"]
+    tags-ignore: ["**"]
+  pull_request:
+  schedule:
+    - cron: "0 8 * * *"
+
+concurrency:
+  group: check-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        env:
+          - "3.14"
+          - "3.13"
+          - "3.12"
+          - "3.11"
+          - "3.10"
+          - type
+          - dev
+          - pkg_meta
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Install tox
+        run: uv tool install --python-preference only-managed --python 3.14 tox --with tox-uv
+      - name: Install Python
+        if: startsWith(matrix.env, '3.') && matrix.env != '3.14'
+        run: uv python install --python-preference only-managed ${{ matrix.env }}
+      - name: Setup test suite
+        run: tox run -vv --notest --skip-missing-interpreters false -e ${{ matrix.env }}
+      - name: Run test suite
+        run: tox run --skip-pkg-install -e ${{ matrix.env }}
+        env:
+          PYTEST_ADDOPTS: "-vv --durations=20"
+          DIFF_AGAINST: HEAD

.github/workflows/check.yml

@@ -0,0 +1,48 @@
+name: Release to PyPI
+on:
+  push:
+    tags: ["*"]
+
+env:
+  dists-artifact-name: python-package-distributions
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build package
+        run: uv build --python 3.14 --python-preference only-managed --sdist --wheel . --out-dir dist
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v6
+        with:
+          name: ${{ env.dists-artifact-name }}
+          path: dist/*
+
+  release:
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/project/py-discovery/${{ github.ref_name }}
+    permissions:
+      id-token: write
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v7
+        with:
+          name: ${{ env.dists-artifact-name }}
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.13.0
+        with:
+          attestations: true

.github/workflows/release.yaml

@@ -1,9 +1,5 @@
-*.py[cod]
-*.swp
-__pycache__
-/src/py_discovery/_version.py
-build
-dist
+*.pyc
 *.egg-info
-.tox
-/.*_cache
+dist/
+.tox/
+/src/py_discovery/_version.py

.github/workflows/release.yml

@@ -1,29 +1,36 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v6.0.0
     hooks:
       - id: end-of-file-fixer
       - id: trailing-whitespace
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: 0.36.1
+    hooks:
+      - id: check-github-workflows
+        args: ["--verbose"]
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.3.0
+    rev: v2.4.1
     hooks:
       - id: codespell
-        args: ["--write-changes"]
-  - repo: https://github.com/tox-dev/tox-ini-fmt
-    rev: "1.3.1"
-    hooks:
-      - id: tox-ini-fmt
-        args: ["-p", "fix"]
+        additional_dependencies: ["tomli>=2.2.1"]
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: "2.2.1"
+    rev: "v2.11.1"
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.6.3"
+    rev: "v0.14.14"
     hooks:
       - id: ruff-format
       - id: ruff
         args: ["--fix", "--unsafe-fixes", "--exit-non-zero-on-fix"]
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: "v3.8.1"
+    hooks:
+      - id: prettier
+        additional_dependencies:
+          - prettier@3.6.2
+          - "@prettier/plugin-xml@3.4.2"
   - repo: meta
     hooks:
       - id: check-hooks-apply

.gitignore

@@ -0,0 +1,8 @@
+version: 2
+build:
+  os: ubuntu-lts-latest
+  tools: {}
+  commands:
+    - curl -LsSf https://astral.sh/uv/install.sh | sh
+    - ~/.local/bin/uv tool install tox --with tox-uv -p 3.14 --managed-python
+    - ~/.local/bin/tox run -e docs --

.pre-commit-config.yaml

@@ -1,40 +1,38 @@
-# noqa: D100
 from __future__ import annotations
 
+from datetime import datetime, timezone
+
 from py_discovery import __version__
 
-project = name = "py_discovery"
 company = "tox-dev"
-copyright = f"{company}"  # noqa: A001
-version, release = __version__, __version__.split("+")[0]
+name = "py-discovery"
+version = ".".join(__version__.split(".")[:2])
+release = __version__
+copyright = f"2024-{datetime.now(tz=timezone.utc).year}, {company}"  # noqa: A001
 
 extensions = [
+    "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.extlinks",
-    "sphinx.ext.autodoc",
-    "sphinx_autodoc_typehints",
-    "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
+    "sphinx_autodoc_typehints",
 ]
-master_doc, source_suffix = "index", ".rst"
-
-html_theme = "furo"
-html_title, html_last_updated_fmt = "py-discovery docs", "%Y-%m-%dT%H:%M:%S"
-pygments_style, pygments_dark_style = "sphinx", "monokai"
-
-autoclass_content, autodoc_typehints = "both", "none"
-autodoc_default_options = {"members": True, "member-order": "bysource", "undoc-members": True, "show-inheritance": True}
-inheritance_alias = {}
 
-extlinks = {
-    "issue": ("https://github.com/tox-dev/py-discovery/issues/%s", "#%s"),
-    "pull": ("https://github.com/tox-dev/py-discovery/pull/%s", "PR #%s"),
-    "user": ("https://github.com/%s", "@%s"),
-}
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
-    "packaging": ("https://packaging.pypa.io/en/latest", None),
 }
 
-nitpicky = True
-nitpick_ignore = []
+templates_path = []
+source_suffix = ".rst"
+exclude_patterns = ["_build"]
+
+main_doc = "index"
+pygments_style = "default"
+always_document_param_types = True
+project = name
+
+html_theme = "furo"
+html_title = project
+html_last_updated_fmt = datetime.now(tz=timezone.utc).isoformat()
+pygments_dark_style = "monokai"
+html_show_sourcelink = False

.readthedocs.yaml

@@ -0,0 +1,30 @@
+How py-discovery works
+=====================
+
+Discovery strategy
+------------------
+
+The :class:`~py_discovery.Builtin` discover searches for Python interpreters in the following order:
+
+1. **Absolute paths** -- if the spec is an absolute path, try it directly.
+2. **``try_first_with``** -- explicit paths to try before anything else.
+3. **Relative paths** -- resolve relative to the current directory.
+4. **Current interpreter** -- the running Python itself.
+5. **Windows registry** (PEP 514) -- on Windows, enumerate registered interpreters.
+6. **PATH search** -- walk ``$PATH`` entries, matching filenames against the spec pattern.
+7. **Version-manager shims** -- resolve pyenv, mise, and asdf shims to real binaries.
+8. **uv-managed Pythons** -- check ``UV_PYTHON_INSTALL_DIR``, ``XDG_DATA_HOME/uv/python``, or the platform default.
+
+Cache sharing
+-------------
+
+``py-discovery`` uses the same on-disk cache layout as virtualenv (``py_info/4/<sha256>.json``), so they share
+cached interpreter metadata. The :class:`~py_discovery.DiskCache` stores results under a configurable root directory
+with file locking via ``filelock``.
+
+Protocol design
+---------------
+
+The cache layer is defined as a :class:`typing.Protocol` (:class:`~py_discovery.PyInfoCache`), allowing custom
+backends without inheriting from any base class. The built-in :class:`~py_discovery.DiskCache` implements this protocol
+using JSON files and ``filelock``.