Make a deprecated name an error in tests and snippets

pyproject.toml

@@ -130,4 +130,9 @@ pythonpath = ["tests"]
 addopts = ["--dist=loadgroup"]
 filterwarnings = [
     "ignore:Low sampling rate:UserWarning",
+    # A deprecated phonometry name used anywhere in the suite is an error, not
+    # a line in a log nobody reads: the shims exist for users on the old paths,
+    # and the tests are not users. The one file that exercises the shims on
+    # purpose catches them with pytest.warns, which passes under this filter.
+    "error:.*is deprecated since phonometry.*:DeprecationWarning",
 ]

scripts/check_doc_snippets.py

@@ -255,7 +255,16 @@ def placeholder(node: ast.Call) -> bool:
 def _run_page(page: pathlib.Path) -> tuple[pathlib.Path, str]:
     """Run a page's blocks as one script; return its stderr tail on failure."""
     runnable = [b for b in _blocks(page) if not _is_sketch(b)]
-    script = "import matplotlib\nmatplotlib.use('Agg')\n" + "\n".join(runnable)
+    # A deprecated phonometry name in a snippet is an error, exactly as it is
+    # in the test suite (pyproject filterwarnings): the guides teach the
+    # canonical API, and a page that teaches an alias teaches a path that the
+    # next major release removes.
+    script = (
+        "import warnings\n"
+        "warnings.filterwarnings('error', message='.*is deprecated since phonometry.*',"
+        " category=DeprecationWarning)\n"
+        "import matplotlib\nmatplotlib.use('Agg')\n" + "\n".join(runnable)
+    )
     with tempfile.TemporaryDirectory() as tmp:
         path = pathlib.Path(tmp) / "snippet.py"
         path.write_text(script, encoding="utf-8")

tests/data/cnossos/README.md

@@ -16,7 +16,7 @@ workbook was computed in 2014 with the database that Commission Directive
 Delegated Directive (EU) 2021/1226 replaced Tables G-1b, G-2, G-3a, G-4 and
 G-7. The coefficients of the current text live in `tests/reference_data.py`,
 transcribed from the Official Journal, and pin the tables shipped in
-`phonometry.environmental.cnossos_rail`.
+`phonometry.environment.sources.cnossos_rail`.
 
 Only the running conditions the Directive models are transcribed. The
 catalogue carries four (constant, accelerating, decelerating, idling) where
@@ -122,7 +122,7 @@ without the reconstruction.
 The coefficients of the current text, Tables F-1 to F-4 as they stand after
 (EU) 2021/1226, are *not* here: they live in `tests/reference_data.py`, also
 machine-transcribed from the Official Journal, and pin the tables shipped in
-`phonometry.environmental.cnossos_road`.
+`phonometry.environment.sources.cnossos_road`.
 
 `tests/environment/sources/test_cnossos_road.py` feeds the shipped equations of
 Annex II 2.2 the superseded 2015 coefficient set and requires the workbook's

tests/simulation/test_fdtd_ntff.py

@@ -32,7 +32,7 @@
   (Sci. Rep. 7, 5389, 2017) is meshed at ``dx = 0.5 mm`` (slits, necks and
   cavities all resolved by at least four cells) and its 2 kHz NTFF polar
   response is compared against the library's TMM + Fraunhofer chain
-  (:func:`~phonometry.materials.metadiffuser_polar_response`), the
+  (:func:`~phonometry.materials.diffusers.metadiffuser_polar_response`), the
   end-to-end counterpart of the paper's TMM-vs-FEM comparison (their
   Fig. 3g), which the paper itself reports agreeing up to "small
   discrepancies". Grid convergence of the pattern was verified against a