add client features

Author: melekderman

.github/workflows/workflow.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-n-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+
+    - name: Install build dependencies
+      run: python -m pip install build
+
+    - name: Build binary wheel and source tarball
+      run: python -m build
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

README.md

@@ -299,7 +299,7 @@ python -m pytest tests/ -v
 A `pyeedl_compat` shim re-exports legacy API symbols for backward compatibility:
 
 ```python
-from pyepics.pyeedl_compat import PERIODIC_TABLE, float_endf, SUBSHELL_LABELS
+from pyepics.pyeedl_compat import PERIODIC_TABLE, float_endf, ELECTRON_SUBSHELL_LABELS
 ```
 
 ## Data Sources

docs/data_sources.rst

@@ -89,7 +89,7 @@ keeps three mapping dictionaries in ``pyepics/utils/constants.py``:
    * - Dictionary
      - Library
      - Purpose
-   * - ``MF_MT`` / ``SECTIONS_ABBREVS``
+   * - ``ELECTRON_MF_MT`` / ``ELECTRON_SECTIONS_ABBREVS``
      - EEDL
      - Electron cross-section & distribution sections
    * - ``PHOTON_MF_MT`` / ``PHOTON_SECTIONS_ABBREVS``

pyepics/__init__.py

@@ -51,23 +51,23 @@
 __version__ = "0.1.0"
 __author__ = "Melek Derman"
 
-from pyepics.readers.eedl import EEDLReader
-from pyepics.readers.eadl import EADLReader
-from pyepics.readers.epdl import EPDLReader
+from pyepics.client import ElementProperties, EPICSClient
 from pyepics.converters.hdf5 import (
     convert_dataset_to_hdf5,
-    create_raw_hdf5,
     create_mcdc_hdf5,
+    create_raw_hdf5,
 )
-from pyepics.client import EPICSClient, ElementProperties
 from pyepics.exceptions import (
-    PyEPICSError,
-    ParseError,
-    ValidationError,
-    FileFormatError,
     ConversionError,
     DownloadError,
+    FileFormatError,
+    ParseError,
+    PyEPICSError,
+    ValidationError,
 )
+from pyepics.readers.eadl import EADLReader
+from pyepics.readers.eedl import EEDLReader
+from pyepics.readers.epdl import EPDLReader
 
 __all__ = [
     # Version

pyepics/client.py

@@ -25,9 +25,9 @@
 from __future__ import annotations
 
 import logging
-import os
+from collections.abc import Sequence
 from pathlib import Path
-from typing import Any, Sequence, Union
+from typing import Any
 
 import numpy as np
 
@@ -45,7 +45,7 @@
 logger = logging.getLogger(__name__)
 
 # Type alias for element identifiers
-ElementID = Union[int, str]
+ElementID = int | str
 
 # ---------------------------------------------------------------------------
 # Internal helpers
@@ -161,6 +161,7 @@ def __init__(
         photon: EPDLDataset | None = None,
         atomic: EADLDataset | None = None,
     ) -> None:
+        """Initialise an ElementProperties container."""
         self.Z = z
         self.symbol = symbol
         self.name = name
@@ -244,6 +245,7 @@ def to_dict(self) -> dict[str, Any]:
         return d
 
     def __repr__(self) -> str:
+        """Return a developer-friendly string representation."""
         libs = []
         if self.electron:
             libs.append("EEDL")
@@ -257,9 +259,11 @@ def __repr__(self) -> str:
         )
 
     def __getitem__(self, key: str) -> Any:
+        """Allow dict-style access to :meth:`to_dict` keys."""
         return self.to_dict()[key]
 
     def __contains__(self, key: str) -> bool:
+        """Support ``key in props`` membership tests."""
         return key in self.to_dict()
 
 
@@ -288,6 +292,7 @@ class EPICSClient:
     """
 
     def __init__(self, data_dir: str | Path = "data/endf") -> None:
+        """Initialise the client with the path to ENDF data."""
         self._data_dir = Path(data_dir)
         self._eedl_reader = EEDLReader()
         self._epdl_reader = EPDLReader()

pyepics/converters/__init__.py

@@ -22,8 +22,8 @@
 
 from pyepics.converters.hdf5 import (
     convert_dataset_to_hdf5,
-    create_raw_hdf5,
     create_mcdc_hdf5,
+    create_raw_hdf5,
 )
 
 __all__ = ["convert_dataset_to_hdf5", "create_raw_hdf5", "create_mcdc_hdf5"]

pyepics/converters/hdf5.py

@@ -88,7 +88,7 @@
     EPDLDataset,
 )
 from pyepics.readers.base import DatasetModel
-from pyepics.utils.constants import SUBSHELL_LABELS
+from pyepics.utils.constants import ELECTRON_SUBSHELL_LABELS
 from pyepics.utils.parsing import (
     build_pdf,
     linear_interpolation,
@@ -255,7 +255,7 @@ def interp(key: str) -> np.ndarray:
     _create_xs_dataset(ion_grp, "xs", xs_ion_total, "barns")
     subs_grp = ion_grp.create_group("subshells")
 
-    for mt, shell_label in SUBSHELL_LABELS.items():
+    for _mt, shell_label in ELECTRON_SUBSHELL_LABELS.items():
         xs_key = f"xs_{shell_label}"
         spec_key = f"spec_{shell_label}"
 
@@ -337,7 +337,7 @@ def interp(key: str) -> np.ndarray:
     pe_grp = root.create_group("photoelectric")
     _create_xs_dataset(pe_grp, "xs", interp("xs_photoelectric"), "barns")
     pe_subs = pe_grp.create_group("subshells")
-    for mt, shell_label in SUBSHELL_LABELS.items():
+    for _mt, shell_label in ELECTRON_SUBSHELL_LABELS.items():
         key = f"xs_pe_{shell_label}"
         if key not in xs:
             continue
@@ -537,8 +537,8 @@ def convert_dataset_to_hdf5(
         )
 
     # Select reader
-    from pyepics.readers.eedl import EEDLReader
     from pyepics.readers.eadl import EADLReader
+    from pyepics.readers.eedl import EEDLReader
     from pyepics.readers.epdl import EPDLReader
 
     reader_map = {
@@ -581,8 +581,8 @@ def convert_dataset_to_hdf5(
 
 def _get_reader(dataset_type: str):
     """Return the correct reader class for a dataset type."""
-    from pyepics.readers.eedl import EEDLReader
     from pyepics.readers.eadl import EADLReader
+    from pyepics.readers.eedl import EEDLReader
     from pyepics.readers.epdl import EPDLReader
     return {"EEDL": EEDLReader, "EADL": EADLReader, "EPDL": EPDLReader}[dataset_type]
 
@@ -619,9 +619,9 @@ def create_raw_hdf5(
     >>> create_raw_hdf5("EEDL", "data/endf/eedl/EEDL.ZA026000.endf", "data/raw/electron/Fe.h5")
     """
     from pyepics.converters.raw_hdf5 import (
+        write_raw_eadl,
         write_raw_eedl,
         write_raw_epdl,
-        write_raw_eadl,
     )
 
     writers = {"EEDL": write_raw_eedl, "EPDL": write_raw_epdl, "EADL": write_raw_eadl}
@@ -681,9 +681,9 @@ def create_mcdc_hdf5(
     >>> create_mcdc_hdf5("EEDL", "data/endf/eedl/EEDL.ZA026000.endf", "data/mcdc/electron/Fe.h5")
     """
     from pyepics.converters.mcdc_hdf5 import (
+        write_mcdc_eadl,
         write_mcdc_eedl,
         write_mcdc_epdl,
-        write_mcdc_eadl,
     )
 
     writers = {"EEDL": write_mcdc_eedl, "EPDL": write_mcdc_epdl, "EADL": write_mcdc_eadl}

pyepics/converters/mcdc_hdf5.py

@@ -56,7 +56,7 @@
     EEDLDataset,
     EPDLDataset,
 )
-from pyepics.utils.constants import SUBSHELL_LABELS
+from pyepics.utils.constants import ELECTRON_SUBSHELL_LABELS
 from pyepics.utils.parsing import (
     build_pdf,
     linear_interpolation,
@@ -199,7 +199,7 @@ def interp(key: str) -> np.ndarray:
     _create_xs_dataset(ion_grp, "xs", xs_ion_total, "barns")
     subs_grp = ion_grp.create_group("subshells")
 
-    for mt, shell_label in SUBSHELL_LABELS.items():
+    for _mt, shell_label in ELECTRON_SUBSHELL_LABELS.items():
         xs_key = f"xs_{shell_label}"
         spec_key = f"spec_{shell_label}"
         if xs_key not in xs:
@@ -292,7 +292,7 @@ def interp(key: str) -> np.ndarray:
     pe_grp = root.create_group("photoelectric")
     _create_xs_dataset(pe_grp, "xs", interp("xs_photoelectric"), "barns")
     pe_subs = pe_grp.create_group("subshells")
-    for mt, shell_label in SUBSHELL_LABELS.items():
+    for _mt, shell_label in ELECTRON_SUBSHELL_LABELS.items():
         key = f"xs_pe_{shell_label}"
         if key not in xs:
             continue

pyepics/converters/raw_hdf5.py

@@ -79,7 +79,7 @@
     EPDLDataset,
     FormFactorRecord,
 )
-from pyepics.utils.constants import SUBSHELL_LABELS
+from pyepics.utils.constants import ELECTRON_SUBSHELL_LABELS
 
 logger = logging.getLogger(__name__)
 
@@ -187,7 +187,7 @@ def write_raw_eedl(h5f: h5py.File, dataset: EEDLDataset) -> None:
     if "xs_ion" in xs:
         _write_xs_record(ig.create_group("cross_section/total"), xs["xs_ion"])
 
-    for mt, shell_label in SUBSHELL_LABELS.items():
+    for _mt, shell_label in ELECTRON_SUBSHELL_LABELS.items():
         xs_key = f"xs_{shell_label}"
         spec_key = f"spec_{shell_label}"
         if xs_key not in xs:
@@ -243,7 +243,7 @@ def write_raw_epdl(h5f: h5py.File, dataset: EPDLDataset) -> None:
     pg = h5f.create_group("photoelectric")
     if "xs_photoelectric" in xs:
         _write_xs_record(pg.create_group("cross_section/total"), xs["xs_photoelectric"])
-    for mt, shell_label in SUBSHELL_LABELS.items():
+    for _mt, shell_label in ELECTRON_SUBSHELL_LABELS.items():
         key = f"xs_pe_{shell_label}"
         if key in xs:
             _write_xs_record(pg.create_group(f"cross_section/{shell_label}"), xs[key])

pyepics/models/__init__.py

@@ -18,12 +18,12 @@
 from pyepics.models.records import (
     CrossSectionRecord,
     DistributionRecord,
-    FormFactorRecord,
-    SubshellTransition,
-    SubshellRelaxation,
+    EADLDataset,
     EEDLDataset,
     EPDLDataset,
-    EADLDataset,
+    FormFactorRecord,
+    SubshellRelaxation,
+    SubshellTransition,
 )
 
 __all__ = [