Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/source/changelog.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,27 @@
Changelog
=========

Unreleased
----------

Features
''''''''

- :issue:`144`: ``imas convert --ids`` takes a comma-separated list of ``IDS``,
``IDS:OCCURRENCE`` and ``IDS:*`` (all occurrences), for example
``--ids summary,plasma_profiles:1,plasma_profiles:2``. As in the IDS path syntax,
an IDS without an occurrence means occurrence 0, so ``--ids core_profiles`` no
longer converts all occurrences: use ``--ids core_profiles:*`` for that. Unknown
IDS names, malformed occurrences and IDSs or occurrences that are not in the input
Data Entry are reported before the output Data Entry is created.

Deprecations
''''''''''''

- [deprecation] :issue:`144`: the ``--occurrence`` option of ``imas convert``;
use ``--ids IDS:OCCURRENCE`` instead. To be removed in the next major release.


What's new in IMAS-Python 2.3.1
-------------------------------

Expand Down
8 changes: 5 additions & 3 deletions docs/source/cli.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,11 @@ IMAS-Python Command Line tool
IMAS-Python comes with a command line tool: ``imas``. This allows you to execute
some tasks without writing Python code:

- ``imas convert`` can convert Data Entries (or, optionally, single IDSs from
a Data Entry) to a different DD version. This command can also be used to
convert IDSs between different backends.
- ``imas convert`` can convert Data Entries (or, optionally, selected IDSs and
occurrences from a Data Entry, for example
``--ids summary,plasma_profiles:1,plasma_profiles:2``) to a different DD
version. This command can also be used to convert IDSs between different
backends.
- ``imas print`` can print the contents of an IDS to the terminal.
- ``imas version`` shows version information of IMAS-Python.
- ``imas analyze-db`` and ``imas process-db-analysis`` analyze the contents
Expand Down
112 changes: 100 additions & 12 deletions imas/command/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
# You should have received the IMAS-Python LICENSE file with this project.
"""Main CLI entry point"""

from __future__ import annotations

import logging
import sys
from contextlib import ExitStack
Expand Down Expand Up @@ -132,17 +134,70 @@ def _check_convert_to_plasma_ids(idss_with_occurrences):
)


ALL_OCCURRENCES = "*"


def _parse_ids_option(
ids: str, known_ids: list[str], dd_version: str
) -> list[tuple[str, int | str | None]]:
"""Split the comma-separated --ids option into (IDS name, occurrence) pairs.

Each entry is an IDS name, optionally followed by ``:OCCURRENCE`` or ``:*`` (all
occurrences). The occurrence is None when it is not given. Names are checked
against the target DD.
"""
entries = []
for item in ids.split(","):
item = item.strip()
if not item:
continue
name, sep, occ = item.partition(":")
name = name.strip()
occurrence = None
if sep:
occ = occ.strip()
if occ == ALL_OCCURRENCES:
occurrence = ALL_OCCURRENCES
elif occ.isdecimal():
occurrence = int(occ)
else:
raise click.BadParameter(
f"invalid occurrence in {item!r}: expected IDS, IDS:OCCURRENCE "
"with a non-negative integer occurrence, or IDS:*",
param_hint="'--ids'",
)
entries.append((name, occurrence))
entries = list(dict.fromkeys(entries))
if not entries:
raise click.BadParameter("no IDS name given", param_hint="'--ids'")
unknown = list(dict.fromkeys(name for name, _ in entries if name not in known_ids))
if unknown:
raise click.BadParameter(
f"unknown IDS name(s) for DD version {dd_version}: {', '.join(unknown)}",
param_hint="'--ids'",
)
return entries


@cli.command("convert", no_args_is_help=True)
@click.argument("uri_in")
@click.argument("dd_version")
@click.argument("uri_out")
@click.option(
"--ids",
default="*",
help="Specify which IDS to convert. \
If not provided, all IDSs in the data entry are converted.",
help="Specify which IDSs to convert, as a comma-separated list of IDS, "
"IDS:OCCURRENCE or IDS:* (all occurrences), for example "
"summary,plasma_profiles:1,plasma_profiles:2. An IDS without an occurrence "
"means occurrence 0. "
"If not provided, all IDSs in the data entry are converted.",
)
@click.option(
"--occurrence",
default=-1,
help="Deprecated: use --ids IDS:OCCURRENCE instead. "
"Occurrence to convert for IDSs given without one.",
)
@click.option("--occurrence", default=-1, help="Specify which occurrence to convert.")
@click.option("--quiet", "-q", is_flag=True, help="Suppress progress output.")
@click.option("--timeit", is_flag=True, help="Show timing information.")
@click.option(
Expand All @@ -166,7 +221,7 @@ def convert_ids(
no_provenance: bool,
convert_to_plasma_ids: bool,
):
"""Convert a Data Entry (or a single IDS) to the target DD version.
"""Convert a Data Entry (or selected IDSs/occurrences) to the target DD version.

Provide a different backend to URI_OUT than URI_IN to convert between backends.
For example:
Expand All @@ -190,25 +245,58 @@ def convert_ids(
else:
raise UnknownDDVersion(dd_version, dd_zip.dd_xml_versions())

# Check the requested IDS names before the output Data Entry is created
target_factory = imas.IDSFactory(
version_params.get("dd_version"), version_params.get("xml_path")
)
if ids == "*":
ids_list = [(name, ALL_OCCURRENCES) for name in target_factory.ids_names()]
if occurrence != -1:
ids_list = [(name, occurrence) for name, _ in ids_list]
else:
ids_list = _parse_ids_option(ids, target_factory.ids_names(), dd_version)
if occurrence != -1:
logger.warning(
"--occurrence is deprecated and will be removed in the next major "
"release; use --ids IDS:OCCURRENCE instead (for example --ids summary:1)."
)
Comment thread
olivhoenen marked this conversation as resolved.
Resolved

provenance_origin_uri = ""
if not no_provenance:
provenance_origin_uri = uri_in

# Use an ExitStack to avoid three nested with-statements
with ExitStack() as stack:
entry_in = stack.enter_context(DBEntry(uri_in, "r"))
entry_out = stack.enter_context(DBEntry(uri_out, "x", **version_params))

# First build IDS/occurrence list so we can show a decent progress bar
ids_list = [ids] if ids != "*" else entry_out.factory.ids_names()
idss_with_occurrences = []
for ids_name in ids_list:
if occurrence == -1:
idss_with_occurrences.extend(
(ids_name, occ) for occ in entry_in.list_all_occurrences(ids_name)
)
missing = []
for ids_name, ids_occurrence in ids_list:
if ids_occurrence is None: # IDS given without an occurrence
ids_occurrence = occurrence if occurrence != -1 else 0
if ids == "*" and ids_occurrence != ALL_OCCURRENCES:
# Deprecated --occurrence without --ids: keep its old behaviour
idss_with_occurrences.append((ids_name, ids_occurrence))
Comment thread
olivhoenen marked this conversation as resolved.
Resolved
continue
available = entry_in.list_all_occurrences(ids_name)
if ids_occurrence == ALL_OCCURRENCES:
idss_with_occurrences.extend((ids_name, occ) for occ in available)
if not available and ids != "*":
missing.append(f"{ids_name}:*")
elif ids_occurrence in available:
idss_with_occurrences.append((ids_name, ids_occurrence))
else:
idss_with_occurrences.append((ids_name, occurrence))
missing.append(f"{ids_name}:{ids_occurrence}")
if missing:
# Reported before the output Data Entry is created
raise click.BadParameter(
f"not found in the input Data Entry: {', '.join(missing)}",
param_hint="'--ids'",
)
idss_with_occurrences = list(dict.fromkeys(idss_with_occurrences))

entry_out = stack.enter_context(DBEntry(uri_out, "x", **version_params))

if convert_to_plasma_ids: # Sanity checks for conversion to plasma IDSs
_check_convert_to_plasma_ids(idss_with_occurrences)
Expand Down
Loading
Loading