Developing New PypeIt Scripts

All of the PypeIt executable scripts are located in the pypeit/scripts directory, and they all have roughly the same structure:

from pypeit.scripts import scriptbase

class NewScript(scriptbase.ScriptBase):

    @classmethod
    def get_parser(cls, width=None):
        parser = super().get_parser(description='A new PypeIt script', width=width)
        ...

    @staticmethod
    def main(args):
        ...

The important components of the scripts are:

  • To ease installation and documentation of the scripts, they all must use ScriptBase as their base class. Note that the class has no instantiation method.

  • The get_parser() function returns an instance of argparse.ArgumentParser used to parse the command-line arguments.

  • The main() function performs the primary operations of the script. It needs no return value, but a return is not prohibited (see, e.g., ChkForCalibs).

  • Each file in the pypeit/scripts directory should only contain one script class. The name() function sets the name of the script to pypeit_{module} by default, where {module} is the name of the file. E.g., if the file name of the new script is new_script.py the executable installed will be pypeit_new_script. This can be altered by overriding the base class name function (see RunPypeIt).

The base class, ScriptBase, provides the common entry point function (entry_point()) used during installation. To ensure that the script is properly installed by pip, you need to add this entry point to the pypeit/pyproject.toml file. All of the PypeIt scripts are listed in the [options.entry_points] group. To add your script, you enter a new line with the following format:

pypeit_new_script = pypeit.scripts.new_script:NewScript.entry_point

Lastly, you should add the script module name to the __all__ list in the pypeit/scripts/__init__.py file; i.e., add:

__all__ = [
    ...
    'new_script',
    ...
]

Preferably add the new script name in a way that maintains the alphabetical ordering of the scripts in the list.

Note that the script files in the pypeit/scripts directory:

  • Should not be executable (i.e., no x in their permissions)

  • Should not start with an env statement; i.e., #!/usr/bin/env python

  • Should not end with the if __name__ == '__main__': block

Creating the executables from the raw script files is all handled by pip installing PypeIt. To ensure the script is installed, from the top-level directory run, e.g.:

pip install -e ".[dev]"

If the new script doesn’t appear in your path after running this, you may need to uninstall (pip uninstall pypeit) and reinstall using the command above.