libcontext 0.6.1__tar.gz → 0.7.0__tar.gz

{libcontext-0.6.1 → libcontext-0.7.0}/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-03-25
+
+### Added
+
+- **Universal venv auto-detection**: environment variable detection chain
+  (`VIRTUAL_ENV` → `CONDA_PREFIX` → `UV_PROJECT_ENVIRONMENT`) with fallback
+  to `.venv/`/`venv/` directory scan and `uv python find` query. Works for
+  virtualenv, conda, poetry, pdm, and uv users out of the box.
+
+### Fixed
+
+- **`Package not found` for globally-installed tool**: `libctx inspect` now
+  correctly discovers packages from project environments when installed via
+  `uv tool install` or `pipx`.
+- **Permission-denied crashes on file traversal**: `rglob()` generators that
+  hit `PermissionError` no longer abort collection; partial results are
+  preserved via incremental `_safe_rglob()` helper.
+- **Cache directory access errors**: `cache load` and `cache clear` handle
+  `OSError` on cache directory access gracefully.
+
+### Changed
+
+- **Search refactoring**: duplicated traversal logic between `search_package()`
+  and `search_package_structured()` extracted into shared `_collect_search_hits()`
+  helper (~150 lines removed).
+- **Single-pass file discovery**: `_walk_package()` and `_compute_source_stats()`
+  now use a single `rglob("*.py*")` pass instead of two separate traversals.
+- **Single-pass variable categorisation**: `render_module()` classifies variables
+  into aliases, constants, and module vars in one loop instead of three.
+- **Cache eviction**: replaced O(n) `pop(0)` loop with slice deletion.
+- Cleaned up broad `except` clauses and moved late imports to module level in
+  `renderer.py`.
+- Added missing `Raises:` docstring sections to public functions across
+  `inspector.py`, `config.py`, `_envsetup.py`, and `mcp_server.py`.
+
 ## [0.6.1] - 2026-03-25
 
 ### Fixed
@@ -108,7 +143,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Free-form `extra_context` field for library authors.
 - Python API for programmatic usage (`collect_package`, `render_package`).
 
-[Unreleased]: https://github.com/Syclaw/libcontext/compare/v0.6.1...HEAD
+[Unreleased]: https://github.com/Syclaw/libcontext/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/Syclaw/libcontext/compare/v0.6.1...v0.7.0
 [0.6.1]: https://github.com/Syclaw/libcontext/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/Syclaw/libcontext/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/Syclaw/libcontext/compare/v0.4.0...v0.5.0

{libcontext-0.6.1 → libcontext-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libcontext
-Version: 0.6.1
+Version: 0.7.0
 Summary: Generate optimized LLM context from Python library APIs — CLI, skill, and MCP server
 Project-URL: Homepage, https://github.com/Syclaw/libcontext
 Project-URL: Repository, https://github.com/Syclaw/libcontext

{libcontext-0.6.1 → libcontext-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "libcontext"
-version = "0.6.1"
+version = "0.7.0"
 description = "Generate optimized LLM context from Python library APIs — CLI, skill, and MCP server"
 readme = "README.md"
 license = "MIT"

{libcontext-0.6.1 → libcontext-0.7.0}/src/libcontext/_envsetup.py

@@ -9,8 +9,13 @@ discovery works against the target environment.
 
 Detection priority:
 1. Explicit ``--python`` argument → use that environment.
-2. ``.venv/`` or ``venv/`` in CWD → use the detected venv.
-3. Neither → use the current process's environment (no injection).
+2. ``VIRTUAL_ENV`` env var → activated venv (any tool).
+3. ``CONDA_PREFIX`` env var → activated conda environment.
+4. ``UV_PROJECT_ENVIRONMENT`` env var → uv-specific override.
+5. ``.venv/`` or ``venv/`` in CWD → use the detected venv.
+6. ``uv`` fallback: if CWD has ``pyproject.toml``, query ``uv`` for the
+   project interpreter.
+7. Neither → use the current process's environment (no injection).
 """
 
 from __future__ import annotations
@@ -18,6 +23,7 @@ from __future__ import annotations
 import importlib
 import json
 import logging
+import os
 import subprocess
 import sys
 from collections.abc import Generator
@@ -33,13 +39,36 @@ _SUBPROCESS_TIMEOUT_SECONDS = 10
 
 _VENV_DIR_NAMES = (".venv", "venv")
 
+# Relative interpreter paths inside a venv, checked in order.
+_INTERPRETER_CANDIDATES = (
+    Path("Scripts") / "python.exe",  # Windows
+    Path("bin") / "python",  # Unix
+    Path("bin") / "python3",  # Unix alternative
+)
+
+
+def _has_python_interpreter(venv_dir: Path) -> bool:
+    """Check whether a directory contains a recognisable Python interpreter."""
+    return any((venv_dir / rel).is_file() for rel in _INTERPRETER_CANDIDATES)
+
 
 def auto_detect_venv(cwd: Path | None = None) -> Path | None:
     """Detect a project venv in the current working directory.
 
-    Checks for ``.venv/`` then ``venv/`` in *cwd* (defaults to
-    ``Path.cwd()``).  Only considers directories that contain a
-    recognisable Python interpreter.
+    Detection order:
+
+    1. ``VIRTUAL_ENV`` env var — set by any activated venv (virtualenv,
+       ``python -m venv``, ``poetry shell``, etc.).
+    2. ``CONDA_PREFIX`` env var — set by an activated conda environment.
+    3. ``UV_PROJECT_ENVIRONMENT`` env var — used when ``uv`` is configured
+       to place the venv outside the default ``.venv/`` location.
+    4. ``.venv/`` then ``venv/`` in *cwd*.
+    5. ``uv`` fallback — if *cwd* contains a ``pyproject.toml``, query
+       ``uv python find`` to locate the project interpreter and derive
+       the venv from its path.
+
+    Only considers directories that contain a recognisable Python
+    interpreter.
 
     Args:
         cwd: Directory to search in.  Defaults to the process CWD.
@@ -50,20 +79,80 @@ def auto_detect_venv(cwd: Path | None = None) -> Path | None:
     if cwd is None:
         cwd = Path.cwd()
 
+    # 1. VIRTUAL_ENV — set by any venv activation script
+    # 2. CONDA_PREFIX — set by conda activate
+    # 3. UV_PROJECT_ENVIRONMENT — uv-specific override
+    for var in ("VIRTUAL_ENV", "CONDA_PREFIX", "UV_PROJECT_ENVIRONMENT"):
+        value = os.environ.get(var)
+        if not value:
+            continue
+        candidate = Path(value)
+        if candidate.is_dir() and _has_python_interpreter(candidate):
+            logger.debug("Auto-detected venv from %s: '%s'", var, candidate)
+            return candidate
+        logger.debug("%s='%s' set but not a valid venv", var, value)
+
+    # 4. Standard .venv/ and venv/ in CWD
     for name in _VENV_DIR_NAMES:
         candidate = cwd / name
-        if not candidate.is_dir():
-            continue
-        # Verify it actually contains an interpreter
-        interpreters = [
-            candidate / "Scripts" / "python.exe",
-            candidate / "bin" / "python",
-            candidate / "bin" / "python3",
-        ]
-        if any(exe.is_file() for exe in interpreters):
+        if candidate.is_dir() and _has_python_interpreter(candidate):
             logger.debug("Auto-detected venv at '%s'", candidate)
             return candidate
 
+    # 5. uv fallback — ask uv for the project interpreter
+    if (cwd / "pyproject.toml").is_file():
+        venv = _detect_venv_via_uv(cwd)
+        if venv is not None:
+            return venv
+
+    return None
+
+
+def _detect_venv_via_uv(cwd: Path) -> Path | None:
+    """Ask ``uv`` for the project interpreter and derive the venv path.
+
+    Only called when a ``pyproject.toml`` exists in *cwd* but no
+    standard venv directory was found.
+    """
+    try:
+        result = subprocess.run(
+            ["uv", "python", "find", "--project", str(cwd)],
+            capture_output=True,
+            text=True,
+            timeout=_SUBPROCESS_TIMEOUT_SECONDS,
+            cwd=str(cwd),
+        )
+    except FileNotFoundError:
+        logger.debug("uv not found on PATH; skipping uv-based detection")
+        return None
+    except subprocess.TimeoutExpired:
+        logger.debug("uv python find timed out; skipping uv-based detection")
+        return None
+
+    if result.returncode != 0:
+        logger.debug(
+            "uv python find exited with code %d; skipping",
+            result.returncode,
+        )
+        return None
+
+    python_path = Path(result.stdout.strip())
+    if not python_path.is_file():
+        logger.debug("uv reported interpreter '%s' but file not found", python_path)
+        return None
+
+    # Derive venv from interpreter path:
+    # .../venv/bin/python  → .../venv
+    # .../venv/Scripts/python.exe → .../venv
+    venv_dir = python_path.parent.parent
+    if (venv_dir / "pyvenv.cfg").is_file():
+        logger.debug("Auto-detected venv via uv at '%s'", venv_dir)
+        return venv_dir
+
+    logger.debug(
+        "uv interpreter '%s' is not inside a venv (no pyvenv.cfg)",
+        python_path,
+    )
     return None
 
 
@@ -151,12 +240,7 @@ def resolve_python_executable(python_arg: str) -> Path:
 
     # Directory — probe for interpreter
     if path.is_dir():
-        candidates = [
-            path / "Scripts" / "python.exe",  # Windows venv
-            path / "bin" / "python",  # Unix venv
-            path / "bin" / "python3",  # Unix alternative
-        ]
-        for candidate in candidates:
+        for candidate in (path / rel for rel in _INTERPRETER_CANDIDATES):
             if candidate.is_file():
                 logger.debug(
                     "Resolved venv directory '%s' to interpreter '%s'",
@@ -329,6 +413,9 @@ def env_tag_for_path(python_arg: str) -> str:
 
     Returns:
         An 8-character hex string derived from the resolved path.
+
+    Raises:
+        EnvironmentSetupError: If *python_arg* cannot be resolved.
     """
     resolved = resolve_python_executable(python_arg)
     return _env_tag_from_resolved(resolved)

{libcontext-0.6.1 → libcontext-0.7.0}/src/libcontext/cache.py

@@ -82,19 +82,20 @@ def _compute_source_stats(package_path: Path) -> _SourceStats:
 
     max_mtime = 0.0
     file_count = 0
-    for pattern in ("*.py", "*.pyi"):
-        for f in package_path.rglob(pattern):
-            if not is_within_boundary(f, package_path):
-                continue
-            if not check_file_size(f):
-                continue
-            try:
-                mtime = f.stat().st_mtime
-                if mtime > max_mtime:
-                    max_mtime = mtime
-                file_count += 1
-            except OSError:
-                continue
+    for f in package_path.rglob("*.py*"):
+        if f.suffix not in (".py", ".pyi"):
+            continue
+        if not is_within_boundary(f, package_path):
+            continue
+        if not check_file_size(f):
+            continue
+        try:
+            mtime = f.stat().st_mtime
+            if mtime > max_mtime:
+                max_mtime = mtime
+            file_count += 1
+        except OSError:
+            continue
     return _SourceStats(max_mtime=max_mtime, file_count=file_count)
 
 
@@ -128,8 +129,12 @@ def load(
     """
     cache_file = _get_cache_dir() / _cache_filename(package_name, version, env_tag)
 
-    if not cache_file.is_file():
-        logger.debug("Cache miss for %r: file not found", package_name)
+    try:
+        if not cache_file.is_file():
+            logger.debug("Cache miss for %r: file not found", package_name)
+            return None
+    except OSError:
+        logger.debug("Cache miss for %r: cannot access cache dir", package_name)
         return None
 
     try:
@@ -232,11 +237,13 @@ def _evict_oldest(cache_dir: Path) -> None:
             entries.append((f, f.stat().st_mtime))
         except OSError:
             continue
+    if len(entries) <= _MAX_CACHE_ENTRIES:
+        return
     entries.sort(key=lambda x: x[1])
-    while len(entries) > _MAX_CACHE_ENTRIES:
-        oldest_path, _ = entries.pop(0)
-        logger.debug("Evicting cache entry: %s", oldest_path.name)
-        _safe_delete(oldest_path)
+    to_remove = entries[: len(entries) - _MAX_CACHE_ENTRIES]
+    for path, _ in to_remove:
+        logger.debug("Evicting cache entry: %s", path.name)
+        _safe_delete(path)
 
 
 # ---------------------------------------------------------------------------
@@ -252,7 +259,11 @@ def clear_all() -> int:
     """
     cache_dir = _get_cache_dir()
     count = 0
-    for f in cache_dir.glob("*.json"):
+    try:
+        entries = list(cache_dir.glob("*.json"))
+    except OSError:
+        return 0
+    for f in entries:
         _safe_delete(f)
         count += 1
     return count

{libcontext-0.6.1 → libcontext-0.7.0}/src/libcontext/collector.py

@@ -50,13 +50,13 @@ def _get_installed_package_names() -> list[str]:
         try:
             for import_name in importlib.metadata.packages_distributions():
                 names.add(import_name)
-        except (ImportError, Exception):
-            # packages_distributions() may fail when the environment
-            # contains distributions with broken metadata or when a
-            # mixed Python installation causes an ImportError inside
-            # stdlib modules (e.g. csv).  Fall through to the
-            # distributions()-based collection below which is more
-            # resilient.
+        except Exception:
+            # Intentionally broad: packages_distributions() can fail
+            # in unpredictable ways depending on Python version and
+            # environment state (ImportError from broken stdlib
+            # modules, RuntimeError from corrupted metadata, etc.).
+            # The distributions()-based fallback below is more
+            # resilient, so any failure here is non-critical.
             logger.debug(
                 "packages_distributions() failed; falling back to distributions() only",
                 exc_info=True,
@@ -75,7 +75,10 @@ def _get_installed_package_names() -> list[str]:
         if normalized != dist_name:
             names.add(normalized)
 
-        top_level = dist.read_text("top_level.txt")
+        try:
+            top_level = dist.read_text("top_level.txt")
+        except OSError:
+            top_level = None
         if top_level:
             for line in top_level.strip().splitlines():
                 entry = line.strip()
@@ -409,6 +412,25 @@ def _find_readme(package_name: str, package_path: Path | None) -> str | None:
 # ---------------------------------------------------------------------------
 
 
+def _safe_rglob(root: Path, pattern: str) -> list[Path]:
+    """Like ``sorted(root.rglob(pattern))`` but tolerant of permission errors.
+
+    Collects as many matching files as possible before the first
+    inaccessible directory terminates the generator.
+    """
+    results: list[Path] = []
+    try:
+        for path in root.rglob(pattern):
+            results.append(path)
+    except PermissionError:
+        logger.warning(
+            "Permission denied while traversing '%s'; some modules may be missing",
+            root,
+        )
+    results.sort()
+    return results
+
+
 def _is_safe_source_file(file_path: Path, root: Path) -> bool:
     """Check that a source file is safe to read.
 
@@ -521,31 +543,25 @@ def _walk_package(
     # key = relative path without extension -> (py_path, pyi_path, stub_source)
     file_map: dict[str, tuple[Path | None, Path | None, str]] = {}
 
-    for py_file in sorted(package_path.rglob("*.py")):
-        if not _is_safe_source_file(py_file, package_path):
-            continue
-        relative = py_file.relative_to(package_path)
-        parts = relative.parts
-        if _should_skip_path(parts, include_private=config.include_private):
+    for source_file in _safe_rglob(package_path, "*.py*"):
+        if source_file.suffix not in (".py", ".pyi"):
             continue
-        key = str(relative.with_suffix(""))
-        file_map[key] = (py_file, None, "")
-
-    # Colocated .pyi files
-    for pyi_file in sorted(package_path.rglob("*.pyi")):
-        if not _is_safe_source_file(pyi_file, package_path):
+        if not _is_safe_source_file(source_file, package_path):
             continue
-        relative = pyi_file.relative_to(package_path)
+        relative = source_file.relative_to(package_path)
         parts = relative.parts
         if _should_skip_path(parts, include_private=config.include_private):
             continue
         key = str(relative.with_suffix(""))
-        existing = file_map.get(key, (None, None, ""))
-        file_map[key] = (existing[0], pyi_file, "colocated")
+        if source_file.suffix == ".py":
+            file_map[key] = (source_file, None, "")
+        else:
+            existing = file_map.get(key, (None, None, ""))
+            file_map[key] = (existing[0], source_file, "colocated")
 
     # Standalone stub .pyi files
     if stub_path is not None:
-        for pyi_file in sorted(stub_path.rglob("*.pyi")):
+        for pyi_file in _safe_rglob(stub_path, "*.pyi"):
             if not _is_safe_source_file(pyi_file, stub_path):
                 continue
             relative = pyi_file.relative_to(stub_path)

{libcontext-0.6.1 → libcontext-0.7.0}/src/libcontext/config.py

@@ -41,7 +41,7 @@ class LibcontextConfig:
         """Create config from a dictionary (e.g. parsed TOML section).
 
         Raises:
-            TypeError: If a value has an unexpected type.
+            ConfigError: If a value has an unexpected type.
         """
         include_modules = data.get("include_modules", [])
         exclude_modules = data.get("exclude_modules", [])
@@ -120,6 +120,9 @@ def read_config_from_pyproject(pyproject_path: Path) -> LibcontextConfig:
 
     Returns:
         LibcontextConfig parsed from the file, or defaults if not found.
+
+    Raises:
+        ConfigError: If a config value has an unexpected type.
     """
     data = _load_toml(pyproject_path)
     tool_config = data.get("tool", {}).get("libcontext", {})

{libcontext-0.6.1 → libcontext-0.7.0}/src/libcontext/exceptions.py

@@ -36,7 +36,11 @@ class PackageNotFoundError(LibcontextError):
             joined = ", ".join(self.suggestions)
             msg += f" Did you mean: {joined}?"
         else:
-            msg += " Make sure it is installed in the current environment."
+            msg += (
+                " Make sure it is installed in the current environment."
+                " If installed in a project venv, run from the project"
+                " directory or use --python <path-to-venv>."
+            )
         super().__init__(msg)
 
 

{libcontext-0.6.1 → libcontext-0.7.0}/src/libcontext/inspector.py

@@ -353,6 +353,9 @@ def inspect_source(
 
     Returns:
         ModuleInfo containing all extracted components.
+
+    Raises:
+        SyntaxError: If *source* is not valid Python.
     """
     tree = ast.parse(source)
 

{libcontext-0.6.1 → libcontext-0.7.0}/src/libcontext/mcp_server.py

@@ -274,6 +274,9 @@ def main() -> None:
     2. ``LIBCONTEXT_PYTHON`` env var → use that environment.
     3. Auto-detect ``.venv/`` or ``venv/`` in CWD → use the detected venv.
     4. None of the above → use the current process's environment.
+
+    Raises:
+        EnvironmentSetupError: If an explicit ``--python`` path is invalid.
     """
     import os
     import sys as _sys