libsoulsearching 0.1.1__tar.gz

libsoulsearching-0.1.1/.gitignore

@@ -0,0 +1,68 @@
+# python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# ides
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# raiseattention cache
+.raiseattention/
+
+# misc
+.DS_Store
+*.log
+
+# nix
+result
+result-*
+.direnv/
+
+# playground and debug files
+playground/
+test_debug*.py
+test_env_config.py
+
+# caches
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/

libsoulsearching-0.1.1/LICENCING

@@ -0,0 +1,25 @@
+This software is unencumbered and free-as-in-freedom.
+
+This project is dual-licenced under The Unlicense or the BSD Zero Clause
+License. (SPDX: `Unlicense OR 0BSD`)
+
+The spirit and intent of the project is to treat the work as public domain via
+The Unlicense, but providing the BSD Zero Clause License where public domain
+dedication is not possible due to policies bound to a contributor or their
+employer. However, this is not a legal condition.
+
+Either way, you are free to use the software as you wish, without any
+restrictions or obligations, subject only to the warranty disclaimers in the
+licence texts.
+
+> Does dual licencing not invalidate the ethos behind The Unlicense?
+
+Well yeah, but like, even if ten percent of code is 0BSD-licenced, the rest
+is still unlicenced. And that's... good enough, and better than the
+alternative of a fully 0BSD-licenced project. _Everyone should be able to
+contribute._
+
+---
+
+See the [CONTRIBUTING](./CONTRIBUTING), [UNLICENSE](./UNLICENSE), and
+[LICENSE-0BSD](./LICENSE-0BSD) files for more information.

libsoulsearching-0.1.1/LICENSE-0BSD

@@ -0,0 +1,12 @@
+Copyright (C) 2024 by Mark Joshwel <mark@joshwel.co>
+
+Permission to use, copy, modify, and/or distribute this software for
+any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE
+FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY
+DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

libsoulsearching-0.1.1/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: libsoulsearching
+Version: 0.1.1
+Summary: universal python virtual environment finder
+Project-URL: Documentation, https://github.com/markjoshwel/RaiseAttention/tree/main/src/libsoulsearching#readme
+Project-URL: Repository, https://github.com/markjoshwel/RaiseAttention/tree/main/src/libsoulsearching
+Project-URL: Issues, https://github.com/markjoshwel/RaiseAttention/issues
+Author-email: Mark Joshwel <mark@joshwel.co>
+Maintainer-email: Mark Joshwel <mark@joshwel.co>
+License-Expression: Unlicense OR 0BSD
+License-File: LICENCING
+License-File: LICENSE-0BSD
+Keywords: hatch,pdm,pipenv,poetry,pyenv,python,rye,uv,venv,virtualenv
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
+Classifier: License :: OSI Approved :: Zero-Clause BSD (0BSD)
+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
+
+python virtual environment finder for most mainstream setups,
+after multiple projects of mine needed to dig through a venv
+
+## installation
+
+```text
+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
+
+```text
+# 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()`  
+  find a virtual environment in the given project directory
+
+- `libsoulsearching.find_all_venvs()`  
+  find all virtual environments in the given project directory
+
+- `libsoulsearching.ToolType`  
+  enumeration of supported python environment management tools
+
+- `libsoulsearching.VenvInfo`  
+  information about a detected python virtual environment
+
+### 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
+
+libsoulsearching is unencumbered, free-as-in-freedom, and is dual-licenced under
+The Unlicense or the BSD Zero Clause License. (SPDX: `Unlicense OR 0BSD`)
+
+you are free to use the software as you wish, without any restrictions or
+obligations, subject only to the warranty disclaimers in the licence text
+of your choosing.

libsoulsearching-0.1.1/README.md

@@ -0,0 +1,177 @@
+# libsoulsearching
+
+python virtual environment finder for most mainstream setups,
+after multiple projects of mine needed to dig through a venv
+
+## installation
+
+```text
+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
+
+```text
+# 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()`  
+  find a virtual environment in the given project directory
+
+- `libsoulsearching.find_all_venvs()`  
+  find all virtual environments in the given project directory
+
+- `libsoulsearching.ToolType`  
+  enumeration of supported python environment management tools
+
+- `libsoulsearching.VenvInfo`  
+  information about a detected python virtual environment
+
+### 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
+
+libsoulsearching is unencumbered, free-as-in-freedom, and is dual-licenced under
+The Unlicense or the BSD Zero Clause License. (SPDX: `Unlicense OR 0BSD`)
+
+you are free to use the software as you wish, without any restrictions or
+obligations, subject only to the warranty disclaimers in the licence text
+of your choosing.

libsoulsearching-0.1.1/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org/>

libsoulsearching-0.1.1/libsoulsearching/__init__.py

@@ -0,0 +1,25 @@
+"""
+universal python virtual environment finder.
+
+libsoulsearching detects virtual environments created by various python tools
+including poetry, pipenv, pdm, uv, rye, hatch, standard venv, and pyenv.
+
+functions:
+    `def find_venv(project_root: str | Path, tool: ToolType | None = None) -> VenvInfo | None`
+        find a virtual environment in the given project directory
+    `def find_all_venvs(project_root: str | Path) -> list[VenvInfo]`
+        find all virtual environments in the given project directory
+"""
+
+from __future__ import annotations
+
+from .core import find_venv, find_all_venvs
+from .models import ToolType, VenvInfo
+
+__version__ = "0.1.0"
+__all__ = [
+    "find_venv",
+    "find_all_venvs",
+    "ToolType",
+    "VenvInfo",
+]