llnl-ssapy-data 0.1.0__tar.gz

llnl_ssapy_data-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018, Lawrence Livermore National Security, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llnl_ssapy_data-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE
+include NOTICE
+include README.rst
+include src/ssapy_data/manifest.json
+graft src/ssapy_data/data
+prune **/__pycache__
+global-exclude *.py[cod]

llnl_ssapy_data-0.1.0/NOTICE

@@ -0,0 +1,7 @@
+This work was produced under the auspices of the U.S. Department of Energy by Lawrence Livermore National Laboratory under Contract DE-AC52-07NA27344.
+
+This work was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor Lawrence Livermore National Security, LLC, nor any of their employees makes any warranty, expressed or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately owned rights.
+
+Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or Lawrence Livermore National Security, LLC.
+
+The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or Lawrence Livermore National Security, LLC, and shall not be used for advertising or product endorsement purposes.

llnl_ssapy_data-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: llnl-ssapy-data
+Version: 0.1.0
+Summary: Packaged data resources for SSAPy and SSAPy Toolkit
+Author-email: LLNL SSAPy Software Team <yeagerastro@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/llnl/SSAPy-Data
+Project-URL: Repository, https://github.com/llnl/SSAPy-Data
+Project-URL: Issues, https://github.com/llnl/SSAPy-Data/issues
+Keywords: ssapy,astrodynamics,orbital-mechanics,data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+SSAPy-Data
+==========
+
+SSAPy-Data stores reusable data resources for `SSAPy <https://github.com/llnl/SSAPy>`_
+and `SSAPy Toolkit <https://github.com/llnl/SSAPy-Toolkit>`_. The repository is
+packaged as the ``llnl-ssapy-data`` Python distribution and exposes the
+``ssapy_data`` import package. Data files live under ``src/ssapy_data/data`` so
+users can receive required data through normal ``pip`` installation without Git
+LFS, git submodules, or runtime GitHub downloads.
+
+The initial package intentionally does not duplicate data already packaged by
+base SSAPy. New SSAPy Toolkit datasets should be added here when they are needed
+by toolkit functions and are not already available from the base ``llnl-ssapy``
+wheel.
+
+Installation
+------------
+
+Install from a local clone in editable mode:
+
+.. code-block:: bash
+
+   pip install -e .
+
+Build the wheel and source distribution:
+
+.. code-block:: bash
+
+   python -m build
+   ls -lh dist/
+
+Using packaged data
+-------------------
+
+Access packaged data with ``importlib.resources`` helpers exposed by
+``ssapy_data``:
+
+.. code-block:: python
+
+   from ssapy_data import data_path, read_text
+
+   gravity_header = read_text("egm84.egm")
+
+   with data_path("Earth_graphics/ne_50m_ocean.shp") as path:
+       print(path)
+
+``data_path`` yields a real filesystem path for libraries that require paths.
+Use the path only inside the context manager because zipped wheels may extract
+resources to temporary locations.
+
+Adding data
+-----------
+
+Add new reusable data below ``src/ssapy_data/data``. Preserve source filenames
+when possible, and use subdirectories when a dataset has multiple sidecar files.
+Do not add files already packaged by base SSAPy unless a later migration
+explicitly moves that dependency here.
+After adding, replacing, or removing data, regenerate the manifest:
+
+.. code-block:: bash
+
+   python scripts/update_manifest.py
+   python -m pytest
+   python -m build
+
+The manifest records each packaged file path, byte count, and SHA-256 digest in
+``src/ssapy_data/manifest.json``. Pull requests that change data should also
+update the source/provenance notes in this README when the dataset source or
+license differs from the existing entries.
+
+Size guidance
+-------------
+
+The initial wheel contains only the package helpers and a data-directory README.
+Before adding large datasets, estimate the built wheel size with:
+
+.. code-block:: bash
+
+   python -m build --wheel
+   ls -lh dist/*.whl
+
+If a future dataset pushes the wheel above PyPI limits, split the data into a
+separate companion package rather than using Git LFS in SSAPy Toolkit.
+
+Publishing
+----------
+
+The repository publishes ``llnl-ssapy-data`` to PyPI through GitHub Actions and
+PyPI trusted publishing. Configure PyPI before creating the first release:
+
+* Create a PyPI trusted publisher, or pending publisher, for project
+  ``llnl-ssapy-data``.
+* Set the owner to ``llnl`` and repository to ``SSAPy-Data``.
+* Set the workflow filename to ``publish.yml``.
+* Set the GitHub environment to ``pypi``.
+
+After PyPI trust is configured, publish by creating a GitHub release whose tag
+matches the version in ``pyproject.toml``, for example ``v0.1.0``. The
+``Publish to PyPI`` workflow builds a clean wheel and source distribution, runs
+tests, checks the manifest, and uploads through OpenID Connect (OIDC). No PyPI
+API token is required.
+
+Data provenance
+---------------
+
+Each data pull request should document the source URL, license, retrieval date,
+and any preprocessing steps for new packaged datasets. Candidate sources include:
+
+* Earth gravity fields:
+  `ICGEM time-variable gravity fields <http://icgem.gfz-potsdam.de/tom_longtime>`_
+* Other celestial bodies:
+  `ICGEM celestial gravity fields <http://icgem.gfz-potsdam.de/tom_celestial>`_
+
+Code of Conduct
+---------------
+
+Please note that SSAPy-Data has a
+`Code of Conduct <https://github.com/LLNL/SSAPy-Data/blob/main/CODE_OF_CONDUCT.md>`_.
+By participating in the SSAPy-Data community, you agree to abide by its rules.
+
+License
+-------
+
+SSAPy-Data is distributed under the terms of the MIT license. All new
+contributions must be made under the MIT license.
+
+See the `license <https://github.com/LLNL/SSAPy-Data/blob/main/LICENSE>`_ and
+`NOTICE <https://github.com/LLNL/SSAPy-Data/blob/main/NOTICE>`_ for details.
+
+SPDX-License-Identifier: MIT
+
+LLNL-CODE-862420

llnl_ssapy_data-0.1.0/README.rst

@@ -0,0 +1,132 @@
+SSAPy-Data
+==========
+
+SSAPy-Data stores reusable data resources for `SSAPy <https://github.com/llnl/SSAPy>`_
+and `SSAPy Toolkit <https://github.com/llnl/SSAPy-Toolkit>`_. The repository is
+packaged as the ``llnl-ssapy-data`` Python distribution and exposes the
+``ssapy_data`` import package. Data files live under ``src/ssapy_data/data`` so
+users can receive required data through normal ``pip`` installation without Git
+LFS, git submodules, or runtime GitHub downloads.
+
+The initial package intentionally does not duplicate data already packaged by
+base SSAPy. New SSAPy Toolkit datasets should be added here when they are needed
+by toolkit functions and are not already available from the base ``llnl-ssapy``
+wheel.
+
+Installation
+------------
+
+Install from a local clone in editable mode:
+
+.. code-block:: bash
+
+   pip install -e .
+
+Build the wheel and source distribution:
+
+.. code-block:: bash
+
+   python -m build
+   ls -lh dist/
+
+Using packaged data
+-------------------
+
+Access packaged data with ``importlib.resources`` helpers exposed by
+``ssapy_data``:
+
+.. code-block:: python
+
+   from ssapy_data import data_path, read_text
+
+   gravity_header = read_text("egm84.egm")
+
+   with data_path("Earth_graphics/ne_50m_ocean.shp") as path:
+       print(path)
+
+``data_path`` yields a real filesystem path for libraries that require paths.
+Use the path only inside the context manager because zipped wheels may extract
+resources to temporary locations.
+
+Adding data
+-----------
+
+Add new reusable data below ``src/ssapy_data/data``. Preserve source filenames
+when possible, and use subdirectories when a dataset has multiple sidecar files.
+Do not add files already packaged by base SSAPy unless a later migration
+explicitly moves that dependency here.
+After adding, replacing, or removing data, regenerate the manifest:
+
+.. code-block:: bash
+
+   python scripts/update_manifest.py
+   python -m pytest
+   python -m build
+
+The manifest records each packaged file path, byte count, and SHA-256 digest in
+``src/ssapy_data/manifest.json``. Pull requests that change data should also
+update the source/provenance notes in this README when the dataset source or
+license differs from the existing entries.
+
+Size guidance
+-------------
+
+The initial wheel contains only the package helpers and a data-directory README.
+Before adding large datasets, estimate the built wheel size with:
+
+.. code-block:: bash
+
+   python -m build --wheel
+   ls -lh dist/*.whl
+
+If a future dataset pushes the wheel above PyPI limits, split the data into a
+separate companion package rather than using Git LFS in SSAPy Toolkit.
+
+Publishing
+----------
+
+The repository publishes ``llnl-ssapy-data`` to PyPI through GitHub Actions and
+PyPI trusted publishing. Configure PyPI before creating the first release:
+
+* Create a PyPI trusted publisher, or pending publisher, for project
+  ``llnl-ssapy-data``.
+* Set the owner to ``llnl`` and repository to ``SSAPy-Data``.
+* Set the workflow filename to ``publish.yml``.
+* Set the GitHub environment to ``pypi``.
+
+After PyPI trust is configured, publish by creating a GitHub release whose tag
+matches the version in ``pyproject.toml``, for example ``v0.1.0``. The
+``Publish to PyPI`` workflow builds a clean wheel and source distribution, runs
+tests, checks the manifest, and uploads through OpenID Connect (OIDC). No PyPI
+API token is required.
+
+Data provenance
+---------------
+
+Each data pull request should document the source URL, license, retrieval date,
+and any preprocessing steps for new packaged datasets. Candidate sources include:
+
+* Earth gravity fields:
+  `ICGEM time-variable gravity fields <http://icgem.gfz-potsdam.de/tom_longtime>`_
+* Other celestial bodies:
+  `ICGEM celestial gravity fields <http://icgem.gfz-potsdam.de/tom_celestial>`_
+
+Code of Conduct
+---------------
+
+Please note that SSAPy-Data has a
+`Code of Conduct <https://github.com/LLNL/SSAPy-Data/blob/main/CODE_OF_CONDUCT.md>`_.
+By participating in the SSAPy-Data community, you agree to abide by its rules.
+
+License
+-------
+
+SSAPy-Data is distributed under the terms of the MIT license. All new
+contributions must be made under the MIT license.
+
+See the `license <https://github.com/LLNL/SSAPy-Data/blob/main/LICENSE>`_ and
+`NOTICE <https://github.com/LLNL/SSAPy-Data/blob/main/NOTICE>`_ for details.
+
+SPDX-License-Identifier: MIT
+
+LLNL-CODE-862420

llnl_ssapy_data-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "llnl-ssapy-data"
+version = "0.1.0"
+description = "Packaged data resources for SSAPy and SSAPy Toolkit"
+readme = "README.rst"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE", "NOTICE"]
+authors = [
+  { name = "LLNL SSAPy Software Team", email = "yeagerastro@gmail.com" },
+]
+keywords = ["ssapy", "astrodynamics", "orbital-mechanics", "data"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Astronomy",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+  "build",
+  "pytest",
+  "twine",
+]
+
+[project.urls]
+Homepage = "https://github.com/llnl/SSAPy-Data"
+Repository = "https://github.com/llnl/SSAPy-Data"
+Issues = "https://github.com/llnl/SSAPy-Data/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+packages = { find = { where = ["src"] } }
+include-package-data = true
+
+[tool.setuptools.package-data]
+ssapy_data = ["manifest.json", "data/*", "data/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

llnl_ssapy_data-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

llnl_ssapy_data-0.1.0/src/llnl_ssapy_data.egg-info/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: llnl-ssapy-data
+Version: 0.1.0
+Summary: Packaged data resources for SSAPy and SSAPy Toolkit
+Author-email: LLNL SSAPy Software Team <yeagerastro@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/llnl/SSAPy-Data
+Project-URL: Repository, https://github.com/llnl/SSAPy-Data
+Project-URL: Issues, https://github.com/llnl/SSAPy-Data/issues
+Keywords: ssapy,astrodynamics,orbital-mechanics,data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+SSAPy-Data
+==========
+
+SSAPy-Data stores reusable data resources for `SSAPy <https://github.com/llnl/SSAPy>`_
+and `SSAPy Toolkit <https://github.com/llnl/SSAPy-Toolkit>`_. The repository is
+packaged as the ``llnl-ssapy-data`` Python distribution and exposes the
+``ssapy_data`` import package. Data files live under ``src/ssapy_data/data`` so
+users can receive required data through normal ``pip`` installation without Git
+LFS, git submodules, or runtime GitHub downloads.
+
+The initial package intentionally does not duplicate data already packaged by
+base SSAPy. New SSAPy Toolkit datasets should be added here when they are needed
+by toolkit functions and are not already available from the base ``llnl-ssapy``
+wheel.
+
+Installation
+------------
+
+Install from a local clone in editable mode:
+
+.. code-block:: bash
+
+   pip install -e .
+
+Build the wheel and source distribution:
+
+.. code-block:: bash
+
+   python -m build
+   ls -lh dist/
+
+Using packaged data
+-------------------
+
+Access packaged data with ``importlib.resources`` helpers exposed by
+``ssapy_data``:
+
+.. code-block:: python
+
+   from ssapy_data import data_path, read_text
+
+   gravity_header = read_text("egm84.egm")
+
+   with data_path("Earth_graphics/ne_50m_ocean.shp") as path:
+       print(path)
+
+``data_path`` yields a real filesystem path for libraries that require paths.
+Use the path only inside the context manager because zipped wheels may extract
+resources to temporary locations.
+
+Adding data
+-----------
+
+Add new reusable data below ``src/ssapy_data/data``. Preserve source filenames
+when possible, and use subdirectories when a dataset has multiple sidecar files.
+Do not add files already packaged by base SSAPy unless a later migration
+explicitly moves that dependency here.
+After adding, replacing, or removing data, regenerate the manifest:
+
+.. code-block:: bash
+
+   python scripts/update_manifest.py
+   python -m pytest
+   python -m build
+
+The manifest records each packaged file path, byte count, and SHA-256 digest in
+``src/ssapy_data/manifest.json``. Pull requests that change data should also
+update the source/provenance notes in this README when the dataset source or
+license differs from the existing entries.
+
+Size guidance
+-------------
+
+The initial wheel contains only the package helpers and a data-directory README.
+Before adding large datasets, estimate the built wheel size with:
+
+.. code-block:: bash
+
+   python -m build --wheel
+   ls -lh dist/*.whl
+
+If a future dataset pushes the wheel above PyPI limits, split the data into a
+separate companion package rather than using Git LFS in SSAPy Toolkit.
+
+Publishing
+----------
+
+The repository publishes ``llnl-ssapy-data`` to PyPI through GitHub Actions and
+PyPI trusted publishing. Configure PyPI before creating the first release:
+
+* Create a PyPI trusted publisher, or pending publisher, for project
+  ``llnl-ssapy-data``.
+* Set the owner to ``llnl`` and repository to ``SSAPy-Data``.
+* Set the workflow filename to ``publish.yml``.
+* Set the GitHub environment to ``pypi``.
+
+After PyPI trust is configured, publish by creating a GitHub release whose tag
+matches the version in ``pyproject.toml``, for example ``v0.1.0``. The
+``Publish to PyPI`` workflow builds a clean wheel and source distribution, runs
+tests, checks the manifest, and uploads through OpenID Connect (OIDC). No PyPI
+API token is required.
+
+Data provenance
+---------------
+
+Each data pull request should document the source URL, license, retrieval date,
+and any preprocessing steps for new packaged datasets. Candidate sources include:
+
+* Earth gravity fields:
+  `ICGEM time-variable gravity fields <http://icgem.gfz-potsdam.de/tom_longtime>`_
+* Other celestial bodies:
+  `ICGEM celestial gravity fields <http://icgem.gfz-potsdam.de/tom_celestial>`_
+
+Code of Conduct
+---------------
+
+Please note that SSAPy-Data has a
+`Code of Conduct <https://github.com/LLNL/SSAPy-Data/blob/main/CODE_OF_CONDUCT.md>`_.
+By participating in the SSAPy-Data community, you agree to abide by its rules.
+
+License
+-------
+
+SSAPy-Data is distributed under the terms of the MIT license. All new
+contributions must be made under the MIT license.
+
+See the `license <https://github.com/LLNL/SSAPy-Data/blob/main/LICENSE>`_ and
+`NOTICE <https://github.com/LLNL/SSAPy-Data/blob/main/NOTICE>`_ for details.
+
+SPDX-License-Identifier: MIT
+
+LLNL-CODE-862420

llnl_ssapy_data-0.1.0/src/llnl_ssapy_data.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+MANIFEST.in
+NOTICE
+README.rst
+pyproject.toml
+src/llnl_ssapy_data.egg-info/PKG-INFO
+src/llnl_ssapy_data.egg-info/SOURCES.txt
+src/llnl_ssapy_data.egg-info/dependency_links.txt
+src/llnl_ssapy_data.egg-info/requires.txt
+src/llnl_ssapy_data.egg-info/top_level.txt
+src/ssapy_data/__init__.py
+src/ssapy_data/_manifest.py
+src/ssapy_data/_resources.py
+src/ssapy_data/manifest.json
+src/ssapy_data/data/README.md
+tests/test_package_data.py

llnl_ssapy_data-0.1.0/src/llnl_ssapy_data.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

llnl_ssapy_data-0.1.0/src/llnl_ssapy_data.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[dev]
+build
+pytest
+twine

llnl_ssapy_data-0.1.0/src/llnl_ssapy_data.egg-info/top_level.txt

@@ -0,0 +1 @@
+ssapy_data

llnl_ssapy_data-0.1.0/src/ssapy_data/__init__.py

@@ -0,0 +1,30 @@
+"""Packaged data resources for SSAPy and SSAPy Toolkit."""
+
+from __future__ import annotations
+
+from ._manifest import manifest, manifest_entries
+from ._resources import (
+    DataResourceNotFoundError,
+    data_path,
+    data_resource,
+    iter_data_files,
+    open_binary,
+    open_text,
+    read_binary,
+    read_text,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DataResourceNotFoundError",
+    "data_path",
+    "data_resource",
+    "iter_data_files",
+    "manifest",
+    "manifest_entries",
+    "open_binary",
+    "open_text",
+    "read_binary",
+    "read_text",
+]

llnl_ssapy_data-0.1.0/src/ssapy_data/_manifest.py

@@ -0,0 +1,23 @@
+"""Manifest helpers for packaged SSAPy data."""
+
+from __future__ import annotations
+
+import json
+from importlib.resources import files
+from typing import Any
+
+PACKAGE = "ssapy_data"
+MANIFEST_NAME = "manifest.json"
+
+
+def manifest() -> dict[str, Any]:
+    """Return the packaged data manifest."""
+
+    resource = files(PACKAGE).joinpath(MANIFEST_NAME)
+    return json.loads(resource.read_text(encoding="utf-8"))
+
+
+def manifest_entries() -> list[dict[str, Any]]:
+    """Return file entries from the packaged data manifest."""
+
+    return list(manifest()["files"])

llnl_ssapy_data-0.1.0/src/ssapy_data/_resources.py

@@ -0,0 +1,165 @@
+"""Resource helpers for data packaged in ``ssapy_data`` wheels."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from importlib.resources import as_file, files
+try:
+    from importlib.resources.abc import Traversable
+except ImportError:  # Python 3.10
+    from importlib.abc import Traversable
+from os import PathLike
+from pathlib import Path, PurePosixPath
+from typing import Iterator
+
+DATA_ROOT = "data"
+PACKAGE = "ssapy_data"
+
+
+class DataResourceNotFoundError(FileNotFoundError):
+    """Raised when a requested packaged data resource is absent."""
+
+
+def data_resource(
+    relative_path: str | PathLike[str] = "",
+    *,
+    data_root: str | PathLike[str] = DATA_ROOT,
+    must_exist: bool = True,
+) -> Traversable:
+    """Return an ``importlib.resources`` object for packaged SSAPy data.
+
+    Parameters
+    ----------
+    relative_path
+        POSIX-style path below ``data_root``. Absolute paths and ``..`` traversal
+        are rejected.
+    data_root
+        Directory inside ``ssapy_data`` that contains data resources.
+    must_exist
+        If ``True``, raise :class:`DataResourceNotFoundError` when the resource
+        is missing.
+    """
+
+    resource = files(PACKAGE)
+    for part in _safe_parts(data_root):
+        resource = resource.joinpath(part)
+    for part in _safe_parts(relative_path):
+        resource = resource.joinpath(part)
+
+    if must_exist and not resource.exists():
+        requested = _display_path(data_root, relative_path)
+        raise DataResourceNotFoundError(
+            f"Data resource '{requested}' was not found in package '{PACKAGE}'."
+        )
+
+    return resource
+
+
+@contextmanager
+def data_path(
+    relative_path: str | PathLike[str],
+    *,
+    data_root: str | PathLike[str] = DATA_ROOT,
+) -> Iterator[Path]:
+    """Yield a filesystem path for a packaged data file.
+
+    Use this when a downstream library requires a real path instead of a file
+    object. The yielded path may be a temporary extraction path for zipped wheels,
+    so callers should use it only inside the context manager.
+    """
+
+    resource = data_resource(relative_path, data_root=data_root)
+    if not resource.is_file():
+        requested = _display_path(data_root, relative_path)
+        raise DataResourceNotFoundError(f"Data resource '{requested}' is not a file.")
+
+    with as_file(resource) as path:
+        yield path
+
+
+@contextmanager
+def open_binary(relative_path: str | PathLike[str], *, data_root: str | PathLike[str] = DATA_ROOT):
+    """Open a packaged data file in binary mode."""
+
+    resource = data_resource(relative_path, data_root=data_root)
+    if not resource.is_file():
+        requested = _display_path(data_root, relative_path)
+        raise DataResourceNotFoundError(f"Data resource '{requested}' is not a file.")
+
+    with resource.open("rb") as file_handle:
+        yield file_handle
+
+
+@contextmanager
+def open_text(
+    relative_path: str | PathLike[str],
+    *,
+    data_root: str | PathLike[str] = DATA_ROOT,
+    encoding: str = "utf-8",
+):
+    """Open a packaged data file in text mode."""
+
+    resource = data_resource(relative_path, data_root=data_root)
+    if not resource.is_file():
+        requested = _display_path(data_root, relative_path)
+        raise DataResourceNotFoundError(f"Data resource '{requested}' is not a file.")
+
+    with resource.open("r", encoding=encoding) as file_handle:
+        yield file_handle
+
+
+def read_binary(relative_path: str | PathLike[str], *, data_root: str | PathLike[str] = DATA_ROOT) -> bytes:
+    """Read a packaged binary data file."""
+
+    with open_binary(relative_path, data_root=data_root) as file_handle:
+        return file_handle.read()
+
+
+def read_text(
+    relative_path: str | PathLike[str],
+    *,
+    data_root: str | PathLike[str] = DATA_ROOT,
+    encoding: str = "utf-8",
+) -> str:
+    """Read a packaged text data file."""
+
+    with open_text(relative_path, data_root=data_root, encoding=encoding) as file_handle:
+        return file_handle.read()
+
+
+def iter_data_files(relative_path: str | PathLike[str] = "") -> Iterator[Traversable]:
+    """Yield packaged data files recursively below ``relative_path``."""
+
+    root = data_resource(relative_path)
+    if root.is_file():
+        yield root
+        return
+
+    for child in sorted(root.iterdir(), key=lambda item: item.name):
+        if child.is_file():
+            yield child
+        elif child.is_dir():
+            child_relative = _display_path(relative_path, child.name)
+            yield from iter_data_files(child_relative)
+
+
+def _safe_parts(path: str | PathLike[str]) -> tuple[str, ...]:
+    path_string = str(path)
+    if path_string in {"", "."}:
+        return ()
+
+    pure_path = PurePosixPath(path_string)
+    if pure_path.is_absolute():
+        raise ValueError(f"Packaged data paths must be relative, got '{path_string}'.")
+
+    parts = tuple(part for part in pure_path.parts if part not in {"", "."})
+    if ".." in parts:
+        raise ValueError(f"Packaged data paths cannot contain '..', got '{path_string}'.")
+    return parts
+
+
+def _display_path(*paths: str | PathLike[str]) -> str:
+    parts: list[str] = []
+    for path in paths:
+        parts.extend(_safe_parts(path))
+    return "/".join(parts)

llnl_ssapy_data-0.1.0/src/ssapy_data/data/README.md

@@ -0,0 +1,9 @@
+# SSAPy Data Payload Directory
+
+Add new reusable datasets for SSAPy Toolkit under this directory. Do not add data already packaged by base SSAPy unless a later migration explicitly moves that dependency here.
+
+After changing files here, run:
+
+```bash
+python scripts/update_manifest.py
+```

llnl_ssapy_data-0.1.0/src/ssapy_data/manifest.json

@@ -0,0 +1,12 @@
+{
+  "data_root": "data",
+  "files": [
+    {
+      "bytes": 289,
+      "path": "README.md",
+      "sha256": "b860d6a1e800c0ee4f7bd9c493e22de75545fd37f087db8b9a015a690e8b7ae1"
+    }
+  ],
+  "generated_by": "scripts/update_manifest.py",
+  "schema_version": 1
+}

llnl_ssapy_data-0.1.0/tests/test_package_data.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+import pytest
+
+from ssapy_data import (
+    DataResourceNotFoundError,
+    data_path,
+    data_resource,
+    iter_data_files,
+    manifest,
+    read_binary,
+    read_text,
+)
+
+
+def test_known_resources_are_packaged():
+    assert data_resource("README.md").is_file()
+
+
+def test_text_and_binary_read_helpers():
+    text = read_text("README.md")
+    assert "SSAPy Data Payload Directory" in text
+    assert read_binary("README.md").startswith(b"# SSAPy Data")
+
+
+def test_data_path_yields_filesystem_path():
+    with data_path("README.md") as path:
+        assert path.exists()
+        assert path.name == "README.md"
+        assert path.stat().st_size > 0
+
+
+def test_manifest_matches_packaged_files():
+    payload = manifest()
+    entries = payload["files"]
+    entry_paths = {entry["path"] for entry in entries}
+    actual_paths = {resource.name for resource in iter_data_files()}
+
+    assert payload["schema_version"] == 1
+    assert payload["data_root"] == "data"
+    assert entry_paths == {"README.md"}
+    assert actual_paths == {"README.md"}
+
+    for entry in entries:
+        resource = data_resource(entry["path"])
+        with data_path(entry["path"]) as path:
+            assert path.stat().st_size == entry["bytes"]
+            assert hashlib.sha256(path.read_bytes()).hexdigest() == entry["sha256"]
+        assert resource.is_file()
+
+
+def test_missing_and_unsafe_paths_are_rejected():
+    with pytest.raises(DataResourceNotFoundError, match="missing.dat"):
+        data_resource("missing.dat")
+    with pytest.raises(ValueError, match="must be relative"):
+        data_resource("/earth.png")
+    with pytest.raises(ValueError, match="cannot contain"):
+        data_resource("Earth_graphics/../earth.png")