API reference

Self-contained Python interpreter discovery.

class python_discovery.ContentStore(*args, **kwargs)

Bases: Protocol

A store for reading and writing cached content.

exists()

Return whether the cached content exists.

Return type:

bool

locked()

Context manager that acquires an exclusive lock on this store.

Return type:

Generator[None]

read()

Read the cached content, or None if unavailable or corrupt.

Return type:

dict | None

remove()

Delete the cached content.

Return type:

None

write(content)

Persist content to the store.

Parameters:

content (dict) – interpreter metadata to cache.

Return type:

None

class python_discovery.DiskCache(root)

Bases: object

File-system based Python interpreter info cache (<root>/py_info/4/<sha256>.json).

Parameters:

root (Path) – root directory for the on-disk cache.

py_info(path)

Return the content store for the interpreter at path.

Parameters:

path (Path) – absolute path to a Python executable.

Return type:

DiskContentStore

py_info_clear()

Remove all cached interpreter information.

Return type:

None

class python_discovery.PyInfoCache(*args, **kwargs)

Bases: Protocol

Cache interface for Python interpreter information.

py_info(path)

Return the content store for the interpreter at path.

Parameters:

path (Path) – absolute path to a Python executable.

Return type:

ContentStore

py_info_clear()

Remove all cached interpreter information.

Return type:

None

class python_discovery.PythonInfo

Bases: object

Contains information for a Python interpreter.

classmethod clear_cache(cache)

Clear all cached interpreter information from cache.

Parameters:

cache (PyInfoCache) – the cache store to clear.

Return type:

None

classmethod current(cache=None)

Locate the current host interpreter information.

Parameters:

cache (PyInfoCache | None) – interpreter metadata cache; when None results are not cached.

Return type:

PythonInfo

classmethod current_system(cache=None)

Locate the current system interpreter information, resolving through any virtualenv layers.

Parameters:

cache (PyInfoCache | None) – interpreter metadata cache; when None results are not cached.

Return type:

PythonInfo

discover_exe(cache, prefix, *, exact=True, env=None)

Discover a matching Python executable under a given prefix directory.

Parameters:

  • cache (PyInfoCache) – interpreter metadata cache.

  • prefix (str) – directory prefix to search under.

  • exact (bool) – when True, require an exact version match.

  • env (Mapping[str, str] | None) – environment mapping; defaults to os.environ.

Return type:

PythonInfo

classmethod from_dict(data)

Reconstruct a PythonInfo from a plain dictionary.

Parameters:

data (dict[str, object]) – dictionary produced by to_dict().

Return type:

PythonInfo

classmethod from_exe(exe, cache=None, *, raise_on_error=True, ignore_cache=False, resolve_to_host=True, env=None)

Get the python information for a given executable path.

Parameters:

  • exe (str) – path to the Python executable.

  • cache (PyInfoCache | None) – interpreter metadata cache; when None results are not cached.

  • raise_on_error (bool) – raise on failure instead of returning None.

  • ignore_cache (bool) – bypass the cache and re-query the interpreter.

  • resolve_to_host (bool) – resolve through virtualenv layers to the system interpreter.

  • env (Mapping[str, str] | None) – environment mapping; defaults to os.environ.

Return type:

PythonInfo | None

classmethod from_json(payload)

Deserialize interpreter information from a JSON string.

Parameters:

payload (str) – JSON produced by to_json().

Return type:

PythonInfo

install_path(key)

Return the relative installation path for a given installation scheme key.

Parameters:

key (str) – sysconfig installation scheme key (e.g. "scripts", "purelib").

Return type:

str

property is_old_virtualenv: bool

True if this interpreter runs inside an old-style virtualenv (has real_prefix).

property is_venv: bool

True if this interpreter runs inside a PEP 405 venv (has base_prefix).

property machine: str

Return the instruction set architecture (ISA) derived from sysconfig.get_platform().

property python_name: str

The python executable name as pythonX.Y (e.g. python3.13).

classmethod resolve_to_system(cache, target)

Walk virtualenv/venv prefix chains to find the underlying system interpreter.

Parameters:

  • cache (PyInfoCache | None) – interpreter metadata cache; when None results are not cached.

  • target (PythonInfo) – the interpreter to resolve.

Return type:

PythonInfo

satisfies(spec, *, impl_must_match)

Check if a given specification can be satisfied by this python interpreter instance.

Parameters:

  • spec (PythonSpec) – the specification to check against.

  • impl_must_match (bool) – when True, the implementation name must match exactly.

Return type:

bool

property spec: str

A specification string identifying this interpreter (e.g. CPython3.13.2-64-arm64).

sysconfig_path(key, config_var=None, sep='/')

Return the sysconfig install path for a scheme key, optionally substituting config variables.

Parameters:

  • key (str) – sysconfig path key (e.g. "purelib", "include").

  • config_var (dict[str, str] | None) – replacement mapping for sysconfig variables; when None uses the interpreter’s own values.

  • sep (str) – path separator to use in the result.

Return type:

str

property system_exec_prefix: str

The exec prefix of the system Python this interpreter is based on.

property system_include: str

The path to the system include directory for C headers.

property system_prefix: str

The prefix of the system Python this interpreter is based on.

to_dict()

Convert this interpreter information to a plain dictionary.

Return type:

dict[str, object]

to_json()

Serialize this interpreter information to a JSON string.

Return type:

str

property version_release_str: str

The release version as major.minor string (e.g. 3.13).

property version_str: str

The full version as major.minor.micro string (e.g. 3.13.2).

class python_discovery.PythonSpec(str_spec, implementation, major, minor, micro, architecture, path, *, free_threaded=None, machine=None, version_specifier=None)

Bases: object

Contains specification about a Python Interpreter.

Parameters:

  • str_spec (str) – the raw specification string as provided by the caller.

  • implementation (str | None) – interpreter implementation name (e.g. "cpython", "pypy"), or None for any.

  • major (int | None) – required major version, or None for any.

  • minor (int | None) – required minor version, or None for any.

  • micro (int | None) – required micro (patch) version, or None for any.

  • architecture (int | None) – required pointer-size bitness (32 or 64), or None for any.

  • path (str | None) – filesystem path to a specific interpreter, or None.

  • free_threaded (bool | None) – whether a free-threaded build is required, or None for any.

  • machine (str | None) – required ISA (e.g. "arm64"), or None for any.

  • version_specifier (SimpleSpecifierSet | None) – PEP 440 version constraints, or None.

classmethod from_string_spec(string_spec)

Parse a string specification into a PythonSpec.

Parameters:

string_spec (str) – an interpreter spec — an absolute path, a version string, an implementation prefix, or a PEP 440 specifier.

Return type:

PythonSpec

generate_re(*, windows)

Generate a regular expression for matching interpreter filenames.

Parameters:

windows (bool) – if True, require a .exe suffix.

Return type:

Pattern

property is_abs: bool

True if the spec refers to an absolute filesystem path.

satisfies(spec)

Check if this spec is compatible with the given spec (e.g. PEP-514 on Windows).

Parameters:

spec (PythonSpec) – the requirement to check against.

Return type:

bool

class python_discovery.SimpleSpecifier(*, spec_str, operator, version_str, is_wildcard, wildcard_precision, version)

Bases: object

Simple PEP 440-like version specifier using only standard library.

Parameters:

  • spec_str (str) – the original specifier string (e.g. >=3.10).

  • operator (str) – the comparison operator (==, >=, <, etc.).

  • version_str (str) – the version portion of the specifier, without the operator.

  • is_wildcard (bool) – True if the specifier uses a wildcard suffix (.*).

  • wildcard_precision (int | None) – number of version components before the wildcard, or None.

  • version (SimpleVersion | None) – the parsed version, or None if parsing failed.

contains(version_str)

Check if a version string satisfies this specifier.

Parameters:

version_str (str) – the version string to test.

Return type:

bool

classmethod from_string(spec_str)

Parse a single PEP 440 specifier (e.g. >=3.10).

Parameters:

spec_str (str) – the specifier string to parse.

Return type:

SimpleSpecifier

is_wildcard: bool
operator: str
spec_str: str
version: SimpleVersion | None
version_str: str
wildcard_precision: int | None
class python_discovery.SimpleSpecifierSet(*, specifiers_str, specifiers)

Bases: object

Simple PEP 440-like specifier set using only standard library.

Parameters:

  • specifiers_str (str) – the original comma-separated specifier string.

  • specifiers (tuple[SimpleSpecifier, ...]) – the parsed individual specifiers.

contains(version_str)

Check if a version satisfies all specifiers in the set.

Parameters:

version_str (str) – the version string to test.

Return type:

bool

classmethod from_string(specifiers_str='')

Parse a comma-separated PEP 440 specifier string (e.g. >=3.10,<4).

Parameters:

specifiers_str (str) – the specifier string to parse.

Return type:

SimpleSpecifierSet

specifiers: tuple[SimpleSpecifier, ...]
specifiers_str: str
class python_discovery.SimpleVersion(*, version_str, major, minor, micro, pre_type, pre_num, release)

Bases: object

Simple PEP 440-like version parser using only standard library.

Parameters:

  • version_str (str) – the original version string.

  • major (int) – major version number.

  • minor (int) – minor version number.

  • micro (int) – micro (patch) version number.

  • pre_type (str | None) – pre-release label ("a", "b", or "rc"), or None.

  • pre_num (int | None) – pre-release sequence number, or None.

  • release (tuple[int, int, int]) – the (major, minor, micro) tuple.

classmethod from_string(version_str)

Parse a PEP 440 version string (e.g. 3.12.1).

Parameters:

version_str (str) – the version string to parse.

Return type:

SimpleVersion

major: int
micro: int
minor: int
pre_num: int | None
pre_type: str | None
release: tuple[int, int, int]
version_str: str
python_discovery.get_interpreter(key, try_first_with=None, cache=None, env=None, predicate=None)

Find a Python interpreter matching key.

Iterates over one or more specification strings and returns the first interpreter that satisfies the spec and passes the optional predicate.

Parameters:

  • key (str | Sequence[str]) – interpreter specification string(s) — an absolute path, a version (3.12), an implementation prefix (cpython3.12), or a PEP 440 specifier (>=3.10). When a sequence is given each entry is tried in order.

  • try_first_with (Iterable[str] | None) – executables to probe before the normal discovery search.

  • cache (PyInfoCache | None) – interpreter metadata cache; when None results are not cached.

  • env (Mapping[str, str] | None) – environment mapping for PATH lookup; defaults to os.environ.

  • predicate (Callable[[PythonInfo], bool] | None) – optional callback applied after an interpreter matches the spec. Return True to accept the interpreter, False to skip it and continue searching.

Return type:

PythonInfo | None

Returns:

the first matching interpreter, or None if no match is found.

python_discovery.normalize_isa(isa)

Normalize an ISA (instruction set architecture) string to a canonical form.

Known aliases are mapped (e.g. amd64 → x86_64, aarch64 → arm64). Unrecognized values are lowercased and returned as-is.

Parameters:

isa (str)

Return type:

str