toolfuncs 0.6.0__tar.gz → 0.7.0__tar.gz

{toolfuncs-0.6.0 → toolfuncs-0.7.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: toolfuncs
-Version: 0.6.0
-Summary: Executable typed Python function tools discovered through PATH
+Version: 0.7.0
+Summary: Executable typed Python function tools invoked by path or discovered through PATH
 Project-URL: Repository, https://github.com/nimashoghi/toolfuncs
 Project-URL: Issues, https://github.com/nimashoghi/toolfuncs/issues
 Author-email: Nima Shoghi <nima@boltz.bio>
@@ -20,7 +20,7 @@ Description-Content-Type: text/markdown
 
 `toolfuncs` turns typed Python functions into tools that have matching Python and command-line interfaces.
 
-A toolfunc is one executable Python script on `PATH`. Its lowercase kebab-case filename is its command name, and its Python import name is the same spelling with hyphens replaced by underscores. Its implementation may import any packages declared in its PEP 723 requirements, but packages and projects are not themselves discoverable toolfuncs.
+A toolfunc is one executable Python script. Its lowercase kebab-case filename is its command name, and its Python import name is the same spelling with hyphens replaced by underscores. A known source can be called or imported directly from any path. Putting it on `PATH` additionally makes its filename a shell command and exposes it to discovery and dynamic Python lookup. Its implementation may import any packages declared in its PEP 723 requirements, but packages and projects are not themselves toolfuncs.
 
 ## Write a toolfunc
 
@@ -56,25 +56,44 @@ def current(city: str) -> dict[str, object]:
     return weather_client.current(city)
 ```
 
-Make it executable and place it in any existing `PATH` directory:
+Make it executable:
 
 ```console
 chmod +x weather-report
-mv weather-report ~/.local/bin/
 ```
 
-That is the complete registration operation.
+No registration operation is required. Move it to an existing `PATH` directory only when it should be globally discoverable:
+
+```console
+mv weather-report ~/.local/bin/
+```
 
 ## Call it
 
-The executable is the CLI:
+A known source can be run explicitly without adding it to `PATH`:
+
+```console
+$ toolfuncs ./weather-report current London
+{"city": "London", "temperature": 18}
+```
+
+When the source is on `PATH`, its filename is also the CLI:
 
 ```console
 $ weather-report current London
 {"city": "London", "temperature": 18}
 ```
 
-The same file is dynamically importable in a Python process that has `toolfuncs` installed and the same `PATH`:
+A known source is importable by path:
+
+```python
+import toolfuncs as tools
+
+weather_report = tools.import_path("./weather-report")
+conditions = weather_report.current("London")
+```
+
+When the source is on `PATH`, the same file is also dynamically importable by name in a Python process with that `PATH`:
 
 ```python
 import toolfuncs as tools
@@ -82,8 +101,7 @@ import toolfuncs as tools
 conditions = tools.weather_report.current("London")
 ```
 
-`import_path()` is the narrower utility for a local script whose path is already
-known:
+`import_path()` also works for an ordinary local Python script whose path is already known:
 
 ```python
 import toolfuncs as tools
@@ -91,8 +109,7 @@ import toolfuncs as tools
 module = tools.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,
+It accepts one ordinary `.py` file or extensionless script and derives the module name from its filename. An extensionless lowercase kebab-case filename is mapped to its snake-case Python name. 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
@@ -110,9 +127,9 @@ Direct Python calls return ordinary Python objects and raise the original except
 
 ## Source contract
 
-A discoverable toolfunc must:
+A toolfunc source must:
 
-1. be one executable file in a directory on `PATH`;
+1. be one executable file;
 2. have an extensionless lowercase ASCII kebab-case filename;
 3. start with one of the two exact toolfuncs shebangs described below;
 4. contain exactly one PEP 723 `script` block with `dependencies`, a one-line description, and required `cli_name` and `python_name` documentation that exactly matches the filename-derived identities;
@@ -215,12 +232,13 @@ Setup does not discover, copy, register, link, synchronize, or remove tools. The
 ## Management commands
 
 ```console
+toolfuncs SOURCE [ARGS...]
 toolfuncs doctor SOURCE
 toolfuncs list
 toolfuncs setup [--bin-dir DIRECTORY]
 ```
 
-The source-path argument supplied automatically by `#!/usr/bin/env toolfuncs` is runtime plumbing rather than another user-facing command. Tools are invoked directly by their own names.
+`toolfuncs SOURCE [ARGS...]` runs a known source directly. This is the explicit-source interface, not a name dispatcher: `toolfuncs weather-report` resolves `weather-report` as a source path rather than searching `PATH` for that tool name. A toolfunc on `PATH` can instead be invoked directly by its own filename.
 
 ## Agent integration
 
@@ -245,7 +263,7 @@ uv run ruff check .
 uv run basedpyright
 ```
 
-The exact 0.4 guarantees and non-goals are recorded in [the contract](docs/contract.md).
+The exact guarantees and non-goals are recorded in [the contract](docs/contract.md).
 
 ## Releasing
 

{toolfuncs-0.6.0 → toolfuncs-0.7.0}/README.md

@@ -2,7 +2,7 @@
 
 `toolfuncs` turns typed Python functions into tools that have matching Python and command-line interfaces.
 
-A toolfunc is one executable Python script on `PATH`. Its lowercase kebab-case filename is its command name, and its Python import name is the same spelling with hyphens replaced by underscores. Its implementation may import any packages declared in its PEP 723 requirements, but packages and projects are not themselves discoverable toolfuncs.
+A toolfunc is one executable Python script. Its lowercase kebab-case filename is its command name, and its Python import name is the same spelling with hyphens replaced by underscores. A known source can be called or imported directly from any path. Putting it on `PATH` additionally makes its filename a shell command and exposes it to discovery and dynamic Python lookup. Its implementation may import any packages declared in its PEP 723 requirements, but packages and projects are not themselves toolfuncs.
 
 ## Write a toolfunc
 
@@ -38,25 +38,44 @@ def current(city: str) -> dict[str, object]:
     return weather_client.current(city)
 ```
 
-Make it executable and place it in any existing `PATH` directory:
+Make it executable:
 
 ```console
 chmod +x weather-report
-mv weather-report ~/.local/bin/
 ```
 
-That is the complete registration operation.
+No registration operation is required. Move it to an existing `PATH` directory only when it should be globally discoverable:
+
+```console
+mv weather-report ~/.local/bin/
+```
 
 ## Call it
 
-The executable is the CLI:
+A known source can be run explicitly without adding it to `PATH`:
+
+```console
+$ toolfuncs ./weather-report current London
+{"city": "London", "temperature": 18}
+```
+
+When the source is on `PATH`, its filename is also the CLI:
 
 ```console
 $ weather-report current London
 {"city": "London", "temperature": 18}
 ```
 
-The same file is dynamically importable in a Python process that has `toolfuncs` installed and the same `PATH`:
+A known source is importable by path:
+
+```python
+import toolfuncs as tools
+
+weather_report = tools.import_path("./weather-report")
+conditions = weather_report.current("London")
+```
+
+When the source is on `PATH`, the same file is also dynamically importable by name in a Python process with that `PATH`:
 
 ```python
 import toolfuncs as tools
@@ -64,8 +83,7 @@ import toolfuncs as tools
 conditions = tools.weather_report.current("London")
 ```
 
-`import_path()` is the narrower utility for a local script whose path is already
-known:
+`import_path()` also works for an ordinary local Python script whose path is already known:
 
 ```python
 import toolfuncs as tools
@@ -73,8 +91,7 @@ import toolfuncs as tools
 module = tools.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,
+It accepts one ordinary `.py` file or extensionless script and derives the module name from its filename. An extensionless lowercase kebab-case filename is mapped to its snake-case Python name. 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
@@ -92,9 +109,9 @@ Direct Python calls return ordinary Python objects and raise the original except
 
 ## Source contract
 
-A discoverable toolfunc must:
+A toolfunc source must:
 
-1. be one executable file in a directory on `PATH`;
+1. be one executable file;
 2. have an extensionless lowercase ASCII kebab-case filename;
 3. start with one of the two exact toolfuncs shebangs described below;
 4. contain exactly one PEP 723 `script` block with `dependencies`, a one-line description, and required `cli_name` and `python_name` documentation that exactly matches the filename-derived identities;
@@ -197,12 +214,13 @@ Setup does not discover, copy, register, link, synchronize, or remove tools. The
 ## Management commands
 
 ```console
+toolfuncs SOURCE [ARGS...]
 toolfuncs doctor SOURCE
 toolfuncs list
 toolfuncs setup [--bin-dir DIRECTORY]
 ```
 
-The source-path argument supplied automatically by `#!/usr/bin/env toolfuncs` is runtime plumbing rather than another user-facing command. Tools are invoked directly by their own names.
+`toolfuncs SOURCE [ARGS...]` runs a known source directly. This is the explicit-source interface, not a name dispatcher: `toolfuncs weather-report` resolves `weather-report` as a source path rather than searching `PATH` for that tool name. A toolfunc on `PATH` can instead be invoked directly by its own filename.
 
 ## Agent integration
 
@@ -227,7 +245,7 @@ uv run ruff check .
 uv run basedpyright
 ```
 
-The exact 0.4 guarantees and non-goals are recorded in [the contract](docs/contract.md).
+The exact guarantees and non-goals are recorded in [the contract](docs/contract.md).
 
 ## Releasing
 

{toolfuncs-0.6.0 → toolfuncs-0.7.0}/docs/contract.md

@@ -1,4 +1,4 @@
-# toolfuncs 0.6 contract
+# toolfuncs 0.7 contract
 
 ## Purpose
 
@@ -6,9 +6,9 @@ Toolfuncs projects one explicitly registered set of typed Python functions into
 
 ## Tool identity and source
 
-A toolfunc is one executable regular file or symlink in a directory on `PATH`. Its first line is exactly `#!/usr/bin/env toolfuncs`, or the explicit floating-VCS form `#!/usr/bin/env -S toolfuncs --allow-floating-vcs`.
+A toolfunc is one executable regular file or symlink. Its first line is exactly `#!/usr/bin/env toolfuncs`, or the explicit floating-VCS form `#!/usr/bin/env -S toolfuncs --allow-floating-vcs`.
 
-The PATH-visible extensionless filename is the CLI command and must use lowercase ASCII kebab-case: a letter followed by letters or digits, with optional single hyphens separating further nonempty letter-or-digit segments. The Python name is the CLI name with every hyphen replaced by an underscore. A Python name that conflicts with `toolfuncs.sdk` or `toolfuncs.import_path` is invalid.
+The extensionless filename is the CLI command and must use lowercase ASCII kebab-case: a letter followed by letters or digits, with optional single hyphens separating further nonempty letter-or-digit segments. The Python name is the CLI name with every hyphen replaced by an underscore. A Python name that conflicts with `toolfuncs.sdk` or `toolfuncs.import_path` is invalid.
 
 The source contains exactly one PEP 723 `script` block. `dependencies` is a list of valid Python requirement strings and `requires-python` is optional. `[tool.toolfuncs]` contains exactly three required documentation fields:
 
@@ -40,7 +40,7 @@ Dynamic attribute lookup maps the requested snake-case Python name to its kebab-
 
 The package root publicly exposes only dynamic tools and `import_path`. There is no public `load`, discovery, setup, record, error, or builder API at the root. `import toolfuncs.NAME` is not promised because discovered tools are dynamic package attributes rather than installed submodules.
 
-`import_path` remains separate. It imports one already-known local `.py` file or extensionless script, derives its module name from that source filename, optionally prepares ordinary PEP 723 dependencies, and does not require the toolfuncs shebang, identity metadata, executable permission, or a module-level app.
+`import_path` remains separate. It imports one already-known local `.py` file or extensionless script, derives its module name from that source filename, maps a valid extensionless kebab-case filename to snake case, optionally prepares ordinary PEP 723 dependencies, and does not require the toolfuncs shebang, identity metadata, executable permission, or a module-level app.
 
 ## Dependencies
 
@@ -68,7 +68,7 @@ The command emits one strict-JSON tagged union. `DoctorSuccess` has `status: "su
 
 ## CLI execution
 
-When the operating system executes a tool, `/usr/bin/env` resolves the managed `toolfuncs` wrapper on `PATH` and passes it the PATH-visible source path followed by the user's arguments. The wrapper validates dependency policy, starts one uv-prepared environment, and invokes the runtime. Toolfuncs validates identity metadata, imports the source under `python_name`, obtains its module-level app, preserves the exact CLI filename as the Cyclopts program name, and invokes the app with the remaining arguments.
+`toolfuncs SOURCE [ARGS...]` runs a known source without requiring that source to be on `PATH`. It resolves `SOURCE` as a filesystem path and does not search `PATH` for a tool name. When the operating system executes a tool that is on `PATH`, `/usr/bin/env` resolves the managed `toolfuncs` wrapper and passes it the source path followed by the user's arguments. In either form, the wrapper validates dependency policy, starts one uv-prepared environment, and invokes the runtime. Toolfuncs validates identity metadata, imports the source under `python_name`, obtains its module-level app, preserves the exact CLI filename as the Cyclopts program name, and invokes the app with the remaining arguments.
 
 The source is imported rather than executed as `__main__`. A main guard is neither required nor used. Plain `python SOURCE ...` does not invoke the CLI and does not prepare PEP 723 dependencies.
 
@@ -80,8 +80,8 @@ Successful default CLI operations emit one strict JSON value. CLI parsing, valid
 
 Setup does not discover, install, copy, link, register, synchronize, or remove tool sources. Adding and removing tools are ordinary filesystem operations in directories already on `PATH`.
 
-The public management commands are `toolfuncs doctor SOURCE`, `toolfuncs list`, and `toolfuncs setup [--bin-dir DIRECTORY]`. Tools are invoked directly by their own CLI names. There is no universal name dispatcher, `run`, `exec`, `describe`, or `sync` command.
+The public management commands are `toolfuncs doctor SOURCE`, `toolfuncs list`, and `toolfuncs setup [--bin-dir DIRECTORY]`. The explicit-source execution form is `toolfuncs SOURCE [ARGS...]`; it is not a universal name dispatcher. Tools on `PATH` are invoked directly by their own CLI names. There is no `run`, `exec`, `describe`, or `sync` command.
 
 ## Compatibility
 
-Version 0.6 retains the 0.4 runtime and identity contract and adds the authoring doctor. It intentionally does not accept the former underscore executable names, missing identity declarations, root-level builder exports, public `load`, or public discovery records. All controlled tools must migrate with the runtime.
+Version 0.7 adds public explicit-source CLI execution and maps extensionless kebab-case names to snake case in `import_path`. It retains the 0.6 runtime, identity, discovery, and authoring contracts. It intentionally does not accept the former underscore executable names, missing identity declarations, root-level builder exports, public `load`, or public discovery records. All controlled tools must migrate with the runtime.

{toolfuncs-0.6.0 → toolfuncs-0.7.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "toolfuncs"
-version = "0.6.0"
-description = "Executable typed Python function tools discovered through PATH"
+version = "0.7.0"
+description = "Executable typed Python function tools invoked by path or discovered through PATH"
 readme = "README.md"
 authors = [
     { name = "Nima Shoghi", email = "nima@boltz.bio" }

{toolfuncs-0.6.0 → toolfuncs-0.7.0}/src/toolfuncs/__main__.py

@@ -29,13 +29,17 @@ from .sdk import _run
 _HELP = f"""\
 Usage:
   toolfuncs --version
+  toolfuncs SOURCE [ARGS...]
   toolfuncs doctor SOURCE
   toolfuncs list
   toolfuncs setup [--bin-dir DIRECTORY]
 
-A toolfunc is an executable Python script on PATH whose first line is exactly:
+A toolfunc is an executable Python script whose first line is exactly:
   {TOOL_SHEBANG}
 
+Run a known source with `toolfuncs SOURCE [ARGS...]`. Put it on PATH to invoke
+it by filename and make it available to discovery and dynamic Python lookup.
+
 Floating Git revisions require the explicit shebang:
   {ALLOW_FLOATING_VCS_SHEBANG}
 """

{toolfuncs-0.6.0 → toolfuncs-0.7.0}/src/toolfuncs/_import_path.py

@@ -37,6 +37,7 @@ _PEP723_BLOCK = re.compile(
     r"(?m)^# /// (?P<type>[a-zA-Z0-9-]+)[ \t]*$[\r\n]"
     r"(?P<content>(?:^#(?:| .*)$[\r\n]?)+)^# ///[ \t]*$"
 )
+_EXTENSIONLESS_MODULE_NAME = re.compile(r"[a-z][a-z0-9]*(?:-[a-z0-9]+)*\Z")
 _IMPORT_LOCK = threading.RLock()
 
 
@@ -87,10 +88,11 @@ def import_path(
     """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.
+    filename determines the module name; valid extensionless kebab-case names
+    map to snake case. 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)
@@ -152,6 +154,8 @@ def _module_name(source: Path) -> str:
         name = source.stem
     elif not source.suffix:
         name = source.name
+        if _EXTENSIONLESS_MODULE_NAME.fullmatch(name):
+            name = name.replace("-", "_")
     else:
         raise ValueError(f"Python script must be extensionless or end in '.py': {source}")
     if not name.isidentifier() or keyword.iskeyword(name):

{toolfuncs-0.6.0 → toolfuncs-0.7.0}/tests/test_import_path.py

@@ -43,6 +43,30 @@ def test_import_path_accepts_extensionless_script(
     assert imported.VALUE == 43
 
 
+def test_import_path_maps_extensionless_kebab_case_to_snake_case(
+    tmp_path: Path,
+    unique_name: str,
+) -> None:
+    source = tmp_path / f"{unique_name}-job"
+    source.write_text("VALUE = 44\n", encoding="utf-8")
+
+    imported = import_path(source)
+
+    assert imported.__name__ == f"{unique_name}_job"
+    assert imported.VALUE == 44
+
+
+def test_import_path_rejects_malformed_extensionless_kebab_case(
+    tmp_path: Path,
+    unique_name: str,
+) -> None:
+    source = tmp_path / f"{unique_name}--job"
+    source.write_text("VALUE = 45\n", encoding="utf-8")
+
+    with pytest.raises(ValueError, match="valid Python module name"):
+        import_path(source)
+
+
 def test_pep723_dependencies_are_passed_as_one_list_before_import(
     tmp_path: Path,
     unique_name: str,

{toolfuncs-0.6.0 → toolfuncs-0.7.0}/tests/test_sdk_cli.py

@@ -34,7 +34,16 @@ 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.6.0\n"
+    assert completed.stdout == "0.7.0\n"
+    assert completed.stderr == ""
+
+
+def test_cli_help_advertises_explicit_source_execution(tmp_path: Path) -> None:
+    completed = run_python(["-m", "toolfuncs", "--help"], cwd=tmp_path)
+
+    assert completed.returncode == 0
+    assert "toolfuncs SOURCE [ARGS...]" in completed.stdout
+    assert "Run a known source" in completed.stdout
     assert completed.stderr == ""
 
 
@@ -106,6 +115,31 @@ def test_runtime_requires_a_module_level_app(tmp_path: Path) -> None:
     assert "must define 'app'" in completed.stderr
 
 
+def test_explicit_source_runs_without_being_on_path(tmp_path: Path) -> None:
+    source = tmp_path / "local-tool"
+    _write_executable(
+        source,
+        _script(
+            "local-tool",
+            "Local tool",
+            "import toolfuncs.sdk as toolsdk\n\n"
+            "app = toolsdk.App()\n\n"
+            "@app.command\n"
+            "def ping() -> str:\n"
+            "    return 'pong'\n",
+        ),
+    )
+
+    completed = run_python(
+        ["-m", "toolfuncs", str(source), "ping"],
+        cwd=tmp_path,
+        env={"PATH": os.defpath},
+    )
+
+    assert completed.returncode == 0, completed.stderr
+    assert json.loads(completed.stdout) == "pong"
+
+
 @pytest.mark.parametrize("prepared", [False, True])
 @pytest.mark.parametrize(
     ("app_definition", "expected_name"),

{toolfuncs-0.6.0 → toolfuncs-0.7.0}/uv.lock

@@ -601,7 +601,7 @@ wheels = [
 
 [[package]]
 name = "toolfuncs"
-version = "0.6.0"
+version = "0.7.0"
 source = { editable = "." }
 dependencies = [
     { name = "cyclopts" },