Metadata-Version: 2.4
Name: libsoulsearching
Version: 0.1.0
Summary: universal python virtual environment finder
Project-URL: homepage, https://github.com/anomalyco/raiseattention
Project-URL: repository, https://github.com/anomalyco/raiseattention
Project-URL: documentation, https://github.com/anomalyco/raiseattention#readme
License: MIT
Keywords: hatch,pdm,pipenv,poetry,pyenv,python,rye,uv,venv,virtualenv
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: typing-extensions>=4.6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# libsoulsearching

universal python virtual environment finder

## installation

```bash
pip install libsoulsearching
```

## quickstart

```python
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

```bash
# 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](#def-libsoulsearchingfind_venv)
- [libsoulsearching.find_all_venvs](#def-libsoulsearchingfind_all_venvs)
- [libsoulsearching.ToolType](#class-libsoulsearchingtooltype)
- [libsoulsearching.VenvInfo](#class-libsoulsearchingvenvinfo)

### def libsoulsearching.find_venv()

find a virtual environment in the given project directory

- signature:

  ```python
  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:

  ```python
  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
