Merge pull request #2 from melekderman/main

Merge v1.0.0 release

Author: melekderman

.github/workflows/ci.yml

@@ -23,10 +23,10 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install dependencies
+      - name: Install package with dev dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install numpy h5py endf pytest
+          pip install -e ".[dev]"
 
       - name: Run tests
         run: |
@@ -50,3 +50,55 @@ jobs:
 
       - name: Ruff check
         run: ruff check pyepics/
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    needs: [test, lint]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Verify distributions
+        run: |
+          pip install dist/*.whl
+          python -c "import pyepics; print(pyepics.__version__)"
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # Template for PyPI publishing — enable when ready.
+  # Uses trusted publishing (OIDC), no secrets required.
+  # See: https://docs.pypi.org/trusted-publishers/
+  #
+  # publish:
+  #   name: Publish to PyPI
+  #   runs-on: ubuntu-latest
+  #   needs: [build]
+  #   if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+  #   permissions:
+  #     id-token: write
+  #   environment:
+  #     name: pypi
+  #     url: https://pypi.org/p/epics
+  #   steps:
+  #     - uses: actions/download-artifact@v4
+  #       with:
+  #         name: dist
+  #         path: dist/
+  #     - uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/docs.yml

@@ -24,12 +24,31 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install numpy h5py endf sphinx sphinx-rtd-theme myst-parser
+          pip install -e ".[dev]"
 
-      - name: Build docs
+      - name: Build docs (strict — fail on warnings)
         run: |
           cd docs
-          make html
+          make html SPHINXOPTS="-W --keep-going"
+
+      - name: Verify autodoc coverage
+        run: |
+          cd docs
+          python -c "
+          import importlib, inspect, sys
+          sys.path.insert(0, '..')
+          import pyepics
+          public = [name for name in pyepics.__all__ if not name.startswith('_')]
+          missing = []
+          for name in public:
+              obj = getattr(pyepics, name)
+              if callable(obj) and not inspect.getdoc(obj):
+                  missing.append(name)
+          if missing:
+              print(f'Missing docstrings: {missing}')
+              sys.exit(1)
+          print(f'All {len(public)} public symbols have docstrings.')
+          "
 
       - name: Deploy to GitHub Pages
         if: github.ref == 'refs/heads/main' && github.event_name == 'push'

.github/workflows/workflow.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-n-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    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

.gitignore

@@ -3,8 +3,11 @@ __pycache__/
 *.py[codz]
 *$py.class
 
+# Data directory (downloaded ENDF, generated HDF5)
+data/
+
 # Generated reports
-reports/
+tests/reports/
 
 # C extensions
 *.so

CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to PyEPICS are documented in this file.
+
+## [1.0.0] — 2026-02-15
+
+### Added
+
+- **Combined MCDC HDF5 output**: Each element now produces a single HDF5
+  file (e.g. `Fe.h5`) containing `electron_reactions`, `photon_reactions`,
+  and `atomic_relaxation` groups together.
+- `create_combined_mcdc_hdf5()` — new public API for writing combined files.
+- `write_mcdc_combined()` — low-level writer accepting EEDL/EPDL/EADL datasets.
+- Full **EPDL** (photon) support: reader, raw HDF5, MCDC HDF5 — cross sections,
+  form factors, photoelectric subshells, pair production.
+- Full **EADL** (atomic relaxation) support: reader, raw HDF5, MCDC HDF5 —
+  subshell binding energies, radiative/non-radiative transitions,
+  fluorescence and Auger yields.
+- `EPICSClient` — high-level API for querying element properties across
+  all three libraries (EEDL, EPDL, EADL).
+- `ElementProperties` — container with binding energies, cross sections,
+  fluorescence data, and transition energies.
+- CLI tool (`epics`) for download, raw, mcdc, and full pipeline execution.
+- Sphinx documentation with API reference, data-sources guide, and pipeline docs.
+- 164 unit tests covering readers, converters, mapping completeness, and pipeline.
+- PDF regression-test report generator.
+
+### Changed
+
+- **PyPI package name** changed from `pyepics-data` to `epics`.
+  Import name remains `pyepics` (`import pyepics`).
+- Electron-specific constants renamed for clarity:
+  `MF_MT` → `ELECTRON_MF_MT`,
+  `SECTIONS_ABBREVS` → `ELECTRON_SECTIONS_ABBREVS`,
+  `SUBSHELL_LABELS` → `ELECTRON_SUBSHELL_LABELS`.
+  Old names kept as backward-compatible aliases.
+- MCDC CLI now produces one combined file per element in `data/mcdc/`
+  (previously separated into `data/mcdc/electron/`, `photon/`, `atomic/`).
+
+## [0.1.0] — 2026-12-18
+
+### Added
+
+- Initial release with EEDL (electron) reader and HDF5 converter.
+- Basic constant dictionaries and utility functions.
+- PyEEDL backward-compatibility layer (`pyepics.pyeedl_compat`).

INSTALL.md

@@ -0,0 +1,129 @@
+# Installing PyEPICS
+
+## Supported Python Versions
+
+PyEPICS requires **Python 3.11 or later** (3.11, 3.12, 3.13).
+
+## Quick Install from PyPI
+
+```bash
+pip install epics
+```
+
+This installs the core package with the minimum required dependencies
+(`numpy`, `h5py`, `endf`).
+
+## Optional Extras
+
+PyEPICS defines optional dependency groups you can install as needed:
+
+| Extra      | What it adds                        | Install command                          |
+|------------|-------------------------------------|------------------------------------------|
+| `download` | `requests`, `beautifulsoup4`        | `pip install "epics[download]"`   |
+| `pandas`   | `pandas`                            | `pip install "epics[pandas]"`     |
+| `plot`     | `matplotlib`                        | `pip install "epics[plot]"`       |
+| `all`      | All optional dependencies           | `pip install "epics[all]"`        |
+| `dev`      | Testing + linting + docs tooling    | `pip install "epics[dev]"`        |
+
+### Examples
+
+```bash
+# Core only (reading ENDF files and converting to HDF5)
+pip install epics
+
+# With plotting and pandas for interactive exploration
+pip install "epics[plot,pandas]"
+
+# Everything (including download support)
+pip install "epics[all]"
+```
+
+## Developer Install
+
+Clone the repository and install in editable mode with development
+dependencies:
+
+```bash
+git clone https://github.com/melekderman/PyEPICS.git
+cd PyEPICS
+
+# Create a virtual environment (recommended)
+python -m venv .venv
+source .venv/bin/activate   # Linux/macOS
+# .venv\Scripts\activate    # Windows
+
+# Editable install with dev dependencies
+pip install -e ".[dev]"
+```
+
+This gives you:
+
+- `pytest` for running tests
+- `ruff` for linting
+- `sphinx`, `sphinx-rtd-theme`, `myst-parser` for building docs
+- All optional runtime dependencies (`pandas`, `matplotlib`, etc.)
+
+## Running Tests
+
+```bash
+# Run all tests
+python -m pytest tests/ -v
+
+# Run only the client API tests
+python -m pytest tests/test_client.py -v
+
+# Run with coverage (if pytest-cov is installed)
+python -m pytest tests/ --cov=pyepics --cov-report=term-missing
+```
+
+## Building Documentation
+
+```bash
+cd docs
+pip install -r requirements.txt   # if not using [dev] extra
+make html
+```
+
+The built HTML will be in `docs/_build/html/`.
+
+## Building Distributions
+
+To build source and wheel distributions for publishing:
+
+```bash
+pip install build
+python -m build
+```
+
+This produces:
+
+```
+dist/
+├── epics-0.1.0.tar.gz      # sdist
+└── epics-0.1.0-py3-none-any.whl  # wheel
+```
+
+## Verifying the Install
+
+After installation, verify everything works:
+
+```python
+import pyepics
+print(pyepics.__version__)  # "0.1.0"
+
+# Check that the client API is available
+from pyepics import EPICSClient
+print("EPICSClient loaded successfully")
+```
+
+## Platform Notes
+
+- **macOS / Linux / Windows**: All supported via pure-Python code.
+  Binary dependencies (`numpy`, `h5py`) provide pre-built wheels for
+  all major platforms.
+- **Conda**: You can also install dependencies via conda-forge:
+
+  ```bash
+  conda install numpy h5py
+  pip install epics
+  ```