Extending QType CLI¶

QType supports third-party CLI plugins through Python entry points. This allows developers to extend the QType CLI with custom commands without modifying the core codebase.

Creating a Plugin¶

1. Define Your Command Function¶

Create a module with a parser function that takes a subparsers object and registers your command:

# my_package/qtype_commands.py
import argparse

def my_command_parser(subparsers: argparse._SubParsersAction) -> None:
    """Register the 'my-command' subcommand."""
    parser = subparsers.add_parser(
        'my-command',
        help='My custom QType command'
    )
    parser.add_argument(
        '--option',
        help='An example option'
    )
    # Set the function to call when this command is invoked
    parser.set_defaults(func=my_command_handler)

def my_command_handler(args: argparse.Namespace) -> None:
    """Handle the 'my-command' subcommand."""
    print(f"Running my-command with option: {args.option}")

2. Register the Entry Point¶

Add the entry point to your package's pyproject.toml:

[project.entry-points."qtype.commands"]
my-command = "my_package.qtype_commands:my_command_parser"

Or if using setup.py:

from setuptools import setup

setup(
    name="my-qtype-plugin",
    # ... other setup parameters
    entry_points={
        "qtype.commands": [
            "my-command = my_package.qtype_commands:my_command_parser",
        ],
    },
)

3. Install and Test¶

After installing your package, the command will be automatically available:

pip install my-qtype-plugin
qtype my-command --option "test"

Best Practices¶

Naming: Use descriptive command names and avoid conflicts with built-in commands
Error Handling: Handle errors gracefully and provide helpful error messages
Documentation: Include help text for your commands and arguments
Dependencies: Declare any additional dependencies your plugin requires
Testing: Test your plugin with different versions of QType

Debugging Plugins¶

To see debug information about plugin loading, run QType with debug logging:

qtype --log-level DEBUG my-command

This will show which plugins are being loaded and any errors that occur during the loading process.

Example Plugin Structure¶

my-qtype-plugin/
├── pyproject.toml
├── my_package/
│   ├── __init__.py
│   └── qtype_commands.py
└── tests/
    └── test_plugin.py