Ship command-line entry point with package

README.md

@@ -118,7 +118,60 @@ For custom installations, please refer to our [Installation guide](docs/INSTALL.
 
 ## Getting Started
 
-Please see the [project quickstart](https://mit-psfc.github.io/disruption-py/quickstart/usage_quickstart/).
+A simple command-line entry point is installed as `disruption-py`:
+
+```bash
+# if you use poetry
+poetry run disruption-py
+
+# if you use uv
+uv run disruption-py
+```
+
+The command-line arguments, which are subject to change, are documented in the help message:
+
+```bash
+uv run disruption-py --help
+```
+```
+usage: disruption-py [-h] [-t TOKAMAK] [-m METHODS] [-e EFIT_TREE] [-b TIME_BASE] [-o OUTPUT_FILE] [-p PROCESSES] [-l LOG_LEVEL] [shots ...]
+
+positional arguments:
+  shots
+
+options:
+  -h, --help            show this help message and exit
+  -t TOKAMAK, --tokamak TOKAMAK
+  -m METHODS, --methods METHODS
+  -e EFIT_TREE, --efit-tree EFIT_TREE
+  -b TIME_BASE, --time-base TIME_BASE
+  -o OUTPUT_FILE, --output-file OUTPUT_FILE
+  -p PROCESSES, --processes PROCESSES
+  -l LOG_LEVEL, --log-level LOG_LEVEL
+```
+
+A typical invocation of the entry point would be:
+
+```bash
+uv run disruption-py -m get_efit_parameters -o efit.csv 1150805012 1150805020
+```
+
+The same entry point can also be invoked from Python:
+
+```python
+from disruption_py.workflow import cli
+out = cli()
+```
+
+A simplified and flattened version of our workflow is available, as well:
+
+```python
+from disruption_py.workflow import run
+out = run(*args)
+```
+
+A full-fledged disruption script enables the configuration of all the settings according to the specific use case.
+Please refer to our `examples/defaults.py` script for a quickstart workflow with all the default arguments clearly explained.
 
 
 ## Contributing

disruption_py/workflow.py

@@ -1,9 +1,11 @@
 #!/usr/bin/env python3
 
 """
-The main entrypoint for retrieving DisruptionPy data.
+main workflow
 """
 
+import argparse
+import os
 import time
 from itertools import repeat
 from multiprocessing import Pool
@@ -15,6 +17,7 @@
 from disruption_py.core.retrieval_manager import RetrievalManager
 from disruption_py.core.utils.misc import (
     get_elapsed_time,
+    get_temporary_folder,
     shot_msg,
     without_duplicates,
 )
@@ -34,6 +37,7 @@
     ShotlistSettingType,
     shotlist_setting_runner,
 )
+from tests.utils.factory import get_tokamak_test_shotlist
 
 
 def _execute_retrieval(args):
@@ -219,3 +223,61 @@ def _get_mds_instance(tokamak, mds_connection_initializer):
     if mds_connection_initializer:
         return mds_connection_initializer()
     return get_mdsplus_class(tokamak)
+
+
+def run(
+    tokamak, methods, shots, efit_tree, time_base, output_file, processes, log_level
+):
+    """
+    simple workflow.
+    """
+
+    if not tokamak:
+        tokamak = resolve_tokamak_from_environment()
+    if not shots:
+        shots, *_ = get_tokamak_test_shotlist(tokamak)
+    methods = methods or None
+
+    sett = RetrievalSettings(
+        efit_nickname_setting=efit_tree, time_setting=time_base, run_methods=methods
+    )
+    out = get_shots_data(
+        tokamak=tokamak,
+        shotlist_setting=shots,
+        retrieval_settings=sett,
+        num_processes=processes,
+        log_settings=log_level,
+        output_setting="dataframe",
+    )
+
+    if output_file:
+        output_file = os.path.realpath(output_file)
+    else:
+        output_file = os.path.join(get_temporary_folder(), "output.csv")
+    logger.info("Output: {output_file}", output_file=output_file)
+    out.to_csv(output_file, index=False)
+
+    return out
+
+
+def cli():
+    """
+    simple argument parser.
+    """
+
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument("shots", nargs="*")
+    parser.add_argument("-t", "--tokamak", type=str)
+    parser.add_argument("-m", "--methods", type=str, action="append")
+    parser.add_argument("-e", "--efit-tree", type=str, default="disruption")
+    parser.add_argument("-b", "--time-base", type=str, default="disruption_warning")
+    parser.add_argument("-o", "--output-file", type=str)
+    parser.add_argument("-p", "--processes", type=int, default=1)
+    parser.add_argument("-l", "--log-level", type=str, default="VERBOSE")
+
+    return run(**vars(parser.parse_args()))
+
+
+if __name__ == "__main__":
+    print(cli())

mkdocs.yml

@@ -29,7 +29,6 @@ nav:
   - Overview:
       - Background: index.md
       - Installation: INSTALL.md
-      - Quickstart: quickstart/usage_quickstart.md
   - Usage:
       - Entry points:
           - Workflow: usage/workflow_reference.md

pyproject.toml

@@ -73,7 +73,7 @@ requires-python = ">=3.11,<4"
 version = "0.11.0"
 
 [project.scripts]
-disruption-workflow = "examples.simple:cli"
+disruption-py = "disruption_py.workflow:cli"
 
 [project.urls]
 documentation = "https://mit-psfc.github.io/disruption-py/"