libsoulsearching 0.1.0

universal python virtual environment finder

libsoulsearching

universal python virtual environment finder

installation

pip install libsoulsearching

quickstart

from libsoulsearching import find_venv, find_all_venvs, ToolType

# find the first/best venv
info = find_venv("/path/to/project")
if info:
    print(f"found {info.tool.value} venv at {info.venv_path}")

# find all venvs
all_venvs = find_all_venvs("/path/to/project")
for venv in all_venvs:
    print(f"{venv.tool.value}: {venv.venv_path}")

# find specific tool only
poetry_venv = find_venv("/path/to/project", tool=ToolType.POETRY)

supported tools

• poetry - poetry.lock, pyproject.toml with poetry config
• pipenv - pipfile.lock
• pdm - pdm.lock, .pdm.toml
• uv - uv.lock, .venv
• rye - rye.lock, .python-version
• hatch - pyproject.toml with [tool.hatch.envs]
• venv - .venv/pyvenv.cfg
• pyenv - .python-version

cli usage

# find first venv
venvfinder /path/to/project

# list all venvs
venvfinder /path/to/project --all

# find specific tool
venvfinder /path/to/project --tool poetry

# json output
venvfinder /path/to/project --json

api reference

• libsoulsearching.find_venv
• libsoulsearching.find_all_venvs
• libsoulsearching.ToolType
• libsoulsearching.VenvInfo

def libsoulsearching.find_venv()

find a virtual environment in the given project directory

• signature:

  def find_venv(
      project_root: str | Path,
      tool: ToolType | None = None,
  ) -> VenvInfo | None: ...
  

• arguments:

  • project_root: str | Path path to the project directory
  • tool: ToolType | None specific tool to detect. if none, uses priority order

• returns: VenvInfo | None venvinfo if a venv is found, none otherwise

def libsoulsearching.find_all_venvs()

find all virtual environments in the given project directory

returns all detected venvs in priority order, including potentially invalid ones (is_valid=false) if the tool's marker files exist but the actual venv is missing

• signature:

  def find_all_venvs(project_root: str | Path) -> list[VenvInfo]: ...
  

• arguments:

  • project_root: str | Path path to the project directory

• returns: list[VenvInfo] list of venvinfo objects (may be empty)

class libsoulsearching.ToolType

enumeration of supported python environment management tools

• attributes:
  • POETRY: str poetry package manager
  • PIPENV: str pipenv package manager
  • PDM: str pdm package manager
  • UV: str uv package manager
  • RYE: str rye package manager
  • HATCH: str hatch package manager
  • VENV: str standard venv module
  • PYENV: str pyenv version manager
  • ENV_VAR: str virtual environment from environment variable

class libsoulsearching.VenvInfo

information about a detected python virtual environment

• attributes:
  • tool: ToolType the detected tool type
  • venv_path: Path | None path to the virtual environment directory
  • python_executable: Path | None path to the python executable
  • python_version: str | None python version string (e.g., "3.10.5")
  • is_valid: bool whether the detected environment exists and is valid

licence

mit