IMAS-5053: replace shot with pulse

Follow IMAS Python HLI and replace `shot` with `pulse`.

Allow `shot` as keyword argument alias of `pulse` in ``DBEntry`

Note: command line sources `command/subcommand/ids.py` and `test_cli_ids.py` are not updated since these files will be removed by https://git.iter.org/projects/IMAS/repos/imaspy/pull-requests/151/overview

Author: maarten-ic

docs/source/courses/basic/al4_snippets/create_core_profiles.py

@@ -33,8 +33,8 @@
     cp.profiles_1d[index].grid.rho_tor_norm = rho_tor_norm
 
 # Create a new data entry for storing the IDS
-shot, run, database = 1, 1, "imaspy-course"
-entry = imas.DBEntry(imas.imasdef.ASCII_BACKEND, database, shot, run)
+pulse, run, database = 1, 1, "imaspy-course"
+entry = imas.DBEntry(imas.imasdef.ASCII_BACKEND, database, pulse, run)
 entry.create()
 
 entry.put(cp)

docs/source/courses/basic/analyze.rst

@@ -243,8 +243,8 @@ Exercise 5
                 import imaspy
                 from imaspy.ids_defs import MDSPLUS_BACKEND
                 
-                database, shot, run, user = "ITER", 134173, 106, "public"
-                data_entry = imaspy.DBEntry(MDSPLUS_BACKEND, database, shot, run, user)
+                database, pulse, run, user = "ITER", 134173, 106, "public"
+                data_entry = imaspy.DBEntry(MDSPLUS_BACKEND, database, pulse, run, user)
                 data_entry.open()
 
     .. md-tab-item:: IMASPy

docs/source/courses/basic/create.rst

@@ -180,7 +180,7 @@ Exercise 5
 
             backend = imaspy.ids_defs.ASCII_BACKEND
             database = "imaspy-course"
-            shot = 1
+            pulse = 1
             run = 1
 
         After a successful ``put`` you should see a file
@@ -190,7 +190,7 @@ Exercise 5
         .. hint::
             :collapsible:
 
-            The signature of :meth:`~imaspy.db_entry.DBEntry()` is: ``DBEntry(backend, database, shot, run)``
+            The signature of :meth:`~imaspy.db_entry.DBEntry()` is: ``DBEntry(backend, database, pulse, run)``
 
     .. md-tab-item:: AL4
 

docs/source/courses/basic/explore.rst

@@ -175,14 +175,14 @@ Exercise 2
           .. code-block:: python
 
             backend = HDF5_BACKEND
-            db_name, shot, run, user = "ITER_MD", 111001, 103, "public"
+            db_name, pulse, run, user = "ITER_MD", 111001, 103, "public"
 
         - ITER machine description database, IDS ``ec_launchers``:
 
           .. code-block:: python
 
             backend = HDF5_BACKEND
-            db_name, shot, run, user = "ITER_MD", 120000, 204, "public"
+            db_name, pulse, run, user = "ITER_MD", 120000, 204, "public"
 
     .. md-tab-item:: Training data
 

docs/source/courses/basic/imaspy_snippets/create_core_profiles.py

@@ -42,8 +42,8 @@
 cp.validate()
 
 # Create a new data entry for storing the IDS
-shot, run, database = 1, 1, "imaspy-course"
-entry = imaspy.DBEntry(imaspy.ids_defs.ASCII_BACKEND, database, shot, run)
+pulse, run, database = 1, 1, "imaspy-course"
+entry = imaspy.DBEntry(imaspy.ids_defs.ASCII_BACKEND, database, pulse, run)
 entry.create()
 
 entry.put(cp)

docs/source/courses/basic/imaspy_snippets/plot_core_profiles_te.py

@@ -13,8 +13,8 @@
 from imaspy.ids_defs import MDSPLUS_BACKEND
 from matplotlib import pyplot as plt
 
-database, shot, run, user = "ITER", 134173, 106, "public"
-data_entry = imaspy.DBEntry(MDSPLUS_BACKEND, database, shot, run, user)
+database, pulse, run, user = "ITER", 134173, 106, "public"
+data_entry = imaspy.DBEntry(MDSPLUS_BACKEND, database, pulse, run, user)
 data_entry.open()
 # Enable lazy loading with `lazy=True`:
 core_profiles = data_entry.get("core_profiles", lazy=True)

docs/source/intro.rst

@@ -99,15 +99,15 @@ IMAS Access Layer. Please check the `IMAS Access Layer documentation
 
 - Which backend to use (e.g. MDSPLUS or HDF5)
 - ``tokamak`` (also known as database)
-- ``shot``
+- ``pulse``
 - ``run``
 
 In IMASPy you do this as follows:
 
 .. code-block:: python
 
     >>> # Create a new IMAS data entry for storing the core_profiles IDS we created earlier
-    >>> # Here we specify the backend, database, shot and run
+    >>> # Here we specify the backend, database, pulse and run
     >>> dbentry = imaspy.DBEntry(imaspy.ids_defs.HDF5_BACKEND, "TEST", 10, 2)
     >>> dbentry.create()
     >>> # now store the core_profiles IDS we just populated

imaspy/db_entry.py

@@ -77,15 +77,30 @@ def __legacy_init(
         self,
         backend_id: int,
         db_name: str,
-        shot: int,
-        run: int,
+        pulse: Optional[int] = None,
+        run: Optional[int] = None,
         user_name: Optional[str] = None,
         data_version: Optional[str] = None,
+        *,
+        shot: Optional[int] = None,
     ):
+        # Backwards compatibility: support shot as alias for pulse
+        if pulse is None:
+            if shot is None:
+                raise ValueError("No value provided for `pulse`")
+            pulse = shot
+        elif shot is not None:
+            raise ValueError(
+                "Cannot provide a value for `shot` and `pulse`. "
+                "`shot` is an alias for pulse, please use `pulse` instead."
+            )
+        if run is None:
+            raise ValueError("No value provided for `run`")
+
         self._legacy_init = True
         self.backend_id = backend_id
         self.db_name = db_name
-        self.shot = shot
+        self.pulse = pulse
         self.run = run
         self.user_name = user_name or os.environ["USER"]
         self.data_version = data_version or os.environ.get("IMAS_VERSION", "")
@@ -145,8 +160,8 @@ def __init__(
             ``db_name``
                 Database name, e.g. "ITER".
 
-            ``shot``
-                Shot number of the database entry
+            ``pulse``
+                Pulse number of the database entry
 
             ``run``
                 Run number of the database entry
@@ -197,7 +212,7 @@ def _build_legacy_uri(self, options):
             )
         status, uri = ll_interface.build_uri_from_legacy_parameters(
             self.backend_id,
-            self.shot,
+            self.pulse,
             self.run,
             self.user_name,
             self.db_name,
@@ -240,7 +255,7 @@ def _open_pulse(self, mode: int, options: Any) -> None:
                     self._setup_mdsplus()
                 status, ctx = ll_interface.begin_pulse_action(
                     self.backend_id,
-                    self.shot,
+                    self.pulse,
                     self.run,
                     self.user_name,
                     self.db_name,

imaspy/test/test_helpers.py

@@ -308,14 +308,14 @@ def open_dbentry(
 ) -> DBEntry:
     """Open a DBEntry, with a tmpdir in place of the user argument"""
     if worker_id == "master":
-        shot = 1
+        pulse = 1
     else:
-        shot = int(worker_id[2:]) + 1
+        pulse = int(worker_id[2:]) + 1
 
     dbentry = DBEntry(
         backend,
         "test",
-        shot,
+        pulse,
         0,
         str(tmp_path),
         dd_version=dd_version,

imaspy/test/test_time_slicing.py

@@ -92,15 +92,15 @@ def test_hli_time_slicing_put(backend, worker_id, tmp_path, time_mode):
     ids = imas.equilibrium()
 
     if worker_id == "master":
-        shot = 1
+        pulse = 1
     else:
-        shot = int(worker_id[2:]) + 1
+        pulse = int(worker_id[2:]) + 1
 
     # ensure presence of mdsplus model dir
     if backend == MDSPLUS_BACKEND:
         os.environ["ids_path"] = mdsplus_model_dir(version=os.environ["IMAS_VERSION"])
         ensure_data_dir(str(tmp_path), "test", "3", 9999)
-    db_entry = imas.DBEntry(backend, "test", shot, 9999, user_name=str(tmp_path))
+    db_entry = imas.DBEntry(backend, "test", pulse, 9999, user_name=str(tmp_path))
     status, ctx = db_entry.create()
     if status != 0:
         logger.error("Error opening db entry %s", status)