Source code for pyretis.bin.cli

#!/usr/bin/env python3
# Copyright (c) 2026, PyRETIS Development Team.
# Distributed under the LGPLv2.1+ License. See LICENSE for more info.
"""pyretis - The unified PyRETIS command-line interface.

This is the single entry point for PyRETIS. It dispatches a sub-command
to the matching tool::

    pyretis run -i input.toml         # run a simulation  (was pyretisrun)
    pyretis analyse -i analysis.txt   # analyse output    (was pyretisanalyse)
    pyretis clean                     # remove run artifacts in a directory

The ``run`` and ``analyse`` sub-commands take exactly the same options as
the standalone command they replace; ``pyretis <command> -h`` shows them.
The standalone ``pyretisrun`` and ``pyretisanalyse`` commands still work
but are deprecated: from PyRETIS 5 only ``pyretis run`` and
``pyretis analyse`` will be supported.
"""
# pylint: disable=invalid-name
import importlib
import sys

from pyretis import __version__ as VERSION
from pyretis.info import PROGRAM_NAME, URL


# Each sub-command maps to the ``(module, entry-point attribute)`` of the
# tool that implements it. The import is done lazily when the command is
# selected, so only the chosen tool's (heavy) module is loaded.
_COMMANDS = {
    'run': ('pyretis.bin.pyretisrun', 'entry_point'),
    # ``analyse`` is the canonical spelling (matching the historical
    # ``pyretisanalyse`` command); ``analyze`` is accepted as an alias.
    'analyse': ('pyretis.bin.pyretisanalyse', 'entry_point'),
    'analyze': ('pyretis.bin.pyretisanalyse', 'entry_point'),
    'clean': ('pyretis.bin.pyretisclean', 'entry_point'),
}




def usage():
    """Return the top-level usage text for the unified CLI.

    Returns
    -------
    string
        The multi-line usage / help text.

    """
    lines = [
        'usage: pyretis <command> [options]',
        '',
        f'{PROGRAM_NAME} unified command-line interface.',
        '',
        'commands:',
        '  run        Run a simulation (same options as the old pyretisrun).',
        '  analyse    Analyse output (as the old pyretisanalyse command).',
        '  clean      Remove the artifacts of a run in a directory.',
        '',
        'Run "pyretis <command> -h" to see the options of a command.',
        f'More information about {PROGRAM_NAME} can be found at: {URL}',
    ]
    return '\n'.join(lines)





def entry_point():  # pragma: no cover
    """Dispatch ``pyretis <command> ...`` to the matching tool.

    The first argument selects the sub-command; every remaining argument
    is handed unchanged to that tool's own argument parser.
    """
    argv = sys.argv[1:]

    # No command, or an explicit top-level help request.
    if not argv or argv[0] in ('-h', '--help'):
        print(usage())
        # An explicit -h is a success; a bare ``pyretis`` is a usage error.
        sys.exit(0 if argv else 2)

    # Top-level version, so ``pyretis -V`` works like the sub-commands.
    if argv[0] in ('-V', '--version'):
        print(f'{PROGRAM_NAME} {VERSION}')
        sys.exit(0)

    command = argv[0]
    if command not in _COMMANDS:
        sys.stderr.write(f'pyretis: unknown command "{command}".\n\n')
        sys.stderr.write(usage() + '\n')
        sys.exit(2)

    module_name, attribute = _COMMANDS[command]
    # Rewrite argv so the sub-command's argparse sees only its own
    # options. argv[0] becomes the program name shown in that command's
    # help / usage text, e.g. "pyretis run".
    sys.argv = [f'pyretis {command}'] + argv[1:]
    module = importlib.import_module(module_name)
    sub_entry_point = getattr(module, attribute)
    sub_entry_point()



if __name__ == '__main__':  # pragma: no cover
    entry_point()