From c788f82fc135cdad1d073fe84644451544d86be8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bern=C3=A1t=20G=C3=A1bor?= Date: Mon, 9 Mar 2026 09:28:43 -0700 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20add=20package=20descript?= =?UTF-8?q?ion=20and=20usage=20examples=20to=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README previously provided no information about what python-discovery does or how to use it, making it difficult for potential users to evaluate the package or get started quickly. Added a clear explanation of the package's purpose (discovering Python interpreters across multiple installation sources), a working usage example with get_interpreter(), and a list of supported specification formats. This addresses issue #44 and improves the first-time user experience. --- README.md | 39 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index decf7fa..5710f84 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,43 @@ # [`python-discovery`](https://python-discovery.readthedocs.io/en/latest/) [![PyPI](https://img.shields.io/pypi/v/python-discovery?style=flat-square)](https://pypi.org/project/python-discovery/) -[![Supported Python -versions](https://img.shields.io/pypi/pyversions/python-discovery.svg)](https://pypi.org/project/python-discovery/) +[![Supported Python versions](https://img.shields.io/pypi/pyversions/python-discovery.svg)](https://pypi.org/project/python-discovery/) [![Downloads](https://static.pepy.tech/badge/python-discovery/month)](https://pepy.tech/project/python-discovery) [![check](https://github.com/tox-dev/python-discovery/actions/workflows/check.yaml/badge.svg)](https://github.com/tox-dev/python-discovery/actions/workflows/check.yaml) [![Documentation Status](https://readthedocs.org/projects/python-discovery/badge/?version=latest)](https://python-discovery.readthedocs.io/en/latest/?badge=latest) + +## What is python-discovery? + +`python-discovery` is a library for discovering Python interpreters installed on your machine. You may have multiple +Python versions from system packages, [pyenv](https://github.com/pyenv/pyenv), [mise](https://mise.jdx.dev/), +[asdf](https://asdf-vm.com/), [uv](https://docs.astral.sh/uv/), or the Windows registry (PEP 514). This library finds +the right one for you. + +Give it a requirement like `python3.12` or `>=3.11,<3.13`, and it searches all known locations, verifies each candidate, +and returns detailed metadata about the match. Results are cached to disk so repeated lookups are fast. + +## Usage + +```python +from pathlib import Path + +from python_discovery import DiskCache, get_interpreter + +cache = DiskCache(root=Path("~/.cache/python-discovery").expanduser()) +result = get_interpreter("python3.12", cache=cache) +if result is not None: + print(result.executable) # /usr/bin/python3.12 + print(result.implementation) # CPython + print(result.version_info[:3]) # (3, 12, 1) +``` + +The `get_interpreter()` function accepts various specification formats: + +- Absolute path: `/usr/bin/python3.12` +- Version: `3.12` +- Implementation prefix: `cpython3.12` +- PEP 440 specifier: `>=3.10`, `>=3.11,<3.13` + +## Documentation + +Full documentation is available at [python-discovery.readthedocs.io](https://python-discovery.readthedocs.io/en/latest/)