Make babel_validation a top-level import; add ruff and offline unit tests to CI

[gaurav]

Summary

Started as the src. prefix removal; grew a CI story, because the packaging change exposed that this repository had no automated checks at all.

Packaging

• pyproject.toml packages src/babel_validation directly instead of the whole src/ directory, so babel_validation is a proper top-level package after install
• All 4 test-file imports move from from src.babel_validation.X import Y to from babel_validation.X import Y
• pythonpath = ["src"] under [tool.pytest.ini_options], so the suite imports from the source tree rather than depending on install state
• The now-dead src/__init__.py is deleted

Linting

• ruff replaces black, with Babel's settings: line-length 120, E/F/I/UP, E501 ignored
• The 22 issues ruff check reported are fixed, and ruff format is applied repo-wide

Testing

• tests/unit/ — 43 offline tests for src/babel_validation/, marked @pytest.mark.unit
• .github/workflows/test.yml runs ruff check, ruff format --check, and pytest -m unit on every PR

Docs

• README.md and CLAUDE.md cover the offline/live split, how to mark a new test, and the ruff commands
• CachedNameRes's docstring records why lookup() and bulk_lookup() may share one cache (see below)

Read commit by commit; the ruff format sweep is isolated in efb3e01 so it can be skipped or dropped.

Why pythonpath

Narrowing the wheel target to src/babel_validation also narrows what an editable install puts on sys.path. Before this PR, from src.babel_validation… resolved off the repo root that pytest prepends during collection, so the suite ran with no install at all. Afterwards it resolves only through the installed distribution — and any venv built from the old packages = ["src"] still points its .pth at the repo root, so pytest fails collection with ModuleNotFoundError: No module named 'babel_validation' until uv sync is re-run. That would have hit every existing contributor venv, plus anyone following the bare pytest --target dev in README.md and CLAUDE.md.

pythonpath = ["src"] (built into pytest ≥ 7, no plugin) puts the source tree on sys.path during collection, so the suite no longer depends on install state either way.

What the unit tests cover, and why those things

Every test here needed a live NodeNorm, NameRes, or Google Sheet, so a PR could not be checked without network access — and babel_validation.services had no tests at all, despite being the part other repositories are meant to import. Both areas covered were chosen because they fail quietly:

• CachedNodeNorm / CachedNameRes caching. A cache that stops caching makes a run slower rather than failing it, so nothing reports it. Pinned: the cache-warming pattern the module docstrings promise, params being part of the cache key, negative results being cached, and invalidation clearing every params variant of one query without flushing the rest.
• TestRow.from_data_row and GoogleSheetTestCases.test_rows. A renamed sheet column yields an empty string rather than an error, and a numbering slip yields a test ID pointing a maintainer at the wrong line of the sheet. Pinned: the column headings, the strict-xfail marking, and that dropping a blank row does not renumber the rows after it.
• deselected_by_markexpr, since it is what keeps pytest -m unit from downloading the Google Sheet during collection.

Verified offline — with HTTPS_PROXY pointed at a dead port, pytest -m unit passes 43 tests in 0.28s.

A note on the NameRes cache

CachedNameRes.lookup() and bulk_lookup() share a single cache namespace keyed on (query, params), with no record of which endpoint produced the entry. So a lookup() result is handed straight back to a later bulk_lookup() for the same query, with no request made:

nr.lookup("diabetes")            # -> [{'curie': 'MONDO:1'}]
nr.bulk_lookup(["diabetes"])     # -> {'diabetes': [{'curie': 'MONDO:1'}]}, no HTTP call

That is intended and correct: given the same parameters the two endpoints are interchangeable, since /lookup returns a list of hits and /bulk-lookup returns that same list under the string it was asked about. Nothing recorded it, though, and the module docstring pointed the other way by calling the endpoints "different response shapes" — true of the return types, not of the hits the cache stores. The docstring now states the premise the shared keyspace rests on, and test_lookup_and_bulk_lookup_share_one_cache_namespace fails if NameRes ever makes the endpoints disagree.

Notes

• -m unit and --category "Unit Tests" are unrelated despite the names. The marker selects tests/unit/; the category selects Google Sheet rows that still call a live service. Documented in CLAUDE.md.
• Deleting src/__init__.py does not fully close the shadow-import path: src/ is still a directory, so PEP 420 namespace packages keep import src.babel_validation… resolving while the repo root is on sys.path, which the root conftest.py guarantees. Closing it entirely needs importmode = importlib, which changes collection semantics suite-wide — not worth it for a hazard that only fires on a hand-written src.-prefixed import.
• log-analysis/ is excluded from ruff: those are exploratory notebooks, and one cell does not parse.
• Three dead locals were removed for F841. source_info and first_biolink_type sit next to assertions that could reasonably have used them, so they may be worth reinstating deliberately.

Test plan

• pytest --collect-only against a venv with a stale editable .pth (no uv sync) — 4485 tests collected, previously ModuleNotFoundError
• pytest -m unit with all network blocked — 43 passed, 25 deselected, 0.28s
• uv sync --frozen, ruff check ., ruff format --check . — all clean
• grep for src.babel_validation — no imports remain; only filesystem paths in CLAUDE.md
• pytest --target dev -x — smoke-test against dev environment

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Makes babel_validation a conventional top-level installed package.

Changes:

• Updates Hatchling packaging configuration.
• Migrates four test imports away from the src. prefix.
• Updates contributor documentation.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
pyproject.toml	Packages src/babel_validation directly.
tests/test_environment/test_env.py	Uses the top-level package import.
tests/nodenorm/test_nodenorm_from_gsheet.py	Updates the Google Sheet import.
tests/nameres/test_nameres_from_gsheet.py	Updates the Google Sheet import.
tests/nameres/test_blocklist.py	Updates the blocklist import.
CLAUDE.md	Documents the new import convention.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.