ENH: Adding Release command to IMAP CLI (#316)

tech3371 · web-flow · commit a471aad932c4 · 2026-05-26T16:46:56.000-06:00
diff --git a/imap_data_access/__init__.py b/imap_data_access/__init__.py
@@ -19,7 +19,7 @@
     ScienceFilePath,
     SPICEFilePath,
 )
-from imap_data_access.io import download, query, reprocess, spice_query, upload
+from imap_data_access.io import download, query, release, reprocess, spice_query, upload
 from imap_data_access.processing_input import (
     AncillaryInput,
     ProcessingInputCollection,
@@ -48,6 +48,7 @@
     "SpinInput",
     "download",
     "query",
+    "release",
     "reprocess",
     "spice_query",
     "upload",
diff --git a/imap_data_access/cli.py b/imap_data_access/cli.py
@@ -29,7 +29,8 @@
     ScienceFilePath,
     generate_imap_file_path,
 )
-from imap_data_access.io import query, spice_query
+from imap_data_access.io import query, release, spice_query
+from imap_data_access.utils import ReleaseType
 from imap_data_access.webpoda import download_daily_data
 
 
@@ -339,6 +340,27 @@ def _webpoda_parser(args: argparse.Namespace):
     print("Successfully downloaded the data from webpoda.")
 
 
+def _release_parser(args: argparse.Namespace):
+    """Submit a release request to the IMAP SDC.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        An object containing the parsed arguments and their values
+    """
+    # All validation is now handled in io.py
+    release(
+        instrument=args.instrument,
+        release_type=args.release_type,
+        start_date=args.start_date,
+        end_date=args.end_date,
+        release_number=args.release_number,
+        exclude_file=args.exclude_file,
+        manifest_file=args.manifest_file,
+    )
+    print("Successfully submitted release request to the IMAP SDC.")
+
+
 def add_query_args(subparser: ArgumentParser) -> None:
     """Add query arguments to subparser.
 
@@ -662,6 +684,98 @@ def main():
         help="Descriptor of the product to reprocess (raw, burst, etc.)",
     )
     reprocess_parser.set_defaults(func=_reprocess_parser)
+
+    # Release command
+    release_help = (
+        "Make a release or unrelease file for IMAP data with specified release type. "
+        "Run 'release -h' for more information."
+    )
+
+    parser_release = subparsers.add_parser(
+        "release",
+        help=release_help,
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    parser_release.add_argument(
+        "--instrument",
+        type=str,
+        required=True,
+        metavar="INSTRUMENT",
+        help="Name of the instrument (e.g., mag, swe, lo, codice)",
+        choices=imap_data_access.VALID_INSTRUMENTS,
+    )
+    parser_release.add_argument(
+        "--start-date",
+        type=str,
+        required=True,
+        metavar="YYYYMMDD",
+        help="Start date for the release",
+    )
+    parser_release.add_argument(
+        "--end-date",
+        type=str,
+        required=True,
+        metavar="YYYYMMDD",
+        help="End date for the release",
+    )
+    parser_release.add_argument(
+        "--release-type",
+        type=str,
+        required=True,
+        metavar="ReleaseType",
+        help=(
+            "Type of release:\n"
+            "- 'release': IMAP mission-wide public release. By default, all\n"
+            "  files are released unless specified in the --exclude-file to\n"
+            "  be withheld.\n"
+            "- 'early-release': Early release of selected files approved by\n"
+            "  both instrument and project. Use --manifest-file to specify\n"
+            "  files to release early.\n"
+            "- 'unrelease': Unrelease previously released files due to\n"
+            "  various causes and reasons. Use --manifest-file to specify\n"
+            "  files to unrelease."
+        ),
+        choices=[e.value for e in ReleaseType],
+    )
+    parser_release.add_argument(
+        "--release-number",
+        type=int,
+        required=False,
+        metavar="NUMBER",
+        help="Release number (required only when --release-type is 'release'). ",
+    )
+    parser_release.add_argument(
+        "--exclude-file",
+        type=str,
+        required=False,
+        metavar="PATH",
+        default=None,
+        help=(
+            "Path to a file listing files to exclude from public release.\n"
+            "Used for 'release' type to specify files to withhold.\n"
+            "File name should follow: \n  imap_<instrument>_withhold-data-"
+            "release-<###>_<start_date>_<end_date>_<version>.txt\n"
+        ),
+    )
+    parser_release.add_argument(
+        "--manifest-file",
+        type=str,
+        required=False,
+        metavar="PATH",
+        default=None,
+        help=(
+            "Path to a file listing files to apply action to in 'early-release'"
+            " or\n 'unrelease' types. This file serves as the manifest for files\n"
+            "to be released early or unreleased.\n"
+            "File name should follow:\n"
+            "  - early-release: "
+            "imap_<instrument>_early-release_<start_date>_<end_date>_<version>.txt\n"
+            "  - unrelease: "
+            "imap_<instrument>_unrelease_<start_date>_<end_date>_<version>.txt\n"
+        ),
+    )
+    parser_release.set_defaults(func=_release_parser)
+
     # Parse the arguments and set the values
     try:
         args = parser.parse_args()
diff --git a/imap_data_access/io.py b/imap_data_access/io.py
@@ -2,6 +2,7 @@
 
 import contextlib
 import logging
+import os
 from pathlib import Path
 from typing import Optional, Union
 
@@ -14,6 +15,7 @@
     ScienceFilePath,
     generate_imap_file_path,
 )
+from imap_data_access.utils import ReleaseType
 
 logger = logging.getLogger(__name__)
 
@@ -529,3 +531,131 @@ def upload(file_path: Union[Path, str]) -> None:
         )
 
     logger.info("File %s uploaded successfully", file_path)
+
+
+def release(
+    *,
+    instrument: str,
+    release_type: str,
+    start_date: str,
+    end_date: str,
+    release_number: Optional[int] = None,
+    exclude_file: Optional[Union[Path, str]] = None,
+    manifest_file: Optional[Union[Path, str]] = None,
+) -> None:
+    """Submit a release file to the data archive API.
+
+    Parameters
+    ----------
+    instrument : str
+        Instrument name (e.g., ``mag``, ``swe``)
+    release_type : str
+        Type of release:
+        - 'release': IMAP mission-wide public release. By default, all files
+          are released unless specified in the exception list to be withheld.
+        - 'early-release': Early release of selected files approved by both
+          instrument and project.
+        - 'unrelease': Unrelease previously released files due to various
+          causes and reasons.
+    start_date : str
+        Start date in YYYYMMDD format
+    end_date : str
+        End date in YYYYMMDD format
+    release_number : int, optional
+        Release number. Defaults to ``None``. Required if release_type is
+        'release' and should be an integer value.
+    exclude_file : str, optional
+        Path to exclude file containing list of files to exclude from public release.
+    manifest_file : str, optional
+        Path to manifest file containing list of files to apply action to in
+        'early-release' or 'unrelease' types.
+
+    Raises
+    ------
+    ValueError
+        If API key is not configured or if any of the required parameters are invalid
+    IMAPDataAccessError
+        If the API request fails
+    """
+    # Check for API key - required for release operations
+    if not imap_data_access.config["API_KEY"]:
+        raise ValueError(
+            "API key is required for release operations. "
+            "Set the IMAP_API_KEY environment variable or use --api-key argument."
+        )
+
+    # Validate instrument
+    if instrument not in imap_data_access.VALID_INSTRUMENTS:
+        raise ValueError(
+            "Not a valid instrument, please choose from "
+            + ", ".join(imap_data_access.VALID_INSTRUMENTS)
+        )
+
+    # Validate release_type
+    valid_release_types = [e.value for e in ReleaseType]
+    if release_type not in valid_release_types:
+        raise ValueError(
+            f"Not a valid release type, please choose from {valid_release_types}"
+        )
+
+    # Validate release_type == "release" requires release_number
+    if release_type == ReleaseType.RELEASE.value and release_number is None:
+        raise ValueError(
+            "The 'release_number' parameter is required for 'release' release type."
+        )
+
+    # Validate start_date
+    if not file_validation.ImapFilePath.is_valid_date(start_date):
+        raise ValueError("Not a valid start date, use format 'YYYYMMDD'.")
+
+    # Validate end_date
+    if not file_validation.ImapFilePath.is_valid_date(end_date):
+        raise ValueError("Not a valid end date, use format 'YYYYMMDD'.")
+
+    # Handle exclude file upload if provided
+    if exclude_file is not None:
+        # Upload the exclude file using the standard upload function
+        upload(exclude_file)
+        logger.info("Exclude file uploaded successfully")
+
+    # Handle manifest file upload if provided
+    if manifest_file is not None:
+        # Upload the manifest file using the standard upload function
+        upload(manifest_file)
+        logger.info("Manifest file uploaded successfully")
+
+    # Build release parameters
+    release_params = {
+        "instrument": instrument,
+        "release_type": release_type,
+        "start_date": start_date,
+        "end_date": end_date,
+    }
+
+    # Add release_number only if release_type is 'release'
+    if release_type == ReleaseType.RELEASE.value:
+        release_params["release_number"] = release_number
+
+    # Add optional parameters if provided
+    if exclude_file is not None:
+        # API only needs the filename, not the full path
+        release_params["exclude_file"] = os.path.basename(exclude_file)
+
+    if manifest_file is not None:
+        # API only needs the filename, not the full path
+        release_params["manifest_file"] = os.path.basename(manifest_file)
+
+    logger.debug("Input release parameters: %s", release_params)
+
+    url = f"{_get_base_url()}/release"
+    request = requests.Request(method="GET", url=url, params=release_params).prepare()
+
+    logger.info("Submitting release request to %s with params %s", url, release_params)
+    with _make_request(request) as response:
+        result = response.json()
+        logger.debug("Received JSON: %s", result)
+
+    logger.info(
+        f"Release request submitted successfully for {instrument} "
+        f"from {start_date} to {end_date}."
+    )
diff --git a/imap_data_access/utils.py b/imap_data_access/utils.py
@@ -0,0 +1,11 @@
+"""Utility classes and enums for IMAP Data Access."""
+
+from enum import Enum
+
+
+class ReleaseType(Enum):
+    """Enum for release types."""
+
+    RELEASE = "release"
+    EARLY_RELEASE = "early-release"
+    UNRELEASE = "unrelease"
