📝 docs: rewrite docs and fix 3.12 tkinter coverage

Remove virtualenv references, add mermaid diagrams for discovery flow,
shim resolution, cache design, and spec format. Cover all features
including PEP 440 specifiers, free-threaded builds, ISA matching, and
custom cache backends.

Use skipif marker for tkinter test so the function body is excluded
from coverage when tkinter is unavailable (3.12 CI).

Author: gaborbernat

docs/conf.py

@@ -16,6 +16,7 @@
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx_autodoc_typehints",
+    "sphinxcontrib.mermaid",
 ]
 
 intersphinx_mapping = {

docs/explanation.rst

@@ -6,25 +6,123 @@ 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
+.. mermaid::
+
+    flowchart TD
+        Start["Builtin.run()"] --> AbsPath{Is spec an\nabsolute path?}
+        AbsPath -->|Yes| TryAbs["Try path directly"]
+        AbsPath -->|No| TryFirst["try_first_with paths"]
+        TryFirst --> RelPath{Is spec a\nrelative path?}
+        RelPath -->|Yes| TryRel["Resolve relative to cwd"]
+        RelPath -->|No| Current["Current interpreter"]
+        Current --> Win{Windows?}
+        Win -->|Yes| PEP514["PEP 514 registry"]
+        Win -->|No| PATH
+        PEP514 --> PATH["PATH search"]
+        PATH --> Shims["Version-manager shims\n(pyenv / mise / asdf)"]
+        Shims --> UV["uv-managed Pythons"]
+
+        TryAbs --> Verify
+        TryRel --> Verify
+        UV --> Verify
+
+        Verify{{"Verify candidate\n(subprocess call)"}}
+        Verify -->|Satisfies spec| Cache["Cache & return"]
+        Verify -->|No match| Next["Try next candidate"]
+
+Each candidate is verified by running it as a subprocess to collect its metadata (version, architecture, platform,
+sysconfig paths, etc.). Verified interpreters are cached to avoid repeating this subprocess call.
+
+Shim resolution
 ---------------
 
-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``.
+When a spec like ``python3.12`` resolves to a version-manager shim (e.g., ``~/.pyenv/shims/python3.12``),
+py-discovery detects this and resolves it to the real binary:
+
+.. mermaid::
+
+    flowchart LR
+        Shim["Shim detected"] --> EnvVar{"PYENV_VERSION\nset?"}
+        EnvVar -->|Yes| Use["Use that version"]
+        EnvVar -->|No| File{".python-version\nfile exists?"}
+        File -->|Yes| Use
+        File -->|No| Global{"$(PYENV_ROOT)/version\nexists?"}
+        Global -->|Yes| Use
+        Global -->|No| Skip["Skip shim"]
+
+For mise and asdf, the ``MISE_DATA_DIR`` / ``ASDF_DATA_DIR`` directories are searched. The shim directory is
+identified via ``PYENV_ROOT``, ``MISE_DATA_DIR``, or ``ASDF_DATA_DIR`` environment variables.
+
+Cache design
+------------
+
+The :class:`~py_discovery.DiskCache` stores interpreter metadata as JSON files under
+``<root>/py_info/4/<sha256>.json``, where the hash is derived from the interpreter path. File locking via ``filelock``
+ensures safe concurrent access.
+
+.. mermaid::
+
+    flowchart LR
+        Lookup["py_info(path)"] --> Exists{Cache hit?}
+        Exists -->|Yes| Read["Read JSON"]
+        Exists -->|No| Run["Run subprocess"]
+        Run --> Write["Write JSON\n(with filelock)"]
+        Write --> Return["Return PythonInfo"]
+        Read --> Return
+
+The cache layer uses a :class:`typing.Protocol` (:class:`~py_discovery.PyInfoCache`), so any object with the right
+method signatures works as a cache backend -- no inheritance required. Two built-in implementations are provided:
+
+- :class:`~py_discovery.DiskCache` -- persistent JSON + filelock storage
+- :class:`~py_discovery.NoOpCache` -- no-op, useful for one-shot scripts or testing
+
+Spec format
+-----------
+
+A spec string follows the pattern ``[impl][version][t][-arch][-machine]``:
+
+.. mermaid::
+
+    flowchart LR
+        Spec["Spec string"] --> Impl["impl\n(optional)"]
+        Impl --> Version["version\n(optional)"]
+        Version --> T["t\n(optional)"]
+        T --> Arch["-arch\n(optional)"]
+        Arch --> Machine["-machine\n(optional)"]
+
+        style Impl fill:#e0f0ff,stroke:#4a90d9
+        style Version fill:#e0ffe0,stroke:#4a9f4a
+        style T fill:#fff0e0,stroke:#d9904a
+        style Arch fill:#ffe0e0,stroke:#d94a4a
+        style Machine fill:#f0e0ff,stroke:#904ad9
+
++------------------------------+-----------------------------------------------+
+| Spec                         | Meaning                                       |
++==============================+===============================================+
+| ``python3.12``               | CPython 3.12 (any architecture)               |
++------------------------------+-----------------------------------------------+
+| ``cpython3.12``              | Explicitly CPython 3.12                       |
++------------------------------+-----------------------------------------------+
+| ``pypy3.9``                  | PyPy 3.9                                      |
++------------------------------+-----------------------------------------------+
+| ``3.12``                     | Any implementation, version 3.12              |
++------------------------------+-----------------------------------------------+
+| ``python3.12t``              | Free-threaded (no-GIL) CPython 3.12           |
++------------------------------+-----------------------------------------------+
+| ``python3.12-64``            | 64-bit CPython 3.12                           |
++------------------------------+-----------------------------------------------+
+| ``python3.12-64-arm64``      | 64-bit CPython 3.12 on ARM64                  |
++------------------------------+-----------------------------------------------+
+| ``/usr/bin/python3``         | Absolute path, used directly                  |
++------------------------------+-----------------------------------------------+
+| ``>=3.11,<3.13``             | PEP 440 version specifier                     |
++------------------------------+-----------------------------------------------+
+| ``cpython>=3.11``            | PEP 440 specifier with implementation filter  |
++------------------------------+-----------------------------------------------+
+
+The ``impl`` prefix is optional; ``python`` and ``py`` are treated as "any implementation". The ``t`` suffix matches
+free-threaded (no-GIL) builds. Architecture (``-32`` or ``-64``) and ISA (``-arm64``, ``-x86_64``, etc.) are optional
+suffixes separated by dashes.
+
+PEP 440 specifiers (``>=``, ``<=``, ``~=``, ``!=``, ``==``, ``===``) are supported for flexible version matching.
+Multiple specifiers can be comma-separated: ``>=3.11,<3.13``.

docs/how-to/standalone-usage.rst

@@ -1,37 +1,109 @@
-Standalone usage
-================
+Advanced usage
+==============
 
-``py-discovery`` works independently of virtualenv. It has only two runtime dependencies: ``filelock`` and
-``platformdirs``.
-
-Using the ``Builtin`` discover
-------------------------------
+Custom cache backends
+---------------------
 
-The :class:`~py_discovery.Builtin` class searches PATH, version managers (pyenv, mise, asdf), the Windows registry
-(PEP 514), and uv-managed installations:
+Implement the :class:`~py_discovery.PyInfoCache` protocol to provide your own storage. The protocol requires two
+methods:
 
 .. code-block:: python
 
    from pathlib import Path
 
+   from py_discovery import ContentStore, PyInfoCache
+
+
+   class MyContentStore:
+       def __init__(self, path: Path) -> None:
+           self._path = path
+
+       def exists(self) -> bool: ...
+
+       def read(self) -> dict | None: ...
+
+       def write(self, content: dict) -> None: ...
+
+       def remove(self) -> None: ...
+
+       def locked(self): ...
+
+
+   class MyCache:
+       def py_info(self, path: Path) -> MyContentStore: ...
+
+       def py_info_clear(self) -> None: ...
+
+The built-in :class:`~py_discovery.DiskCache` stores JSON files under ``<root>/py_info/4/<sha256>.json`` with
+``filelock``-based locking. :class:`~py_discovery.NoOpCache` disables caching entirely.
+
+Using ``get_interpreter`` directly
+-----------------------------------
+
+For lower-level control, use :func:`~py_discovery.get_interpreter` instead of the :class:`~py_discovery.Builtin` class:
+
+.. code-block:: python
+
+   from py_discovery import get_interpreter
+
+   info = get_interpreter("python3.12", try_first_with=["/opt/python/bin"])
+   if info is not None:
+       print(info.executable)
+
+The ``try_first_with`` parameter takes paths to check before the normal discovery strategy.
+
+Controlling the environment
+---------------------------
+
+Pass a custom environment mapping to isolate discovery from the system environment:
+
+.. code-block:: python
+
+   import os
+
+   from py_discovery import Builtin
+
+   env = {**os.environ, "PATH": "/usr/local/bin:/usr/bin"}
+   discover = Builtin(python_spec=["python3.12"], env=env)
+
+This controls which ``PATH``, ``PYENV_ROOT``, ``UV_PYTHON_INSTALL_DIR``, and other environment variables are used
+during discovery.
+
+Inspecting interpreter metadata
+--------------------------------
+
+A :class:`~py_discovery.PythonInfo` object exposes detailed interpreter metadata:
+
+.. code-block:: python
+
    from py_discovery import Builtin, DiskCache
+   from pathlib import Path
 
    cache = DiskCache(root=Path("~/.cache/py-discovery").expanduser())
-   discover = Builtin(python_spec=["python3.12"], cache=cache)
-   interpreter = discover.interpreter  # cached property, calls run() once
+   info = Builtin(python_spec=["python3.12"], cache=cache).run()
 
-Custom cache backends
----------------------
+   info.executable           # resolved path to the binary
+   info.system_executable    # the system (non-venv) executable
+   info.implementation       # "CPython", "PyPy", etc.
+   info.version_info         # VersionInfo(major, minor, micro, releaselevel, serial)
+   info.architecture         # 64 or 32
+   info.platform             # sys.platform value ("linux", "darwin", "win32")
+   info.sysconfig_vars       # dict of sysconfig variables
+   info.sysconfig_paths      # dict of sysconfig paths
 
-Implement the :class:`~py_discovery.PyInfoCache` protocol to provide your own storage:
+Parsing specs without discovery
+-------------------------------
 
-.. code-block:: python
+Use :class:`~py_discovery.PythonSpec` to parse a spec string without running discovery:
 
-   from py_discovery import PyInfoCache
+.. code-block:: python
 
-   class MyCache:
-       def py_info(self, path):
-           ...
+   from py_discovery import PythonSpec
 
-       def py_info_clear(self):
-           ...
+   spec = PythonSpec.from_string_spec("cpython3.12t-64-arm64")
+   print(spec.implementation)   # cpython
+   print(spec.major)            # 3
+   print(spec.minor)            # 12
+   print(spec.free_threaded)    # True
+   print(spec.architecture)     # 64
+   print(spec.machine)          # arm64

docs/index.rst

@@ -1,8 +1,9 @@
 py-discovery
 ============
 
-Python interpreter discovery library. Extracted from `virtualenv <https://virtualenv.pypa.io>`_, ``py-discovery``
-provides a self-contained API for finding Python interpreters on the system.
+A Python interpreter discovery library. ``py-discovery`` finds Python interpreters on your system by searching PATH,
+version managers (pyenv, mise, asdf), the Windows registry (PEP 514), and uv-managed installations. Results are cached
+to disk for fast repeated lookups.
 
 Tutorial
 --------
@@ -13,7 +14,7 @@ Tutorial
    tutorial/getting-started
 
 :doc:`tutorial/getting-started`
-   Create a cache and discover interpreters.
+   Install py-discovery, find interpreters, and inspect their metadata.
 
 How-to guides
 -------------
@@ -24,7 +25,7 @@ How-to guides
    how-to/standalone-usage
 
 :doc:`how-to/standalone-usage`
-   Using py-discovery without virtualenv.
+   Advanced usage: custom cache backends, environment isolation, and the ``get_interpreter`` function.
 
 Reference
 ---------
@@ -46,4 +47,4 @@ Explanation
    explanation
 
 :doc:`explanation`
-   How discovery works, cache sharing, and the Protocol design.
+   How the discovery strategy works, spec format syntax, and the cache design.

docs/tutorial/getting-started.rst

@@ -1,30 +1,72 @@
 Getting started
 ===============
 
-Install py-discovery:
+Installation
+------------
 
 .. code-block:: console
 
    pip install py-discovery
 
-Discover the current interpreter:
+Finding the current interpreter
+--------------------------------
 
 .. code-block:: python
 
+   from pathlib import Path
+
    from py_discovery import DiskCache, PythonInfo
 
    cache = DiskCache(root=Path("~/.cache/py-discovery").expanduser())
    info = PythonInfo.current_system(cache)
-   print(info.spec)
+   print(info.executable)        # /usr/bin/python3.12
+   print(info.version_info[:3])  # (3, 12, 1)
+   print(info.implementation)    # CPython
+   print(info.architecture)      # 64
+
+Discovering an interpreter by spec
+-----------------------------------
 
-Find an interpreter by spec:
+Use :class:`~py_discovery.Builtin` to find an interpreter matching a specification string:
 
 .. code-block:: python
 
+   from pathlib import Path
+
    from py_discovery import Builtin, DiskCache
 
    cache = DiskCache(root=Path("~/.cache/py-discovery").expanduser())
-   builtin = Builtin(python_spec=["python3.12"], cache=cache)
-   result = builtin.run()
+   discover = Builtin(python_spec=["python3.12"], cache=cache)
+   result = discover.run()
    if result is not None:
        print(result.executable)
+
+The ``python_spec`` parameter accepts a list of spec strings to try in order. The first match wins.
+
+Spec syntax
+-----------
+
+Specs follow the pattern ``[impl][version][t][-arch][-machine]``:
+
+- ``python3.12`` -- CPython 3.12
+- ``cpython3.12`` -- explicitly CPython 3.12
+- ``pypy3.9`` -- PyPy 3.9
+- ``3.12`` -- any implementation, version 3.12
+- ``python3.12t`` -- free-threaded CPython 3.12
+- ``python3.12-64`` -- 64-bit CPython 3.12
+- ``python3.12-64-arm64`` -- 64-bit CPython 3.12 on ARM64
+- ``/usr/bin/python3`` -- absolute path, used directly
+- ``>=3.11,<3.13`` -- PEP 440 version specifier
+- ``cpython>=3.11`` -- PEP 440 specifier with implementation filter
+
+Without caching
+---------------
+
+Pass ``cache=None`` to skip caching entirely. Each discovery will invoke the interpreter subprocess:
+
+.. code-block:: python
+
+   from py_discovery import Builtin
+
+   discover = Builtin(python_spec=["python3.12"], cache=None)
+   result = discover.run()