Merge pull request #4 from martinmoldrup/features/add-a-plugin-system

Enhance CLI with plugin system and error handling

Author: martinmoldrup

CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to this project will be documented in this file.
 ## [0.3.0] - 09-09-2025
 - Added toolit `create-vscode-tasks-json` CLI command to create the `.vscode/tasks.json` file from the command line.
 - Improved error handling and user feedback when the `devtools` folder does not exist.
+- Added a plugin system to all for loading tools automatically from installed packages.
 
 ## [0.2.0] - 16-06-2025
 - Fix problem with subdependencies not being installed

README.md

@@ -71,5 +71,15 @@ def my_parallel_commands() -> list[Callable]:
 
 This will create a group of commands in the `tasks.json` file that can be executed sequentially or in parallel.
 
+## Creating Plugins
+Toolit supports a plugin system that allows you to create and share your own tools as separate packages. This makes it easy to reuse tools across different projects, without needing to copy and update tools across multiple codebases.
+
+To create a plugin, follow these steps:
+1. Create a new Python package for your plugin. You can use tools like `setuptools`, `poetry` or `uv` to set up your package structure.
+2. In your package, create a module where you define your tools using the `@tool` decorator.
+3. Make sure to include `toolit` as a dependency in your package's `setup.py` or `pyproject.toml`.
+4. Register your plugin with Toolit by adding an entry point in your `setup.py` or `pyproject.toml`, so Toolit can discover your tools when the package is installed. The entry point is called `toolit_plugins`.
+5. Publish your package to PyPI or install it from a git repository where you need it.
+
 ## Contributing
 We welcome contributions to Toolit! If you have ideas for new features, improvements, or bug fixes, please open an issue or submit a pull request on our GitHub repository. We appreciate your feedback and support in making Toolit even better for the community.

devtools/create_new_release.py

@@ -1,4 +1,5 @@
 """Create a new release for the project, by reading the version from the pyproject.toml file, and adding and pushing a new tag to the repository."""
+
 import os
 import subprocess
 import toml
@@ -11,20 +12,23 @@
 CHANGELOG_MD = pathlib.Path(__file__).parent.parent / "CHANGELOG.md"
 PYPI_ENDPOINT = "https://pypi.org/pypi/toolit/json"
 
+
 def read_version():
     """Read the version from the pyproject.toml file."""
     with open(PYPROJECT_TOML, "r", encoding="utf-8") as file:
         data = toml.load(file)
     return data["project"]["version"]
 
+
 def check_version(version: str):
     """Check if the version is newer than the one in pypi."""
     response = requests.get(PYPI_ENDPOINT)
     pypi_version = response.json()["info"]["version"]
     print(f"Version in pypi: {pypi_version}")
     if Version(version) <= Version(pypi_version):
         raise ValueError(f"Version {version} is not newer than the one in pypi: {pypi_version}")
-    
+
+
 def check_change_log(version: str):
     """Check if the version has a corresponding entry in the change log. It will be a line starting with ## [0.0.2]"""
     with open(CHANGELOG_MD, "r", encoding="utf-8") as file:
@@ -34,6 +38,7 @@ def check_change_log(version: str):
         raise ValueError(f"Version {version} does not have a corresponding entry in the change log.")
     print(f"Version {version} has a corresponding entry in the change log.")
 
+
 @tool
 def create_new_release():
     """Create a new release for the project, by reading the version from the pyproject.toml file, and adding and pushing a new tag to the repository."""
@@ -60,5 +65,6 @@ def create_new_release():
 
     print("Release created successfully.")
 
+
 if __name__ == "__main__":
-    create_new_release()
+    create_new_release()

toolit/auto_loader.py

@@ -12,10 +12,11 @@
 import inspect
 import pathlib
 import importlib
+import importlib.metadata
 from toolit.constants import MARKER_TOOL, ToolitTypesEnum
 from toolit.create_apps_and_register import register_command
 from types import FunctionType, ModuleType
-from typing import Callable
+from typing import Any, Callable
 
 
 def get_items_from_folder(
@@ -51,6 +52,14 @@ def tool_group_strategy(module: ModuleType) -> list[FunctionType]:
     return groups
 
 
+def load_tools_from_plugins() -> list[FunctionType]:
+    """Discover and return plugin commands via entry points."""
+    plugins = get_plugin_tools()
+    for plugin in plugins:
+        register_command(plugin)
+    return plugins
+
+
 def load_tools_from_folder(folder_path: pathlib.Path) -> list[FunctionType]:
     """
     Load all tools from a given folder and register them as commands.
@@ -108,3 +117,12 @@ def import_module(file: pathlib.Path) -> ModuleType:
         module_import_name = module_name
     module = importlib.import_module(module_import_name)
     return module
+
+
+def get_plugin_tools() -> list[FunctionType]:
+    """Discover and return plugin commands via entry points."""
+    plugins = []
+    for entry_point in importlib.metadata.entry_points().get("toolit_plugins", []):
+        plugin_func: Any = entry_point.load()
+        plugins.append(plugin_func)
+    return plugins

toolit/cli.py

@@ -1,13 +1,15 @@
 """CLI entry point for the toolit package."""
 import pathlib
-from .auto_loader import load_tools_from_folder, register_command
+from .auto_loader import load_tools_from_folder, load_tools_from_plugins, register_command
 from .create_apps_and_register import app
 from .create_tasks_json import create_vscode_tasks_json
 
 PATH = pathlib.Path() / "devtools"
 load_tools_from_folder(PATH)
+load_tools_from_plugins()
 register_command(create_vscode_tasks_json)
 
+
 if __name__ == "__main__":
     # Run the typer app
     app()

toolit/create_tasks_json.py

@@ -5,7 +5,13 @@
 import typer
 import inspect
 import pathlib
-from toolit.auto_loader import get_items_from_folder, get_toolit_type, tool_group_strategy, tool_strategy
+from toolit.auto_loader import (
+    get_items_from_folder,
+    get_plugin_tools,
+    get_toolit_type,
+    tool_group_strategy,
+    tool_strategy,
+)
 from toolit.constants import ToolitTypesEnum
 from types import FunctionType
 from typing import Any
@@ -17,9 +23,15 @@
 def create_vscode_tasks_json() -> None:
     """Create a tasks.json file based on the tools discovered in the project."""
     typer.echo(f"Creating tasks.json at {output_file_path}")
-    tools: list[FunctionType] = get_items_from_folder(PATH, tool_strategy)
-    tool_groups: list[FunctionType] = get_items_from_folder(PATH, tool_group_strategy)
-    tools.extend(tool_groups)
+    if PATH.exists() and PATH.is_dir():
+        tools: list[FunctionType] = get_items_from_folder(PATH, tool_strategy)
+        tool_groups: list[FunctionType] = get_items_from_folder(PATH, tool_group_strategy)
+        tools.extend(tool_groups)
+    else:
+        typer.echo(f"The devtools folder does not exist or is not a directory: {PATH.absolute().as_posix()}")
+        tools = []
+
+    tools.extend(get_plugin_tools())
     json_builder = TaskJsonBuilder()
     for tool in tools:
         json_builder.process_tool(tool)