Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
# SPDX-License-Identifier: Apache-2.0
"""Import-surface contract checks for downstream package consumers."""
from __future__ import annotations
import ast
import importlib
import subprocess
import sys
from pathlib import Path
import pytest
from sprite_gen._modules import qualified
ROOT = Path(__file__).resolve().parents[2]
PACKAGE_DIR = ROOT / "sprite_gen"
PACKAGE_RUN_MODULES = [
"anchor",
"compose_atlas",
"compose_cycle",
"compose_gif",
"correction_loop",
"export_aseprite",
"export_pngs",
"extract",
"gen",
"gen_set",
"inspect",
"prepare",
"preview",
"score",
"serve_curation",
"slice_sheet",
"unpack_atlas",
"video",
"canvas",
"frames",
"loop",
"batch",
]
@pytest.fixture
def import_probe():
"""Import a module for inspection and leave the process as it was.
Importing a submodule binds it as an attribute on its parent package. If a
submodule ever shares its name with an attribute the package already exports,
that binding replaces the attribute for the rest of the session (the retired
`sprite_gen.gen.generate_image` shim did exactly that to the live
`generate_image()` function until it was removed on 2026-09-13). The probe records
the parent attribute and the `sys.modules` entry before importing and restores
both afterwards, so this test observes the package without rewriting it for
tests that run after it — a general isolation device, not a fix for any one clash.
"""
restores: list[tuple[object, str, object]] = []
fresh_modules: list[str] = []
missing = object()
def probe(module_path: str):
parent_path, _, child = module_path.rpartition(".")
parent = sys.modules.get(parent_path) if parent_path else None
was_loaded = module_path in sys.modules
if parent is not None:
restores.append((parent, child, getattr(parent, child, missing)))
module = importlib.import_module(module_path)
if not was_loaded:
fresh_modules.append(module_path)
return module
yield probe
for parent, child, prior in reversed(restores):
if prior is missing:
if hasattr(parent, child):
delattr(parent, child)
else:
setattr(parent, child, prior)
for module_path in fresh_modules:
sys.modules.pop(module_path, None)
def test_mcp_import_surface_modules_expose_callable_run(import_probe) -> None:
offenders: list[str] = []
for module_name in PACKAGE_RUN_MODULES:
module_path = "sprite_gen.gen" if module_name == "gen" else qualified(module_name)
try:
module = import_probe(module_path)
except Exception as exc: # one broken module must not hide the rest
offenders.append(f"{module_path} (import failed: {type(exc).__name__}: {exc})")
continue
if not callable(getattr(module, "run", None)):
offenders.append(f"{module_path} (no callable run)")
assert not offenders, "every MCP import-surface module must import and expose a callable run:\n" + \
"\n".join(offenders)
def _sibling_module_names() -> set[str]:
modules = {path.stem for path in PACKAGE_DIR.glob("*.py")}
modules |= {path.name for path in PACKAGE_DIR.iterdir() if (path / "__init__.py").is_file()}
return modules - {"__init__"}
def _bare_sibling_imports(path: Path, siblings: set[str]) -> list[tuple[int, str]]:
"""Imports of a sibling module by bare name, at any nesting depth.
Names that also exist in the stdlib (`inspect`) are left alone: inside the package an
absolute `import inspect` reaches the stdlib, which is what the caller means.
"""
hits = []
for node in ast.walk(ast.parse(path.read_text(encoding="utf-8"))):
if isinstance(node, ast.Import):
names = [alias.name for alias in node.names]
elif isinstance(node, ast.ImportFrom) and node.level == 0:
names = [node.module or ""]
else:
continue
for name in names:
root = name.split(".")[0]
if root in siblings and root not in sys.stdlib_module_names:
hits.append((node.lineno, name))
return hits
def test_package_modules_import_siblings_by_package_path() -> None:
"""`from sprite_gen.curate.curation import …`, never `from curation import …`.
A bare sibling import only resolves when `scripts/` happens to be on `sys.path`, so it
survives `python scripts/<tool>.py` and dies under `python -m sprite_gen.<tool>` or any
downstream importer. The lazy ones die at request time, not import time — the curation
webview served its SPA and 500'd on `/api/run` with `No module named 'extract'`.
"""
siblings = _sibling_module_names()
offenders = {
str(path.relative_to(ROOT)): _bare_sibling_imports(path, siblings)
for path in sorted(PACKAGE_DIR.rglob("*.py"))
if _bare_sibling_imports(path, siblings)
}
assert not offenders, f"bare sibling imports inside the package: {offenders}"
def test_scripts_wrappers_reexport_their_package_module() -> None:
"""The `scripts/*.py` call path documented in the READMEs keeps working after a module
moves into the package: the wrapper re-exports the implementation, entrypoints included."""
probe = (
"import runpy, sys;"
f"m = runpy.run_path({str(ROOT / 'scripts' / 'serve_curation.py')!r});"
"sys.exit(0 if callable(m.get('main')) and callable(m.get('build_run_state')) else 1)"
)
proc = subprocess.run([sys.executable, "-c", probe], cwd=ROOT, capture_output=True, encoding="utf-8")
assert proc.returncode == 0, f"scripts/serve_curation.py stopped re-exporting the impl:\n{proc.stderr}"
# That the wrapper also runs the entrypoint (`python scripts/serve_curation.py` is a
# documented launch command) is held by the wrapper leg of
# test_curation_cli_entrypoint.py::test_every_launch_form_exposes_the_same_flags.