CLI command plugins

An installed Python distribution can extend the ase2sprkkr command without modifying ASE2SPRKKR. A plugin exposes a Python package through the entry point named cli in the group ase2sprkkr:

[project.entry-points."ase2sprkkr"]
cli = "my_plugin.commands"

The target must be an importable package (with an __init__.py), not a single command module. Its immediate Python modules become CLI commands:

my_plugin/
    __init__.py
    commands/
        __init__.py
        analyse.py
        show_results.py

For example, show_results.py makes ase2sprkkr show-results available. Module filenames use underscores; CLI names use hyphens. Modules without a parser function are ignored.

Each command has the same interface as native commands:

help = "Analyse a calculation."
description = "Detailed description of the plugin command."
aliases = ["inspect"]  # optional

def parser(parser):
    parser.add_argument("filename")

def run(args, global_args):
    from my_plugin.analysis import analyse  # expensive imports belong here

    analyse(args.filename)

The required module members are help, description, parser(parser) and run(args, global_args). Optional members aliases, extra_help and unknowns behave as they do for native commands. global_args contains the global debug and profile flags. The plugin’s argument parser is initialized when its command (or alias) is selected. Here global_args['profile'] refers to Python profiling, not an SPR-KKR execution profile.

Install the plugin distribution in the same Python environment as ASE2SPRKKR, for example with pip install my-plugin. Its commands then appear in ase2sprkkr --help.

Native command names and aliases take precedence over plugin commands. If a plugin claims an already registered name or alias, that command is skipped with a diagnostic on stderr; other plugin commands remain available. A plugin whose entry point or command module fails to import is reported and skipped. Keep expensive imports inside the command’s run() function so unrelated CLI commands start quickly.