polyphys 1.0.0__py3-none-any.whl

polyphys/tests/test_conftest.py

@@ -0,0 +1,414 @@
+"""Tests for the shared fixtures and the ``private_data`` and ``lammps``
+markers in ``polyphys/tests/conftest.py``.
+
+Expected file counts and indices come from the arguments each test passes.
+Expected file contents come from the formula documented in
+``lineage_tree_value``. Expected LAMMPS section layouts come from the LAMMPS
+manual's read_data and dump pages: ``atom-ID atom-type x y z`` for
+``atomic``, ``atom-ID molecule-ID atom-type x y z`` for ``bond`` and
+``angle``, and one bond and one angle per consecutive pair and triple of a
+linear chain. The marker tests run a nested pytest session with
+``pytester``; the ``lammps`` ones name the Python interpreter as the
+executable, since any executable file stands in for LAMMPS there.
+"""
+import sys
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from polyphys.tests import synthetic
+
+
+def _sections(text: str) -> dict[str, list[str]]:
+    """Split a LAMMPS data file into its header and its named sections."""
+    blocks = [b.strip().splitlines() for b in text.split("\n\n")]
+    sections = {"header": blocks[1]}
+    for title, body in zip(blocks[2:], blocks[3:]):
+        if len(title) == 1 and not title[0][0].isdigit():
+            sections[title[0].split("#")[0].strip()] = body
+    return sections
+
+
+def _header_counts(header: list[str]) -> dict[str, int]:
+    """Map each header keyword, such as 'bonds', to its count."""
+    return {line.split(maxsplit=1)[1]: int(line.split()[0])
+            for line in header}
+
+
+def _dump_frames(text: str) -> list[list[str]]:
+    """Split a LAMMPS dump into frames, each a list of its lines."""
+    frames = text.split("ITEM: TIMESTEP\n")[1:]
+    return [frame.strip().splitlines() for frame in frames]
+
+
+@pytest.fixture(params=synthetic.__all__)
+def parser_class(request: pytest.FixtureRequest) -> type:
+    """Each synthetic parser class, one per test run."""
+    return getattr(synthetic, request.param)
+
+
+@pytest.fixture
+def private_data_project(pytester: pytest.Pytester) -> pytest.Pytester:
+    """A nested pytest project with this conftest and one private_data test."""
+    pytester.makeconftest(Path(__file__).with_name("conftest.py").read_text())
+    pytester.makepyfile(
+        test_private="""
+        import pytest
+
+        @pytest.mark.private_data
+        def test_reads_data(private_data_dir):
+            assert private_data_dir.is_dir()
+        """
+    )
+    return pytester
+
+
+@pytest.fixture
+def lammps_project(pytester: pytest.Pytester) -> pytest.Pytester:
+    """A nested pytest project whose conftest imports this conftest (so the
+    nested session runs the real module's hooks and fixtures, in process),
+    with one lammps test and one unmarked test that takes the
+    ``lammps_executable`` fixture."""
+    pytester.makeconftest(
+        "from polyphys.tests.conftest import *  # noqa: F401,F403\n")
+    pytester.makepyfile(
+        test_lammps="""
+        from pathlib import Path
+
+        import pytest
+
+        @pytest.mark.lammps
+        def test_runs_lammps(lammps_executable):
+            assert Path(lammps_executable).exists()
+
+        def test_fixture_without_marker(lammps_executable):
+            assert isinstance(lammps_executable, str)
+        """
+    )
+    return pytester
+
+
+def test_make_lineage_tree_writes_one_file_per_segment(make_lineage_tree):
+    """A segment tree holds n_ensembles * n_wholes * n_segments files."""
+    tree = make_lineage_tree(
+        synthetic.ChainCyl, n_ensembles=2, n_wholes=3, n_segments=2
+    )
+
+    assert len(tree.paths) == 12
+    assert all(path.is_file() for path in tree.paths)
+
+
+def test_make_lineage_tree_names_parse_without_missing_keywords(
+    make_lineage_tree, capsys, parser_class
+):
+    """Every segment filename yields every keyword of the parser's grammar."""
+    tree = make_lineage_tree(parser_class)
+
+    parsed = [parser_class(path, "segment", tree.group, ispath=True)
+              for path in tree.paths]
+
+    assert len(parsed) == len(tree.paths)
+    # The parsers report a missing keyword on stdout rather than raising.
+    assert capsys.readouterr().out == ""
+
+
+def test_make_lineage_tree_groups_into_wholes_and_ensembles(
+    make_lineage_tree, parser_class
+):
+    """Segments group into one whole per replicate, one ensemble per state."""
+    tree = make_lineage_tree(
+        parser_class, n_ensembles=2, n_wholes=3, n_segments=2
+    )
+
+    parsed = [parser_class(path, "segment", tree.group, ispath=True)
+              for path in tree.paths]
+
+    assert len({p.whole for p in parsed}) == 6
+    assert len({p.ensemble_long for p in parsed}) == 2
+
+
+def test_make_lineage_tree_index_is_read_only(make_lineage_tree):
+    """A tree's file index cannot be changed after the tree is written."""
+    tree = make_lineage_tree(synthetic.ChainCyl, n_ensembles=1)
+
+    with pytest.raises(TypeError, match="does not support item assignment"):
+        tree.index[tree.paths[0]] = (9, 9, 9)
+
+
+def test_make_lineage_tree_numbers_wholes_and_segments_from_one(
+    make_lineage_tree,
+):
+    """The ens and j values in the names count wholes and segments from 1."""
+    tree = make_lineage_tree(
+        synthetic.ChainCyl, n_ensembles=1, n_wholes=3, n_segments=2
+    )
+
+    parsed = [synthetic.ChainCyl(path, "segment", tree.group, ispath=True)
+              for path in tree.paths]
+
+    assert [(p.ensemble_id, p.segment_id) for p in parsed] == [
+        (1, 1), (1, 2), (2, 1), (2, 2), (3, 1), (3, 2)
+    ]
+
+
+@pytest.mark.parametrize(
+    ("lineage", "ext", "load", "key", "expected"),
+    [
+        pytest.param("segment", ".npy", np.load, (2, 3, 1),
+                     [2310.0, 2311.0, 2312.0], id="segment-npy"),
+        pytest.param("segment", ".csv",
+                     lambda p: pd.read_csv(p)["gyrTMon"].to_numpy(),
+                     (2, 3, 1), [2310.0, 2311.0, 2312.0], id="segment-csv"),
+        pytest.param("whole", ".npy", np.load, (2, 3, 0),
+                     [2300.0, 2301.0, 2302.0], id="whole-npy"),
+    ],
+)
+def test_make_lineage_tree_file_holds_documented_values(
+    make_lineage_tree, lineage, ext, load, key, expected
+):
+    """A file holds 1000*ensemble + 100*whole + 10*segment + row."""
+    tree = make_lineage_tree(
+        synthetic.ChainCyl, n_ensembles=2, n_wholes=3, lineage=lineage,
+        ext=ext, prop="gyrTMon", n_rows=3,
+    )
+    path = next(p for p, index in tree.index.items() if index == key)
+
+    values = load(path)
+
+    # Integers below 2**53 are exact in float64 and in the CSV text.
+    np.testing.assert_array_equal(values, expected)
+
+
+@pytest.mark.parametrize(
+    ("atom_style", "expected"),
+    [
+        pytest.param("atomic", {"atoms": 4, "bonds": 0, "angles": 0},
+                     id="atomic"),
+        pytest.param("bond", {"atoms": 4, "bonds": 3, "angles": 0},
+                     id="bond"),
+        pytest.param("angle", {"atoms": 4, "bonds": 3, "angles": 2},
+                     id="angle"),
+    ],
+)
+def test_make_lammps_data_header_counts_match_sections(
+    make_lammps_data, atom_style, expected
+):
+    """A 4-atom chain's header counts equal its section line counts."""
+    path = make_lammps_data(atom_style=atom_style)
+
+    sections = _sections(path.read_text())
+
+    counts = _header_counts(sections["header"])
+    assert {key: counts.get(key, 0) for key in expected} == expected
+    assert {
+        "atoms": len(sections["Atoms"]),
+        "bonds": len(sections.get("Bonds", [])),
+        "angles": len(sections.get("Angles", [])),
+    } == expected
+
+
+@pytest.mark.parametrize(
+    ("atom_style", "n_columns"),
+    [
+        pytest.param("atomic", 5, id="atomic"),
+        pytest.param("bond", 6, id="bond"),
+        pytest.param("angle", 6, id="angle"),
+    ],
+)
+def test_make_lammps_data_atoms_columns_follow_style(
+    make_lammps_data, atom_style, n_columns
+):
+    """Atoms lines have the column count LAMMPS reads for the atom style."""
+    path = make_lammps_data(atom_style=atom_style)
+
+    atoms = _sections(path.read_text())["Atoms"]
+
+    assert {len(line.split()) for line in atoms} == {n_columns}
+
+
+def test_make_lammps_dump_round_trips_positions(make_lammps_dump):
+    """Positions read back from the dump match those written."""
+    positions = np.linspace(0.0, 9.5, 36).reshape(3, 4, 3)
+    path = make_lammps_dump(positions=positions, timesteps=[0, 500, 1000])
+
+    frames = _dump_frames(path.read_text())
+
+    assert [frame[0] for frame in frames] == ["0", "500", "1000"]
+    assert [int(frame[2]) for frame in frames] == [4, 4, 4]
+    assert {frame[7] for frame in frames} == {"ITEM: ATOMS id type x y z"}
+    read = np.array([[line.split()[2:] for line in frame[8:]]
+                     for frame in frames], dtype=float)
+    # Six decimals are written, so a value can be off by half of 1e-6.
+    np.testing.assert_allclose(read, positions, rtol=0, atol=5e-7)
+
+
+@pytest.mark.parametrize(
+    "boundary",
+    [pytest.param("pp pp pp", id="periodic"),
+     pytest.param("ff ff pp", id="cylinder")],
+)
+def test_make_lammps_dump_writes_boundary_flags(make_lammps_dump, boundary):
+    """Every BOX BOUNDS line carries the requested boundary flags."""
+    path = make_lammps_dump(boundary=boundary)
+
+    frames = _dump_frames(path.read_text())
+
+    assert {frame[3] for frame in frames} == {
+        f"ITEM: BOX BOUNDS {boundary}"
+    }
+
+
+def test_private_data_skips_when_data_dir_unset(
+    private_data_project, monkeypatch
+):
+    """A private_data test is skipped when POLYPHYS_DATA_DIR is unset."""
+    monkeypatch.delenv("POLYPHYS_DATA_DIR", raising=False)
+
+    result = private_data_project.runpytest_subprocess()
+
+    result.assert_outcomes(skipped=1)
+
+
+def test_private_data_runs_when_data_dir_exists(
+    private_data_project, monkeypatch, tmp_path
+):
+    """A private_data test runs when POLYPHYS_DATA_DIR names a directory."""
+    monkeypatch.setenv("POLYPHYS_DATA_DIR", str(tmp_path))
+
+    result = private_data_project.runpytest_subprocess()
+
+    result.assert_outcomes(passed=1)
+
+
+def test_private_data_errors_when_data_dir_missing(
+    private_data_project, monkeypatch, tmp_path
+):
+    """A private_data test errors when POLYPHYS_DATA_DIR is no directory."""
+    monkeypatch.setenv("POLYPHYS_DATA_DIR", str(tmp_path / "missing"))
+
+    result = private_data_project.runpytest_subprocess()
+
+    result.assert_outcomes(errors=1)
+
+
+def test_lammps_skips_without_an_executable(lammps_project, monkeypatch):
+    """A lammps test, and the fixture used without the marker, are skipped
+    when LMP is unset and lmp_serial is not on PATH."""
+    monkeypatch.delenv("LMP", raising=False)
+    monkeypatch.setenv("PATH", "")
+
+    result = lammps_project.runpytest()
+
+    result.assert_outcomes(skipped=2)
+
+
+def test_lammps_runs_with_the_executable_lmp_names(
+    lammps_project, monkeypatch
+):
+    """A lammps test runs, and the fixture returns the path, when LMP names
+    an executable."""
+    monkeypatch.setenv("LMP", sys.executable)
+
+    result = lammps_project.runpytest()
+
+    result.assert_outcomes(passed=2)
+
+
+def test_lammps_errors_when_lmp_is_not_an_executable(
+    lammps_project, monkeypatch, tmp_path
+):
+    """A lammps test errors in setup when LMP names a missing file; the
+    fixture alone returns the name, since the marker does the checking."""
+    monkeypatch.setenv("LMP", str(tmp_path / "missing"))
+
+    result = lammps_project.runpytest()
+
+    result.assert_outcomes(errors=1, passed=1)
+
+
+def test_strict_markers_rejects_misspelled_private_data(pytester):
+    """A misspelled private_data marker fails collection."""
+    pytester.makeconftest(Path(__file__).with_name("conftest.py").read_text())
+    pytester.makepyfile(
+        test_typo="""
+        import pytest
+
+        @pytest.mark.private_dta
+        def test_reads_data():
+            pass
+        """
+    )
+
+    result = pytester.runpytest_subprocess("--strict-markers")
+
+    result.assert_outcomes(errors=1)
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "match"),
+    [
+        pytest.param({"n_wholes": 0}, "'n_wholes' must be from 1 to 9",
+                     id="size-below-range"),
+        pytest.param({"n_rows": 11}, "'n_rows' must be from 1 to 10",
+                     id="rows-above-range"),
+        pytest.param({"lineage": "ensemble"},
+                     "'lineage' must be 'segment' or 'whole'",
+                     id="unknown-lineage"),
+        pytest.param({"ext": ".txt"}, "'ext' must be '.npy' or '.csv'",
+                     id="unknown-ext"),
+        pytest.param({"attrs": {"ens": 1}}, "'attrs' cannot set",
+                     id="reserved-keyword"),
+        pytest.param({"vary": "xyz"},
+                     "not keywords of ChainCyl whole names",
+                     id="unknown-keyword"),
+    ],
+)
+def test_make_lineage_tree_rejects_invalid_arguments(
+    make_lineage_tree, kwargs, match
+):
+    """A lineage tree with an invalid argument raises before writing."""
+    with pytest.raises(ValueError, match=match):
+        make_lineage_tree(synthetic.ChainCyl, **kwargs)
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "match"),
+    [
+        pytest.param({"atom_style": "full"}, "'atom_style' must be one of",
+                     id="unknown-style"),
+        pytest.param({"positions": np.zeros((4, 2))},
+                     r"'positions' must have shape \(n_atoms, 3\)",
+                     id="positions-not-3d"),
+    ],
+)
+def test_make_lammps_data_rejects_invalid_arguments(
+    make_lammps_data, kwargs, match
+):
+    """A data file with an unknown style or bad positions raises."""
+    with pytest.raises(ValueError, match=match):
+        make_lammps_data(**kwargs)
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "match"),
+    [
+        pytest.param({"positions": np.zeros((4, 3))},
+                     r"'positions' must have shape \(n_frames, n_atoms, 3\)",
+                     id="positions-one-frame-2d"),
+        pytest.param({"timesteps": [0]}, "'timesteps' has 1 entries for 3",
+                     id="timesteps-too-few"),
+        pytest.param({"boundary": "pp pp"}, "'boundary' must be three flags",
+                     id="boundary-two-flags"),
+        pytest.param({"boundary": "px pp pp"},
+                     "'boundary' must be three flags",
+                     id="boundary-unknown-letter"),
+    ],
+)
+def test_make_lammps_dump_rejects_invalid_arguments(
+    make_lammps_dump, kwargs, match
+):
+    """A dump with bad positions, timesteps, or boundary flags raises."""
+    with pytest.raises(ValueError, match=match):
+        make_lammps_dump(**kwargs)

polyphys/tests/test_docs.py

@@ -0,0 +1,82 @@
+"""
+Tests for the examples of the documentation pages in ``docs/source/``.
+
+pytest collects doctests from ``polyphys``, ``README.md``, and ``projects``
+only, so the ``>>>`` examples of a documentation page run here, one test
+per page, through :func:`doctest.testfile`. The pages compute their expected
+values by hand in the text beside each example.
+"""
+import doctest
+import os
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+
+import pytest
+
+import polyphys
+
+
+@pytest.fixture
+def docs_source() -> Path:
+    """The ``docs/source/`` directory of the checkout under test."""
+    return Path(__file__).resolve().parents[2] / "docs" / "source"
+
+
+@pytest.mark.parametrize("page", [
+    pytest.param("quickstart.md", id="quickstart"),
+    pytest.param("lineage.md", id="lineage"),
+    pytest.param("studies.md", id="studies"),
+    pytest.param("usage.md", id="usage"),
+    pytest.param("viz.md", id="viz"),
+])
+def test_docs_page_examples_run(docs_source: Path, page: str) -> None:
+    """Every example of the page gives the output the page shows."""
+    path = docs_source / page
+
+    result = doctest.testfile(str(path), module_relative=False,
+                              encoding="utf-8", verbose=False)
+
+    assert result.attempted > 0, f"{page} has no examples"
+    assert result.failed == 0, f"{result.failed} example(s) of {page} failed"
+
+
+def test_mocked_modules_import_with_their_annotations_evaluated():
+    """The probe and viz modules import, and every annotation in them
+    evaluates, with MDAnalysis and matplotlib replaced by the mocks of the
+    docs build."""
+    pytest.importorskip("sphinx.ext.autodoc.mock")
+    script = textwrap.dedent("""\
+        import importlib
+        import inspect
+        import pkgutil
+
+        from sphinx.ext.autodoc.mock import mock
+
+        with mock(['MDAnalysis', 'matplotlib']):
+            for package in ('polyphys.probe', 'polyphys.viz'):
+                names = [package] + [
+                    f'{package}.{info.name}' for info in pkgutil.iter_modules(
+                        importlib.import_module(package).__path__)]
+                for name in names:
+                    module = importlib.import_module(name)
+                    for obj in vars(module).values():
+                        if getattr(obj, '__module__', None) != name:
+                            continue
+                        members = [obj] + (list(vars(obj).values())
+                                           if inspect.isclass(obj) else [])
+                        for member in members:
+                            if inspect.isfunction(member) or inspect.isclass(
+                                    member):
+                                inspect.get_annotations(member)
+        """)
+    # The child imports this checkout's package.
+    env = dict(os.environ,
+               PYTHONPATH=str(Path(polyphys.__file__).parents[1]))
+
+    completed = subprocess.run(
+        [sys.executable, '-c', script], env=env, capture_output=True,
+        text=True, timeout=120, check=False)
+
+    assert completed.returncode == 0, completed.stderr

polyphys/tests/test_packaging.py

@@ -0,0 +1,97 @@
+"""
+Tests for :mod:`polyphys` distribution metadata.
+
+These tests guard the packaging contract declared in ``pyproject.toml``
+against defects that are invisible to the rest of the test suite because
+they only surface in an *installed* copy of the package: an entry point
+naming a module that does not exist, or a malformed version string. They
+also guard the public API that ``docs/source/stability.md`` defines: the
+``__all__`` of every module on the API page.
+"""
+import importlib
+import re
+from importlib.metadata import PackageNotFoundError, distribution
+from pathlib import Path
+
+import pytest
+
+from polyphys.__version__ import __version__
+
+#: ``MAJOR.MINOR.PATCH`` with an optional pre-release/build suffix.
+SEMVER_RE = re.compile(
+    r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)"
+    r"(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$"
+)
+
+
+#: The API page, whose autosummary lists the public modules.
+API_PAGE = Path(__file__).resolve().parents[2] / "docs" / "source" / "api.rst"
+
+#: The extra each optional subpackage needs, by module prefix.
+EXTRAS = {"polyphys.probe": "MDAnalysis", "polyphys.viz.helpers": "matplotlib"}
+
+
+def _api_modules() -> list[str]:
+    """Return the modules the API page lists, or none without the page."""
+    if not API_PAGE.exists():  # pragma: no cover - depends on the checkout
+        return []
+    return re.findall(r"^   (polyphys(?:\.\w+)+)$", API_PAGE.read_text(),
+                      flags=re.MULTILINE)
+
+
+def _polyphys_distribution():
+    """
+    Return the installed ``polyphys`` distribution, or skip the test.
+
+    Skipping keeps the suite runnable from a bare source checkout, where
+    no distribution metadata exists to inspect.
+    """
+    try:
+        return distribution("polyphys")
+    except PackageNotFoundError:  # pragma: no cover - depends on install
+        pytest.skip("polyphys is not installed; no metadata to inspect")
+
+
+def test_version_is_valid_semver() -> None:
+    """``__version__`` must be a valid semantic version string.
+
+    Guards the release process: ``pyproject.toml`` reads this attribute
+    dynamically, so a malformed value produces a broken distribution.
+    """
+    assert SEMVER_RE.match(__version__), (
+        f"__version__ = {__version__!r} is not valid semantic versioning"
+    )
+
+
+def test_declared_console_scripts_are_importable() -> None:
+    """Every declared console script must resolve to a real callable.
+
+    Regression test: the distribution previously declared
+    ``polyphys = polyphys.cli:main`` while ``polyphys/cli.py`` did not
+    exist, so every install shipped a command that raised
+    ``ModuleNotFoundError`` when run.
+    """
+    dist = _polyphys_distribution()
+    scripts = [
+        ep for ep in dist.entry_points if ep.group == "console_scripts"
+    ]
+    for entry_point in scripts:
+        target = entry_point.load()
+        assert callable(target), (
+            f"console script {entry_point.name!r} points at "
+            f"{entry_point.value!r}, which is not callable"
+        )
+
+
+@pytest.mark.parametrize("module_name", _api_modules())
+def test_api_module_declares_resolvable_all(module_name: str) -> None:
+    """Every module on the API page declares ``__all__``, and each name in
+    it is an attribute of the module."""
+    for prefix, extra in EXTRAS.items():
+        if module_name.startswith(prefix):
+            pytest.importorskip(extra)
+    module = importlib.import_module(module_name)
+
+    assert hasattr(module, "__all__"), f"{module_name} has no __all__"
+    missing = [name for name in module.__all__ if not hasattr(module, name)]
+    assert missing == []