toolfuncs 0.3.1__tar.gz → 0.3.3__tar.gz

{toolfuncs-0.3.1 → toolfuncs-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: toolfuncs
-Version: 0.3.1
+Version: 0.3.3
 Summary: Executable typed Python function tools discovered through PATH
 Project-URL: Repository, https://github.com/nimashoghi/toolfuncs
 Project-URL: Issues, https://github.com/nimashoghi/toolfuncs/issues
@@ -80,7 +80,29 @@ import toolfuncs
 weather = toolfuncs.load("weather")
 ```
 
-Direct Python calls return ordinary Python objects and raise the original exceptions. `toolfuncs.load()` prepares the script's requirements in the running Python environment before import. CLI calls use Cyclopts to parse annotated values and serialize successful results as strict JSON through `pydantic-core`.
+`import_path()` is the narrower utility for a local script whose path is already
+known:
+
+```python
+module = toolfuncs.import_path("scripts/prepare_data.py")
+```
+
+It accepts one ordinary `.py` file or extensionless script and derives the
+module name from its filename. It does not require a shebang, executable bit,
+`[tool.toolfuncs]` metadata, or `App`, and it does not import packages, projects,
+distributions, or URLs. When an optional PEP 723 block exists, the default
+installer installs all declared requirements together into the running Python
+environment before import. A caller can replace that behavior with one callable
+that accepts `list[str]` and returns `None`:
+
+```python
+module = toolfuncs.import_path(
+    "scripts/prepare_data.py",
+    dependency_installer=my_installer,
+)
+```
+
+Direct Python calls return ordinary Python objects and raise the original exceptions. `toolfuncs.load()` and `toolfuncs.import_path()` prepare declared requirements in the running Python environment before import. CLI calls use Cyclopts to parse annotated values and serialize successful results as strict JSON through `pydantic-core`.
 
 ## Source contract
 

{toolfuncs-0.3.1 → toolfuncs-0.3.3}/README.md

@@ -62,7 +62,29 @@ import toolfuncs
 weather = toolfuncs.load("weather")
 ```
 
-Direct Python calls return ordinary Python objects and raise the original exceptions. `toolfuncs.load()` prepares the script's requirements in the running Python environment before import. CLI calls use Cyclopts to parse annotated values and serialize successful results as strict JSON through `pydantic-core`.
+`import_path()` is the narrower utility for a local script whose path is already
+known:
+
+```python
+module = toolfuncs.import_path("scripts/prepare_data.py")
+```
+
+It accepts one ordinary `.py` file or extensionless script and derives the
+module name from its filename. It does not require a shebang, executable bit,
+`[tool.toolfuncs]` metadata, or `App`, and it does not import packages, projects,
+distributions, or URLs. When an optional PEP 723 block exists, the default
+installer installs all declared requirements together into the running Python
+environment before import. A caller can replace that behavior with one callable
+that accepts `list[str]` and returns `None`:
+
+```python
+module = toolfuncs.import_path(
+    "scripts/prepare_data.py",
+    dependency_installer=my_installer,
+)
+```
+
+Direct Python calls return ordinary Python objects and raise the original exceptions. `toolfuncs.load()` and `toolfuncs.import_path()` prepare declared requirements in the running Python environment before import. CLI calls use Cyclopts to parse annotated values and serialize successful results as strict JSON through `pydantic-core`.
 
 ## Source contract
 

{toolfuncs-0.3.1 → toolfuncs-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "toolfuncs"
-version = "0.3.1"
+version = "0.3.3"
 description = "Executable typed Python function tools discovered through PATH"
 readme = "README.md"
 authors = [
@@ -38,6 +38,7 @@ dev = [
     "pytest>=8",
     "pytest-cov>=6",
     "ruff>=0.12",
+    "tomli>=2.2,<3",
     "typed-agent-hooks",
 ]
 

{toolfuncs-0.3.1 → toolfuncs-0.3.3}/src/toolfuncs/__init__.py

@@ -13,6 +13,7 @@ from ._errors import (
     ToolfuncsError,
     ToolNotFoundError,
 )
+from ._import_path import DependencyInstaller, import_path
 from ._setup import SetupResult, setup
 from ._tools import ALLOW_FLOATING_VCS_SHEBANG, TOOL_SHEBANG, Tool, discover, load
 from .sdk import (
@@ -28,7 +29,7 @@ from .sdk import (
     validators,
 )
 
-__version__ = "0.3.1"
+__version__ = "0.3.3"
 
 __all__ = [
     "ALLOW_FLOATING_VCS_SHEBANG",
@@ -36,6 +37,7 @@ __all__ = [
     "UNSET",
     "App",
     "DependencyError",
+    "DependencyInstaller",
     "Group",
     "InvalidToolError",
     "Parameter",
@@ -49,6 +51,7 @@ __all__ = [
     "ToolNotFoundError",
     "ToolfuncsError",
     "discover",
+    "import_path",
     "json_result_action",
     "load",
     "setup",

{toolfuncs-0.3.1 → toolfuncs-0.3.3}/src/toolfuncs/__main__.py

@@ -11,6 +11,7 @@ from typing import Any
 
 from pydantic_core import to_jsonable_python
 
+from . import __version__
 from ._setup import setup
 from ._tools import (
     ALLOW_FLOATING_VCS_SHEBANG,
@@ -24,6 +25,7 @@ from .sdk import _run
 
 _HELP = f"""\
 Usage:
+  toolfuncs --version
   toolfuncs list
   toolfuncs setup [--bin-dir DIRECTORY]
 
@@ -42,6 +44,11 @@ def main(argv: Sequence[str] | None = None) -> int:
     if not tokens or tokens[0] in {"-h", "--help", "help"}:
         print(_HELP, end="")
         return 0
+    if tokens[0] in {"-V", "--version"}:
+        if len(tokens) != 1:
+            raise SystemExit("toolfuncs --version accepts no arguments")
+        print(__version__)
+        return 0
 
     command = tokens.pop(0)
     if command == "__run-source":

toolfuncs-0.3.3/src/toolfuncs/_import_path.py

@@ -0,0 +1,258 @@
+"""Import one local Python script into the running interpreter."""
+
+from __future__ import annotations
+
+import importlib
+import importlib.abc
+import importlib.machinery
+import importlib.util
+import keyword
+import os
+import re
+import subprocess
+import sys
+import threading
+import weakref
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from importlib.machinery import ModuleSpec
+from pathlib import Path
+from types import ModuleType
+from typing import TypeAlias, cast
+
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
+from packaging.version import Version
+
+from ._errors import DependencyError, ToolConflictError
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+DependencyInstaller: TypeAlias = Callable[[list[str]], None]
+
+_PEP723_BLOCK = re.compile(
+    r"(?m)^# /// (?P<type>[a-zA-Z0-9-]+)[ \t]*$[\r\n]"
+    r"(?P<content>(?:^#(?:| .*)$[\r\n]?)+)^# ///[ \t]*$"
+)
+_IMPORT_LOCK = threading.RLock()
+
+
+@dataclass(frozen=True, slots=True)
+class _ScriptDependencies:
+    requirements: tuple[str, ...]
+    requires_python: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class _DirectImport:
+    name: str
+    source: Path
+
+
+_BY_SOURCE: dict[Path, ModuleType] = {}
+_SOURCE_BY_NAME: dict[str, Path] = {}
+_DIRECT_IMPORTS: weakref.WeakKeyDictionary[ModuleType, _DirectImport] = weakref.WeakKeyDictionary()
+
+
+class _DirectImportFinder(importlib.abc.MetaPathFinder):
+    """Rediscover script-backed module specs for ``importlib.reload``."""
+
+    def find_spec(
+        self,
+        fullname: str,
+        path: Sequence[str] | None = None,
+        target: ModuleType | None = None,
+    ) -> ModuleSpec | None:
+        del path
+        if target is None:
+            return None
+        with _IMPORT_LOCK:
+            direct_import = _DIRECT_IMPORTS.get(target)
+        if direct_import is None or direct_import.name != fullname:
+            return None
+        return _direct_import_spec(direct_import.name, direct_import.source)
+
+
+_DIRECT_IMPORT_FINDER = _DirectImportFinder()
+
+
+def import_path(
+    source: str | os.PathLike[str],
+    *,
+    dependency_installer: DependencyInstaller | None = None,
+) -> ModuleType:
+    """Import one local Python script.
+
+    ``source`` may be an ordinary ``.py`` file or an extensionless script. Its
+    filename determines the module name. When the source contains PEP 723
+    metadata, its requirements are installed as one list before import. Pass a
+    custom ``dependency_installer`` to replace the default current-interpreter
+    pip installation.
+    """
+
+    path = _source_path(source)
+    name = _module_name(path)
+    source_key = path.resolve(strict=True)
+    with _IMPORT_LOCK:
+        if imported := _BY_SOURCE.get(source_key):
+            return imported
+        if previous_source := _SOURCE_BY_NAME.get(name):
+            raise ToolConflictError(
+                f"script name {name!r} was already imported from {previous_source}, "
+                f"not {source_key}"
+            )
+        if name in sys.modules:
+            raise ToolConflictError(
+                f"cannot import {source_key} as {name!r}: that Python module name is already in use"
+            )
+
+        dependencies = _script_dependencies(path)
+        _require_compatible_python(dependencies, source=path)
+        if dependencies.requirements:
+            installer = dependency_installer or _default_dependency_installer
+            installer(list(dependencies.requirements))
+            importlib.invalidate_caches()
+
+        spec = _direct_import_spec(name, path)
+        assert spec.loader is not None
+        imported = importlib.util.module_from_spec(spec)
+        sys.modules[name] = imported
+        try:
+            spec.loader.exec_module(imported)
+        except BaseException:
+            if sys.modules.get(name) is imported:
+                sys.modules.pop(name, None)
+            raise
+
+        _BY_SOURCE[source_key] = imported
+        _SOURCE_BY_NAME[name] = source_key
+        _DIRECT_IMPORTS[imported] = _DirectImport(name, path)
+        if _DIRECT_IMPORT_FINDER not in sys.meta_path:
+            sys.meta_path.insert(0, _DIRECT_IMPORT_FINDER)
+        return imported
+
+
+def _source_path(source: str | os.PathLike[str]) -> Path:
+    raw = os.fspath(source)
+    if isinstance(raw, bytes):
+        raise TypeError("source must be a string path, not bytes")
+    if not raw:
+        raise ValueError("source path must not be empty")
+    path = Path(os.path.abspath(Path(raw).expanduser()))
+    if not path.is_file():
+        raise FileNotFoundError(f"Python script does not exist: {path}")
+    return path
+
+
+def _module_name(source: Path) -> str:
+    if source.suffix == ".py":
+        name = source.stem
+    elif not source.suffix:
+        name = source.name
+    else:
+        raise ValueError(f"Python script must be extensionless or end in '.py': {source}")
+    if not name.isidentifier() or keyword.iskeyword(name):
+        raise ValueError(
+            f"script filename does not define a valid Python module name: {source.name!r}"
+        )
+    return name
+
+
+def _script_dependencies(source: Path) -> _ScriptDependencies:
+    try:
+        text = source.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise ValueError(f"could not read Python script {source}: {exc}") from exc
+    blocks = [match for match in _PEP723_BLOCK.finditer(text) if match.group("type") == "script"]
+    if not blocks:
+        return _ScriptDependencies((), None)
+    if len(blocks) > 1:
+        raise ValueError(f"Python script {source} contains more than one PEP 723 'script' block")
+    content = "\n".join(
+        line[2:] if line.startswith("# ") else line[1:]
+        for line in blocks[0].group("content").splitlines()
+    )
+    try:
+        table = tomllib.loads(content)
+    except tomllib.TOMLDecodeError as exc:
+        raise ValueError(f"Python script {source} has invalid PEP 723 metadata: {exc}") from exc
+    return _dependencies_from_table(table, source=source)
+
+
+def _dependencies_from_table(
+    table: Mapping[str, object],
+    *,
+    source: Path,
+) -> _ScriptDependencies:
+    raw_dependencies = table.get("dependencies", [])
+    if not isinstance(raw_dependencies, list):
+        raise ValueError(f"{source}: PEP 723 'dependencies' must be a list of strings")
+    requirements: list[str] = []
+    for raw_dependency in cast(list[object], raw_dependencies):
+        if not isinstance(raw_dependency, str) or not raw_dependency.strip():
+            raise ValueError(f"{source}: PEP 723 dependencies must contain nonempty strings")
+        dependency = raw_dependency.strip()
+        try:
+            Requirement(dependency)
+        except InvalidRequirement as exc:
+            raise ValueError(f"{source}: invalid dependency {dependency!r}: {exc}") from exc
+        requirements.append(dependency)
+
+    requires_python: str | None = None
+    if (raw_requires_python := table.get("requires-python")) is not None:
+        if not isinstance(raw_requires_python, str) or not raw_requires_python.strip():
+            raise ValueError(f"{source}: PEP 723 'requires-python' must be a nonempty string")
+        requires_python = raw_requires_python.strip()
+        try:
+            SpecifierSet(requires_python)
+        except InvalidSpecifier as exc:
+            raise ValueError(
+                f"{source}: invalid 'requires-python' value {requires_python!r}"
+            ) from exc
+    return _ScriptDependencies(tuple(requirements), requires_python)
+
+
+def _require_compatible_python(metadata: _ScriptDependencies, *, source: Path) -> None:
+    if metadata.requires_python is None:
+        return
+    interpreter = Version(".".join(str(part) for part in sys.version_info[:3]))
+    if not SpecifierSet(metadata.requires_python).contains(interpreter, prereleases=True):
+        raise ValueError(
+            f"{source}: 'requires-python' {metadata.requires_python!r} does not admit "
+            f"the running interpreter {interpreter}"
+        )
+
+
+def _default_dependency_installer(requirements: list[str]) -> None:
+    completed = subprocess.run(
+        (
+            sys.executable,
+            "-m",
+            "pip",
+            "--disable-pip-version-check",
+            "install",
+            "--quiet",
+            *requirements,
+        ),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if completed.returncode:
+        raise DependencyError(
+            f"could not install script dependencies (pip exited {completed.returncode})"
+        )
+
+
+def _direct_import_spec(name: str, source: Path) -> ModuleSpec:
+    loader = importlib.machinery.SourceFileLoader(name, str(source))
+    spec = importlib.util.spec_from_loader(name, loader)
+    if spec is None:
+        raise ImportError(f"could not create an import specification for {source}")
+    return spec
+
+
+__all__ = ["DependencyInstaller", "import_path"]

toolfuncs-0.3.3/tests/test_import_path.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import importlib
+import subprocess
+import sys
+from pathlib import Path
+from types import ModuleType
+from typing import Any, cast
+
+import pytest
+
+import toolfuncs._import_path as import_path_module
+from toolfuncs import DependencyError, import_path
+
+
+def test_import_path_imports_plain_python_file_without_installing(
+    tmp_path: Path,
+    unique_name: str,
+) -> None:
+    source = tmp_path / f"{unique_name}.py"
+    source.write_text("VALUE = 41\n", encoding="utf-8")
+    calls: list[list[str]] = []
+
+    imported = import_path(source, dependency_installer=calls.append)
+
+    assert imported.__name__ == unique_name
+    assert imported.__file__ == str(source)
+    assert imported.VALUE == 41
+    assert calls == []
+
+
+def test_import_path_accepts_extensionless_script(
+    tmp_path: Path,
+    unique_name: str,
+) -> None:
+    source = tmp_path / unique_name
+    source.write_text("VALUE = 43\n", encoding="utf-8")
+
+    imported = import_path(source)
+
+    assert imported.__name__ == unique_name
+    assert imported.VALUE == 43
+
+
+def test_pep723_dependencies_are_passed_as_one_list_before_import(
+    tmp_path: Path,
+    unique_name: str,
+) -> None:
+    source = tmp_path / f"{unique_name}.py"
+    dependency_name = f"{unique_name}_dependency"
+    calls: list[list[str]] = []
+
+    def install(requirements: list[str]) -> None:
+        calls.append(requirements)
+        dependency = ModuleType(dependency_name)
+        cast(Any, dependency).VALUE = 47
+        sys.modules[dependency_name] = dependency
+
+    source.write_text(
+        "# /// script\n"
+        '# requires-python = ">=3.10"\n'
+        '# dependencies = ["demo-one>=1", "demo-two==2"]\n'
+        "# [tool.anything]\n"
+        '# ignored = "by import_path"\n'
+        "# ///\n"
+        f"import {dependency_name}\n"
+        f"VALUE = {dependency_name}.VALUE\n",
+        encoding="utf-8",
+    )
+    try:
+        imported = import_path(source, dependency_installer=install)
+
+        assert imported.VALUE == 47
+        assert calls == [["demo-one>=1", "demo-two==2"]]
+    finally:
+        sys.modules.pop(dependency_name, None)
+
+
+def test_default_installer_uses_current_interpreter_pip(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    unique_name: str,
+) -> None:
+    source = tmp_path / f"{unique_name}.py"
+    source.write_text(
+        '# /// script\n# dependencies = ["demo-package>=1"]\n# ///\nVALUE = 53\n',
+        encoding="utf-8",
+    )
+    calls: list[tuple[str, ...]] = []
+
+    def successful_install(
+        argv: tuple[str, ...],
+        **_: object,
+    ) -> subprocess.CompletedProcess[str]:
+        calls.append(argv)
+        return subprocess.CompletedProcess(argv, 0, "", "")
+
+    monkeypatch.setattr(import_path_module.subprocess, "run", successful_install)
+
+    assert import_path(source).VALUE == 53
+    assert calls == [
+        (
+            sys.executable,
+            "-m",
+            "pip",
+            "--disable-pip-version-check",
+            "install",
+            "--quiet",
+            "demo-package>=1",
+        )
+    ]
+
+
+def test_dependency_failure_prevents_import(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    unique_name: str,
+) -> None:
+    source = tmp_path / f"{unique_name}.py"
+    source.write_text(
+        '# /// script\n# dependencies = ["missing-package"]\n# ///\nVALUE = 59\n',
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(
+        import_path_module.subprocess,
+        "run",
+        lambda argv, **_: subprocess.CompletedProcess(argv, 3, "", "failed"),
+    )
+
+    with pytest.raises(DependencyError, match="pip exited 3"):
+        import_path(source)
+    assert unique_name not in sys.modules
+
+
+def test_incompatible_python_fails_before_custom_installer(
+    tmp_path: Path,
+    unique_name: str,
+) -> None:
+    source = tmp_path / f"{unique_name}.py"
+    source.write_text(
+        '# /// script\n# requires-python = "<3"\n# dependencies = ["demo"]\n# ///\n',
+        encoding="utf-8",
+    )
+
+    def forbidden_install(_requirements: list[str]) -> None:
+        raise AssertionError("installer must not run")
+
+    with pytest.raises(ValueError, match="does not admit"):
+        import_path(source, dependency_installer=forbidden_install)
+
+
+def test_import_path_caches_by_source_and_supports_reload(
+    tmp_path: Path,
+    unique_name: str,
+) -> None:
+    source = tmp_path / f"{unique_name}.py"
+    source.write_text("COUNT = globals().get('COUNT', 0) + 1\n", encoding="utf-8")
+
+    imported = import_path(source)
+    again = import_path(source)
+    reloaded = importlib.reload(imported)
+
+    assert imported is again is reloaded
+    assert imported.COUNT == 2
+
+
+def test_import_failure_removes_partial_module(
+    tmp_path: Path,
+    unique_name: str,
+) -> None:
+    source = tmp_path / f"{unique_name}.py"
+    source.write_text("raise RuntimeError('boom')\n", encoding="utf-8")
+
+    with pytest.raises(RuntimeError, match="boom"):
+        import_path(source)
+
+    assert unique_name not in sys.modules
+
+
+def test_import_path_rejects_non_script_suffix(tmp_path: Path, unique_name: str) -> None:
+    source = tmp_path / f"{unique_name}.txt"
+    source.write_text("VALUE = 1\n", encoding="utf-8")
+
+    with pytest.raises(ValueError, match=r"extensionless or end in '\.py'"):
+        import_path(source)

{toolfuncs-0.3.1 → toolfuncs-0.3.3}/tests/test_sdk_cli.py

@@ -25,6 +25,15 @@ from .conftest import run_python
 _INSTALL_HOOKS = setup_impl._install_hooks
 
 
+@pytest.mark.parametrize("flag", ["--version", "-V"])
+def test_cli_prints_installed_version(tmp_path: Path, flag: str) -> None:
+    completed = run_python(["-m", "toolfuncs", flag], cwd=tmp_path)
+
+    assert completed.returncode == 0
+    assert completed.stdout == "0.3.3\n"
+    assert completed.stderr == ""
+
+
 @pytest.fixture(autouse=True)
 def _avoid_installing_live_agent_hooks(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(setup_impl, "_install_hooks", lambda _hook_wrapper: None)

{toolfuncs-0.3.1 → toolfuncs-0.3.3}/uv.lock

@@ -601,7 +601,7 @@ wheels = [
 
 [[package]]
 name = "toolfuncs"
-version = "0.3.1"
+version = "0.3.3"
 source = { editable = "." }
 dependencies = [
     { name = "cyclopts" },
@@ -624,6 +624,7 @@ dev = [
     { name = "pytest" },
     { name = "pytest-cov" },
     { name = "ruff" },
+    { name = "tomli" },
     { name = "typed-agent-hooks" },
 ]
 
@@ -646,6 +647,7 @@ dev = [
     { name = "pytest", specifier = ">=8" },
     { name = "pytest-cov", specifier = ">=6" },
     { name = "ruff", specifier = ">=0.12" },
+    { name = "tomli", specifier = ">=2.2,<3" },
     { name = "typed-agent-hooks" },
 ]