toolfuncs 0.3.3__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: toolfuncs
-Version: 0.3.3
+Version: 0.4.0
 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
@@ -20,11 +20,11 @@ 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 filename is its command name and dynamic Python import name. 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 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.
 
 ## Write a toolfunc
 
-Create an extensionless file named `weather`:
+Create an extensionless file named `weather-report`:
 
 ```python
 #!/usr/bin/env toolfuncs
@@ -33,12 +33,14 @@ Create an extensionless file named `weather`:
 # dependencies = ["weather-client"]
 # [tool.toolfuncs]
 # description = "Read current weather conditions."
+# cli_name = "weather-report"
+# python_name = "weather_report"
 # ///
 
-import toolfuncs
+import toolfuncs.sdk as toolsdk
 import weather_client
 
-app = toolfuncs.App()
+app = toolsdk.App()
 
 
 @app.command
@@ -49,8 +51,8 @@ def current(city: str) -> dict[str, object]:
 Make it executable and place it in any existing `PATH` directory:
 
 ```console
-chmod +x weather
-mv weather ~/.local/bin/
+chmod +x weather-report
+mv weather-report ~/.local/bin/
 ```
 
 That is the complete registration operation.
@@ -60,31 +62,25 @@ That is the complete registration operation.
 The executable is the CLI:
 
 ```console
-$ weather current London
+$ 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`:
 
 ```python
-from toolfuncs import weather
+import toolfuncs as tools
 
-conditions = weather.current("London")
-```
-
-The explicit equivalent is useful when a tool name conflicts with a public package attribute:
-
-```python
-import toolfuncs
-
-weather = toolfuncs.load("weather")
+conditions = tools.weather_report.current("London")
 ```
 
 `import_path()` is the narrower utility for a local script whose path is already
 known:
 
 ```python
-module = toolfuncs.import_path("scripts/prepare_data.py")
+import toolfuncs as tools
+
+module = tools.import_path("scripts/prepare_data.py")
 ```
 
 It accepts one ordinary `.py` file or extensionless script and derives the
@@ -96,23 +92,23 @@ environment before import. A caller can replace that behavior with one callable
 that accepts `list[str]` and returns `None`:
 
 ```python
-module = toolfuncs.import_path(
+module = tools.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`.
+Direct Python calls return ordinary Python objects and raise the original exceptions. Dynamic tool attributes 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
 
 A discoverable toolfunc must:
 
 1. be one executable file in a directory on `PATH`;
-2. have an extensionless filename that is a valid non-keyword Python identifier;
+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` and a one-line `[tool.toolfuncs].description`;
-5. define a module-level `app = toolfuncs.App()`;
+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;
+5. define a module-level `app = toolsdk.App()` after `import toolfuncs.sdk as toolsdk`;
 6. register each CLI-callable function explicitly with `@app.command`.
 
 The PEP 723 dependency list contains the packages needed in addition to the running toolfuncs environment. Listing `toolfuncs` itself is accepted but normally redundant because the shebang has already started the toolfuncs runtime before dependencies are prepared.
@@ -127,7 +123,7 @@ The launcher consumes `--allow-floating-vcs`; the tool's Cyclopts app never sees
 
 Only functions registered on `app` become CLI commands. Imported functions and `__all__` do not define the command surface. Function command and option spelling follows Cyclopts' Python-to-kebab-case projection.
 
-No `if __name__ == "__main__":` block is required. The operating system passes the source path to the shebang interpreter, and toolfuncs imports the source under its filename before invoking its module-level app. Consequently, `weather ...` is the supported CLI while `python weather ...` merely defines the module and exits, or fails if its dependencies are not already installed.
+No `if __name__ == "__main__":` block is required. The operating system passes the source path to the shebang interpreter, and toolfuncs imports the source under its declared Python name before invoking its module-level app. Consequently, `weather-report ...` is the supported CLI while `python weather-report ...` merely defines the module and exits, or fails if its dependencies are not already installed.
 
 ## Package-backed implementations
 
@@ -140,6 +136,8 @@ A toolfunc remains one script even when most of its implementation lives in a pa
 # dependencies = ["my-large-package"]
 # [tool.toolfuncs]
 # description = "Run the package's agent operation."
+# cli_name = "package-operation"
+# python_name = "package_operation"
 # ///
 
 from my_large_package.agent_tool import app, perform_operation
@@ -151,9 +149,9 @@ The imported `app` and functions are the original Python objects. Toolfuncs does
 
 Toolfuncs reads the current process's `PATH` from left to right. It considers only executable files and symlinks, reads their first line, and parses PEP 723 metadata only when either exact toolfuncs shebang matches.
 
-The first executable filename claims a command name even when it is not a toolfunc. Therefore an ordinary executable earlier on `PATH` hides a same-named toolfunc later on `PATH`, matching what the shell actually executes. Repeated directories are scanned once, inaccessible directories are skipped, and discovered records are sorted by name.
+The first executable filename claims a command name even when it is not a toolfunc. Therefore an ordinary executable earlier on `PATH` hides a same-named toolfunc later on `PATH`, matching what the shell actually executes. Repeated directories are scanned once, inaccessible directories are skipped, and discovered records are sorted by CLI name.
 
-`toolfuncs list` returns static JSON records containing `name`, `path`, and `description`. It never imports a tool, prepares its dependencies, or executes its source.
+`toolfuncs list` returns one JSON object with `tools` and `invalid_tools`. Valid records contain `cli_name`, `python_name`, `path`, and `description`. An opted-in but invalid tool is reported with its path and validation error without hiding unrelated valid tools; the command also prints a concise warning to stderr and exits successfully. Listing never imports a tool, prepares its dependencies, or executes its source.
 
 ## Install the runtime
 
@@ -196,12 +194,12 @@ The installed hook runs at initial session start and at the session-start event
 
 ```text
 Available toolfuncs:
-- `weather`: Read current weather conditions.
-  CLI: `weather --help`
-  Python: `from toolfuncs import weather`
+- `weather_report`: Read current weather conditions.
+  CLI: `weather-report --help`
+  Python: `import toolfuncs as tools; tools.weather_report`
 ```
 
-The hook reads only executable headers and PEP 723 metadata. It does not import tools or resolve their dependencies. The hook itself is harness infrastructure, not a toolfunc, and therefore does not carry the toolfuncs shebang or appear in the catalog.
+The hook reads only executable headers and PEP 723 metadata. It advertises valid tools and lists invalid tool paths and errors separately; one invalid tool does not suppress the others. It does not import tools or resolve their dependencies. The hook itself is harness infrastructure, not a toolfunc, and therefore does not carry the toolfuncs shebang or appear in the catalog.
 
 ## Development
 
@@ -213,7 +211,7 @@ uv run ruff check .
 uv run basedpyright
 ```
 
-The exact 0.2 guarantees and non-goals are recorded in [the contract](docs/contract.md).
+The exact 0.4 guarantees and non-goals are recorded in [the contract](docs/contract.md).
 
 ## Releasing
 

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

@@ -2,11 +2,11 @@
 
 `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 filename is its command name and dynamic Python import name. 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 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.
 
 ## Write a toolfunc
 
-Create an extensionless file named `weather`:
+Create an extensionless file named `weather-report`:
 
 ```python
 #!/usr/bin/env toolfuncs
@@ -15,12 +15,14 @@ Create an extensionless file named `weather`:
 # dependencies = ["weather-client"]
 # [tool.toolfuncs]
 # description = "Read current weather conditions."
+# cli_name = "weather-report"
+# python_name = "weather_report"
 # ///
 
-import toolfuncs
+import toolfuncs.sdk as toolsdk
 import weather_client
 
-app = toolfuncs.App()
+app = toolsdk.App()
 
 
 @app.command
@@ -31,8 +33,8 @@ def current(city: str) -> dict[str, object]:
 Make it executable and place it in any existing `PATH` directory:
 
 ```console
-chmod +x weather
-mv weather ~/.local/bin/
+chmod +x weather-report
+mv weather-report ~/.local/bin/
 ```
 
 That is the complete registration operation.
@@ -42,31 +44,25 @@ That is the complete registration operation.
 The executable is the CLI:
 
 ```console
-$ weather current London
+$ 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`:
 
 ```python
-from toolfuncs import weather
+import toolfuncs as tools
 
-conditions = weather.current("London")
-```
-
-The explicit equivalent is useful when a tool name conflicts with a public package attribute:
-
-```python
-import toolfuncs
-
-weather = toolfuncs.load("weather")
+conditions = tools.weather_report.current("London")
 ```
 
 `import_path()` is the narrower utility for a local script whose path is already
 known:
 
 ```python
-module = toolfuncs.import_path("scripts/prepare_data.py")
+import toolfuncs as tools
+
+module = tools.import_path("scripts/prepare_data.py")
 ```
 
 It accepts one ordinary `.py` file or extensionless script and derives the
@@ -78,23 +74,23 @@ environment before import. A caller can replace that behavior with one callable
 that accepts `list[str]` and returns `None`:
 
 ```python
-module = toolfuncs.import_path(
+module = tools.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`.
+Direct Python calls return ordinary Python objects and raise the original exceptions. Dynamic tool attributes 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
 
 A discoverable toolfunc must:
 
 1. be one executable file in a directory on `PATH`;
-2. have an extensionless filename that is a valid non-keyword Python identifier;
+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` and a one-line `[tool.toolfuncs].description`;
-5. define a module-level `app = toolfuncs.App()`;
+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;
+5. define a module-level `app = toolsdk.App()` after `import toolfuncs.sdk as toolsdk`;
 6. register each CLI-callable function explicitly with `@app.command`.
 
 The PEP 723 dependency list contains the packages needed in addition to the running toolfuncs environment. Listing `toolfuncs` itself is accepted but normally redundant because the shebang has already started the toolfuncs runtime before dependencies are prepared.
@@ -109,7 +105,7 @@ The launcher consumes `--allow-floating-vcs`; the tool's Cyclopts app never sees
 
 Only functions registered on `app` become CLI commands. Imported functions and `__all__` do not define the command surface. Function command and option spelling follows Cyclopts' Python-to-kebab-case projection.
 
-No `if __name__ == "__main__":` block is required. The operating system passes the source path to the shebang interpreter, and toolfuncs imports the source under its filename before invoking its module-level app. Consequently, `weather ...` is the supported CLI while `python weather ...` merely defines the module and exits, or fails if its dependencies are not already installed.
+No `if __name__ == "__main__":` block is required. The operating system passes the source path to the shebang interpreter, and toolfuncs imports the source under its declared Python name before invoking its module-level app. Consequently, `weather-report ...` is the supported CLI while `python weather-report ...` merely defines the module and exits, or fails if its dependencies are not already installed.
 
 ## Package-backed implementations
 
@@ -122,6 +118,8 @@ A toolfunc remains one script even when most of its implementation lives in a pa
 # dependencies = ["my-large-package"]
 # [tool.toolfuncs]
 # description = "Run the package's agent operation."
+# cli_name = "package-operation"
+# python_name = "package_operation"
 # ///
 
 from my_large_package.agent_tool import app, perform_operation
@@ -133,9 +131,9 @@ The imported `app` and functions are the original Python objects. Toolfuncs does
 
 Toolfuncs reads the current process's `PATH` from left to right. It considers only executable files and symlinks, reads their first line, and parses PEP 723 metadata only when either exact toolfuncs shebang matches.
 
-The first executable filename claims a command name even when it is not a toolfunc. Therefore an ordinary executable earlier on `PATH` hides a same-named toolfunc later on `PATH`, matching what the shell actually executes. Repeated directories are scanned once, inaccessible directories are skipped, and discovered records are sorted by name.
+The first executable filename claims a command name even when it is not a toolfunc. Therefore an ordinary executable earlier on `PATH` hides a same-named toolfunc later on `PATH`, matching what the shell actually executes. Repeated directories are scanned once, inaccessible directories are skipped, and discovered records are sorted by CLI name.
 
-`toolfuncs list` returns static JSON records containing `name`, `path`, and `description`. It never imports a tool, prepares its dependencies, or executes its source.
+`toolfuncs list` returns one JSON object with `tools` and `invalid_tools`. Valid records contain `cli_name`, `python_name`, `path`, and `description`. An opted-in but invalid tool is reported with its path and validation error without hiding unrelated valid tools; the command also prints a concise warning to stderr and exits successfully. Listing never imports a tool, prepares its dependencies, or executes its source.
 
 ## Install the runtime
 
@@ -178,12 +176,12 @@ The installed hook runs at initial session start and at the session-start event
 
 ```text
 Available toolfuncs:
-- `weather`: Read current weather conditions.
-  CLI: `weather --help`
-  Python: `from toolfuncs import weather`
+- `weather_report`: Read current weather conditions.
+  CLI: `weather-report --help`
+  Python: `import toolfuncs as tools; tools.weather_report`
 ```
 
-The hook reads only executable headers and PEP 723 metadata. It does not import tools or resolve their dependencies. The hook itself is harness infrastructure, not a toolfunc, and therefore does not carry the toolfuncs shebang or appear in the catalog.
+The hook reads only executable headers and PEP 723 metadata. It advertises valid tools and lists invalid tool paths and errors separately; one invalid tool does not suppress the others. It does not import tools or resolve their dependencies. The hook itself is harness infrastructure, not a toolfunc, and therefore does not carry the toolfuncs shebang or appear in the catalog.
 
 ## Development
 
@@ -195,7 +193,7 @@ uv run ruff check .
 uv run basedpyright
 ```
 
-The exact 0.2 guarantees and non-goals are recorded in [the contract](docs/contract.md).
+The exact 0.4 guarantees and non-goals are recorded in [the contract](docs/contract.md).
 
 ## Releasing
 

toolfuncs-0.4.0/docs/contract.md

@@ -0,0 +1,81 @@
+# toolfuncs 0.4 contract
+
+## Purpose
+
+Toolfuncs projects one explicitly registered set of typed Python functions into ordinary in-process Python calls and a strict-JSON command line. It is a source convention and runtime, not a transport protocol, package format, registry, plugin system, or filesystem scope.
+
+## 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`.
+
+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 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:
+
+```toml
+[tool.toolfuncs]
+description = "Describe the tool in one line."
+cli_name = "session-history"
+python_name = "session_history"
+```
+
+The declared names do not override runtime identity. `cli_name` must equal the PATH entry's filename, and `python_name` must equal the mechanically derived Python name. A source reached through a symlink therefore documents the symlink basename rather than its target basename. One source has one supported CLI identity; aliases are not part of the contract.
+
+The source imports the authoring API as `import toolfuncs.sdk as toolsdk`, defines a module-level `app`, normally `app = toolsdk.App()`, and registers every CLI-callable operation explicitly. Function signatures, annotations, defaults, docstrings, return values, side effects, and exceptions define the operations. `__all__` retains its ordinary Python meaning and does not register commands.
+
+`toolsdk.App` supplies strict JSON serialization as its default result action. An explicit `result_action=` replaces that default unchanged. Advanced builder values such as `Parameter`, `Group`, validators, and result helpers live under `toolfuncs.sdk`, not the package root.
+
+## Python interface
+
+The standard Python interface is:
+
+```python
+import toolfuncs as tools
+
+hits = tools.session_history.search("Cyclopts")
+module = tools.import_path("scripts/prepare_data.py")
+```
+
+Dynamic attribute lookup maps the requested snake-case Python name to its kebab-case PATH command, validates the source and its declared identities, prepares its PEP 723 requirements in the current interpreter, and imports the source under the Python name. A loaded name retains one canonical source and module object. A different source or pre-existing Python module using the same name is a clear conflict rather than an implicit replacement.
+
+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.
+
+## Dependencies
+
+For CLI execution, the managed wrapper passes the source to `uvx --with-requirements` and starts toolfuncs inside the resulting cached environment. The runtime then imports the prepared source without installing its requirements again. For direct Python composition, dynamic attribute loading installs requirements into the running interpreter with pip before import. The current interpreter must satisfy `requires-python`, and preparation and loading are serialized within a process.
+
+The `toolfuncs` distribution may appear in `dependencies`, but it is redundant because the shebang has already started the runtime. A script may import any installed implementation package; that package is not itself a toolfunc.
+
+Git requirements are immutable by default. A direct Git URL must name a full 40- or 64-hex commit object ID. A branch, tag, abbreviated hash, or omitted revision fails before dependency resolution unless the source explicitly uses the floating-VCS shebang. An adjacent `uv lock --script` lock is not consumed by the toolfuncs launch path.
+
+## Discovery
+
+Discovery reads the current `PATH` from left to right. The first executable filename claims that command before its shebang is inspected, so an earlier ordinary executable hides a later same-named toolfunc exactly as the shell does. Repeated resolved directories are visited once, and missing or unreadable directories are skipped.
+
+An exact-shebang source opts into validation. Discovery records an invalid opted-in source instead of raising and suppressing unrelated tools. The internal catalog contains sorted valid `Tool(cli_name, python_name, path, description)` records and sorted `InvalidTool(path, error)` records.
+
+`toolfuncs list` emits one JSON object with `tools` and `invalid_tools`, prints a concise warning with invalid paths and errors to stderr, and exits successfully even when invalid entries exist. The startup hook advertises valid tools and reports invalid tools separately. Discovery and listing never import source, prepare dependencies, or execute tool code.
+
+Direct invocation or Python lookup of an invalid tool fails with its validation error.
+
+## 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.
+
+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.
+
+Successful default CLI operations emit one strict JSON value. CLI parsing, validation, dependency, or execution failures exit nonzero. Direct Python calls return original objects and raise original exceptions.
+
+## Setup and management
+
+`uvx toolfuncs setup` installs one managed uvx wrapper in `~/.local/bin` or an explicit `--bin-dir`, plus the agent-catalog hook wrapper. The destination must already resolve from `PATH`. Setup is idempotent, refuses to overwrite unmanaged commands, and never modifies shell profiles.
+
+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 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.
+
+## Compatibility
+
+Version 0.4 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.3.3 → toolfuncs-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "toolfuncs"
-version = "0.3.3"
+version = "0.4.0"
 description = "Executable typed Python function tools discovered through PATH"
 readme = "README.md"
 authors = [

toolfuncs-0.4.0/src/toolfuncs/__init__.py

@@ -0,0 +1,38 @@
+"""Typed Python tools with matching command-line interfaces."""
+
+from __future__ import annotations
+
+import types as _types
+
+from ._errors import InvalidToolError as _InvalidToolError
+from ._errors import ToolNotFoundError as _ToolNotFoundError
+from ._import_path import import_path
+from ._tools import _cli_name_for_python_name, _discover, _load_python_name
+
+__all__ = ["import_path"]
+
+_PUBLIC_NAMES = frozenset({"import_path", "sdk"})
+
+
+def __getattr__(python_name: str) -> _types.ModuleType:
+    """Dynamically expose PATH tools by their declared Python names."""
+
+    if python_name.startswith("_") or python_name in _PUBLIC_NAMES:
+        raise AttributeError(python_name)
+    try:
+        _cli_name_for_python_name(python_name)
+    except _InvalidToolError:
+        raise AttributeError(python_name) from None
+    try:
+        module = _load_python_name(python_name)
+    except _ToolNotFoundError:
+        raise AttributeError(f"module {__name__!r} has no attribute {python_name!r}") from None
+    globals()[python_name] = module
+    return module
+
+
+def __dir__() -> list[str]:
+    """Include valid effective PATH tools in interactive completion."""
+
+    catalog = _discover()
+    return sorted(_PUBLIC_NAMES | {tool.python_name for tool in catalog.tools})

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

@@ -4,22 +4,24 @@ from __future__ import annotations
 
 import json
 import sys
-from collections.abc import Sequence
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
 from dataclasses import asdict
+from importlib.metadata import version
 from pathlib import Path
 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,
     TOOL_SHEBANG,
+    InvalidTool,
+    _discover,
     _load_prepared_source,
     _load_source,
     _validate_source_dependencies,
-    discover,
 )
 from .sdk import _run
 
@@ -37,6 +39,18 @@ Floating Git revisions require the explicit shebang:
 """
 
 
+@contextmanager
+def _tool_program_name(source: Path) -> Iterator[None]:
+    """Expose the source executable as the invoked app's program name."""
+
+    previous = sys.argv[0]
+    sys.argv[0] = source.name
+    try:
+        yield
+    finally:
+        sys.argv[0] = previous
+
+
 def main(argv: Sequence[str] | None = None) -> int:
     """Run a source supplied by its shebang or dispatch a management command."""
 
@@ -47,7 +61,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     if tokens[0] in {"-V", "--version"}:
         if len(tokens) != 1:
             raise SystemExit("toolfuncs --version accepts no arguments")
-        print(__version__)
+        print(version("toolfuncs"))
         return 0
 
     command = tokens.pop(0)
@@ -55,7 +69,9 @@ def main(argv: Sequence[str] | None = None) -> int:
         if not tokens:
             raise SystemExit("toolfuncs internal error: missing prepared source")
         source = Path(tokens.pop(0))
-        result = _run(_load_prepared_source(source), tokens)
+        module = _load_prepared_source(source)
+        with _tool_program_name(source):
+            result = _run(module, tokens)
         return result if isinstance(result, int) else 0
     if command == "__validate-source":
         if len(tokens) != 1:
@@ -65,7 +81,9 @@ def main(argv: Sequence[str] | None = None) -> int:
     if command == "list":
         if tokens:
             raise SystemExit("toolfuncs list accepts no arguments")
-        _print_json([asdict(tool) for tool in discover()])
+        catalog = _discover()
+        _print_json(asdict(catalog))
+        _warn_invalid_tools(catalog.invalid_tools)
         return 0
     if command == "setup":
         destination = _parse_setup(tokens)
@@ -75,7 +93,9 @@ def main(argv: Sequence[str] | None = None) -> int:
     source = Path(command)
     if not source.is_file():
         raise SystemExit(f"unknown toolfuncs command or missing source: {command}")
-    result = _run(_load_source(source), tokens)
+    module = _load_source(source)
+    with _tool_program_name(source):
+        result = _run(module, tokens)
     return result if isinstance(result, int) else 0
 
 
@@ -91,5 +111,15 @@ def _print_json(value: Any) -> None:
     print(json.dumps(value, default=to_jsonable_python, allow_nan=False))
 
 
+def _warn_invalid_tools(invalid_tools: tuple[InvalidTool, ...]) -> None:
+    if not invalid_tools:
+        return
+    count = len(invalid_tools)
+    noun = "toolfunc" if count == 1 else "toolfuncs"
+    print(f"warning: found {count} invalid {noun}:", file=sys.stderr)
+    for invalid in invalid_tools:
+        print(f"- {invalid.path}: {invalid.error}", file=sys.stderr)
+
+
 if __name__ == "__main__":
     raise SystemExit(main())