Skip to content

Make babel_validation a top-level import, switch to ruff, and keep NameRes /lookup and /bulk-lookup results in separate caches - #106

Open
gaurav wants to merge 24 commits into
mainfrom
split/2-top-level-package
Open

gaurav wants to merge 24 commits into
mainfrom
split/2-top-level-package

Conversation

@gaurav

@gaurav gaurav commented Jun 26, 2026 •

Copy link
Copy Markdown
Collaborator

The library under src/babel_validation/ could only be imported as src.babel_validation, which works from the repository root and nowhere else, so nothing outside this repo could use it. This PR packages it as a top-level babel_validation, rewrites every import, python -m call and doc to match, replaces black with ruff (Babel's settings, checked on every PR), and adds offline tests for the two parts of the library that fail quietly: the NodeNorm/NameRes caches and the Google Sheet parsing.

It also fixes a bug in CachedNameRes, which let a /bulk-lookup result answer a later /lookup and vice versa, though the two endpoints do not answer the same parameters the same way. The NameRes cache is now kept per endpoint.

The whole tree is now ruff-clean. Read it commit by commit: the format sweeps are isolated in efb3e01 (the tree this branch started from) and ef58694 (code main added since), so they can be skipped.

The calls worth overruling

  • ruff replaces black, with Babel's settings (line length 120; E, F, I, UP; E501 ignored) so the two repos format alike, plus one rule of our own (below). The lint job sits in main's existing tests.yaml, beside the unit tests, rather than in a second workflow. ruff is a dev dependency, so the wheel does not pull it in.
  • pytest gets pythonpath = ["src"], so the suite imports from the source tree whatever is installed. Without it, any venv with an editable install from before the wheel was narrowed failed collection until uv sync was re-run. The reason is beside the setting.
  • A stray src.babel_validation import is caught by ruff, not by pytest. tests/__init__.py puts the repository root on sys.path, where src/ is a namespace package, so such an import still passes under pytest while loading a second copy of every module and its caches. ruff's TID251 bans src in every import form. The alternative, importmode = importlib, would close it in pytest too but changes collection suite-wide.
  • CachedNameRes caches /lookup and /bulk-lookup separately. They name the type filter differently (biolink_type against biolink_types, each ignoring the other's name), and /lookup rejects a too-short query with a 422 where /bulk-lookup returns [], so a shared cache could return unfiltered hits, or [] in place of an error. Nothing relied on one endpoint warming the other: assertions/nameres.py, the only caller, uses lookup() alone. The module docstring says why they must stay apart. A string missing from a /bulk-lookup response is now retried rather than cached as None.
  • CI does not run pytest --collect-only. Collection downloads the Google Sheet, whose ID is now a repository secret, so the step would fail without it, and on fork PRs even with it. A broken import in a live-only test module is therefore caught only by a live run.

What's here

  • Packaging: the wheel packages src/babel_validation instead of all of src/; src/__init__.py is gone; the imports in about fifty files, the dashboard workflow's python -m calls and the agent docs use babel_validation.
  • Linting: ruff in place of black in pyproject.toml, uv.lock and tests.yaml; its findings fixed across the tree, including a few dead locals (input_results in test_nodenorm_229, source_info in test_nodenorm_from_gsheet, first_biolink_type in test_nodenorm_types).
  • Tests: about forty-five offline tests in tests/unit/test_service_caching.py (the cache-warming pattern the module docstrings promise, params in the cache key, cached negative results, invalidation, and the NameRes endpoints kept apart) and tests/unit/test_gsheet_parsing.py (the sheet's column headings, strict-xfail marking, and that a blank row does not renumber the rows after it).
  • Docs: AGENTS.md and the README give the ruff commands, note that -m unit and --category "Unit Tests" are unrelated despite the names, and say that the unit marker, not the tests/unit directory, is what puts a test in the offline subset.

Verification

On dc16d7c: ruff check . and ruff format --check . are clean, uv sync --frozen succeeds, no src.babel_validation import remains, and all 340-odd unit tests pass with HTTPS_PROXY pointed at a dead port. All 4,800-odd tests collect, including in a venv holding every dependency but not the project itself, where import babel_validation alone fails. The new NameRes tests fail against the previous cache code.

Before merging

  • pytest --target dev -x — smoke-test against the dev environment

🤖 Generated with Claude Code

Change pyproject.toml to package src/babel_validation directly so
babel_validation is importable as a top-level name after install.
Update all test imports from src.babel_validation.* to babel_validation.*.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Base automatically changed from split/1-library-reorg to main June 26, 2026 18:26

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

gaurav and others added 7 commits August 18, 2026 15:31
…stall

Moving the wheel target from `packages = ["src"]` to
`packages = ["src/babel_validation"]` meant `babel_validation` was only
importable via the installed distribution. Anyone with a venv built
before that change -- or following the bare `pytest --target dev` in
README.md and CLAUDE.md -- hit `ModuleNotFoundError: No module named
'babel_validation'` at collection until they re-ran `uv sync`.

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

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nothing imports `src.*` any more, but the file still marked `src` as a
package, so editors and linters kept offering `src.babel_validation` as
a completion -- and such an import resolves to a second, distinct module
object with its own caches rather than failing loudly.

Deleting it does not fully close that path (PEP 420 namespace packages
keep `src.` importable while the repo root is on sys.path, which the
root conftest.py guarantees under pytest's default prepend import mode),
but it removes the marker that invites the mistake.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Settings are copied from NCATSTranslator/Babel so the two repositories
lint identically: line-length 120, `E`/`F`/`I`/`UP` selected, `E501`
ignored because `ruff format` already owns wrapping.

ruff format supersedes black rather than joining it -- two formatters
with different opinions produce a diff every time whichever one ran last
disagrees with the other, so black is dropped from the dependencies and
from CLAUDE.md.

Also registers the `unit` marker, again matching Babel's wording. Every
test in this repository currently talks to a live service or downloads
the Google Sheet, so `pytest -m unit` is empty today; the following
commits give it something to run and wire it up to CI.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nineteen were mechanical and applied with `ruff check --fix`: import
blocks sorted into stdlib/third-party/first-party groups (I001), the
eight `Optional[str]` annotations in BlocklistEntry rewritten as
`str | None` now that the floor is Python 3.11 (UP045), and one f-string
with no placeholders (F541).

The remaining three were dead locals (F841). `input_results`,
`source_info` (with the `source`/`source_url` reads that fed only it),
and `first_biolink_type` were each assigned and never read, so removing
them changes no behaviour -- but `source_info` and `first_biolink_type`
sit next to assertions that could reasonably have used them, so they may
be worth reinstating deliberately rather than by accident.

log-analysis/ is excluded: those are exploratory notebooks, and one cell
does not parse, so linting them would gate CI on scratch work.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Mechanical only: `uv run ruff format .` over the repository, no
behavioural changes. Isolated in its own commit so the substantive
commits on either side stay readable.

19 files were reformatted. Most of the diff is the two quote styles
(ruff format normalises to double quotes, as black does) and long
argument lists exploded one-per-line.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Until now every test in this repository needed a live NodeNorm, NameRes,
or Google Sheet, so a pull request could not be checked at all without
network access -- and `babel_validation.services` had no tests whatsoever,
despite being the part other repositories are meant to import.

Two areas are covered, chosen because both fail quietly:

- CachedNodeNorm/CachedNameRes caching. A cache that stops caching makes
  a run slower rather than failing it, so nothing would report it. The
  tests pin the cache-warming pattern the module docstrings promise, that
  params are part of the cache key, that negative results are cached, and
  that invalidation clears 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. The tests pin the column headings, the strict xfail
  marking, and that dropping a blank row does not renumber the rows after
  it.

One test documents rather than endorses: lookup() and bulk_lookup() share
a single cache namespace keyed on (query, params), so a lookup() result
is served to a later bulk_lookup(). That is harmless today only because
NameRes returns a list of hits from /lookup and one such list per string
from /bulk-lookup -- a coincidence the module docstring does not mention,
and the test fails if it ever stops holding.

deselected_by_markexpr is covered too, 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.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two jobs, following NCATSTranslator/Babel's workflow: `ruff check` plus
`ruff format --check`, and `pytest -m unit`. Neither needs a NodeNorm or
NameRes deployment, so both are safe to run on every PR -- the existing
service tests stay a manual `pytest --target dev`, since they fail on
upstream outages rather than on the change under review.

The unit job also runs `pytest --collect-only` first. That does need the
network, but it is the only check that exercises the pytest_generate_tests
hooks in the gsheet modules, where an import error or a broken
parametrize would otherwise surface only at the start of a live run.

README.md and CLAUDE.md document the split, including the trap that
`-m unit` and `--category "Unit Tests"` are unrelated: the marker selects
tests/unit/, while the category selects Google Sheet rows that still call
a live service.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@gaurav gaurav changed the title Make babel_validation a top-level import (drop src. prefix) Make babel_validation a top-level import; add ruff and offline unit tests to CI Aug 18, 2026
The two methods key the cache on (query, params) with no record of which
endpoint produced an entry, so either can serve the other with no HTTP
call. That is deliberate and correct: for equal parameters the 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 said so, and the module docstring pointed the other way by
describing the endpoints as having "different response shapes" -- true of
the return types (a mapping against a bare list), but not of the hits
themselves, which is what the cache stores. Reworded to separate the two,
and the caching model now states the premise the shared keyspace rests on.

No behaviour change; the existing test that pins the shared cache is
reframed to match.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
gaurav and others added 8 commits November 11, 2026 02:28
main has moved on 260 commits since this branch was cut, including #159
(CLAUDE.md renamed to AGENTS.md) and #160.

Conflicts:
- CLAUDE.md: kept deleted, as on main. This branch's edits to it (ruff in
  place of black, the -m unit note, babel_validation imports) are carried
  into AGENTS.md in the commits after this merge.
- pyproject.toml: this branch's ruff dependency and settings, pythonpath and
  marker comment; main's pyyaml. black stays dropped.
- Ten source and test files: main's side. This branch changed them only by the
  src. prefix rename, ruff's lint fixes and the ruff format sweep, all
  mechanical, so they are re-applied over the whole tree in the commits after
  this one rather than hand-merged here. main already had
  deselected_by_markexpr, which this branch also used.

tests/unit/test_gsheet_parsing.py stubbed requests.get inside
google_sheet_test_cases, which main replaced with fetch_sheet_csv(): the
fixture now stubs that instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This branch made babel_validation a top-level import, but main had added about
forty files since that still imported src.babel_validation. They worked only
from the repository root: run from anywhere else, as an installed package is,
`import babel_validation.tools.generate_report` failed with "No module named
'src'". Every module path is rewritten, including the dashboard workflow's
`python -m` calls, the agent instructions and the generated assertions README.
File paths (src/babel_validation/...) are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The same kinds of fix as this branch's earlier ruff commit, now over the code
main added: sorted imports, PEP 604 Optionals, collections.abc imports, two
unused imports, and two unused variables (input_results in test_nodenorm_229,
source_info in test_nodenorm_from_gsheet) that this branch had removed and the
merge brought back from main. The handler imports at the foot of
assertions/__init__.py were reordered; harmless, as ASSERTION_HANDLERS lists
its handlers explicitly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`ruff format`, unchanged settings, over the files main added or reformatted
with black after this branch's own sweep. Formatting only; `ruff check` and
`ruff format --check` are now clean across the tree.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Carries over this branch's edits to CLAUDE.md, which main renamed to AGENTS.md:
the ruff commands in place of black, `pytest -m unit` in the command list, the
note that it is unrelated to --category "Unit Tests", and tests/unit/ in the
list of test modules. The caveat that the tree was not black-clean, and the
list of single-quoted files not to run black on, are gone: CI now checks that
the whole tree is ruff-clean, so formatting a file never touches lines you did
not change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This branch added test.yml and main added tests.yaml, both named "Tests" and
both running `pytest -m unit` on every pull request. tests.yaml now has this
branch's ruff job and triggers (also on pushes to main, and by hand), and
test.yml is gone.

Two steps of test.yml were not carried over:
- `pytest --collect-only`: collection now downloads the Google Sheet, whose
  ID main moved into the BABEL_VALIDATION_SHEET_ID secret, so the step would
  fail on every run without it, and on fork PRs even with it.
- `uv sync --frozen`: `uv run` already syncs from the lockfile.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
It looks redundant beside an installed package, but narrowing the wheel to
src/babel_validation left editable installs made before that pointing at the
repository root, and collection then failed until `uv sync` was re-run. The
reason was only in #106's description.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…r pytest

tests/__init__.py makes pytest put the repository root on sys.path, where src/
is a namespace package, so a test importing src.babel_validation passes while
the same import fails everywhere else. About forty files added on main after
this branch was cut did exactly that, and nothing caught it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gaurav gaurav changed the title Make babel_validation a top-level import; add ruff and offline unit tests to CI Make babel_validation a top-level import, replace black with ruff, and add offline tests for the caches and sheet parsing Nov 11, 2026
gaurav and others added 2 commits November 11, 2026 11:53
lookup() and bulk_lookup() shared one keyspace, keyed on (query, params),
on the premise that the two endpoints answer equal parameters with equal
hits. The NameRes source (api/server.py, 2026-11) says otherwise:

- /lookup filters on `biolink_type`, /bulk-lookup on `biolink_types`, and
  each silently ignores the other's name. So
  bulk_lookup(["diabetes"], biolink_type="biolink:Disease") cached
  unfiltered hits, which a later lookup() with the same arguments returned
  without asking /lookup, which would have filtered them.
- /lookup rejects a too-short query with a 422; /bulk-lookup returns [].
  A bulk-cached [] hid the error lookup() should raise.

The cache key now starts with the endpoint. Nothing outside the unit
tests relied on one endpoint warming the other: the only caller,
assertions/nameres.py, uses lookup() alone.

The test that pinned the shared keyspace claimed it would fail "if NameRes
ever makes them disagree", which an offline test replaying one payload
cannot do. Its replacement checks the separation, in both directions, and
says what it cannot see. test_invalidate_query_clears_both_endpoints now
fills the cache through both endpoints, which it never did before, and the
module docstring no longer claims these are the only tests that use
babel_validation.services.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
bulk_lookup() stored result.get(query, None) for every string it sent, so
a string missing from the response was cached as None and handed back on
every later call, to callers expecting a list of hits. Now it is left out
of both the result and the cache, with a warning, and the next call asks
for it again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
gaurav and others added 4 commits November 11, 2026 11:53
AGENTS.md warned against the src. form, but only in prose. It still
passes under pytest, loading a second copy of each module with its own
from_url() singletons and caches, so nothing would catch it. TID251 with
"src" in banned-api flags `from src.babel_validation.x import y`,
`import src.babel_validation.x` and `from src import ...` alike, and the
lint job in tests.yaml already runs ruff check on every PR.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ruff was in [project] dependencies, as black was before it, so anyone
installing the babel_validation wheel also got the ruff binary. It is
only for working on this repository. `uv sync` and `uv run` install the
dev group by default, and ruff-action still finds ruff's version in
uv.lock, which records the group.

uv lock also bumped the lockfile's revision from 3 to 5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…line tests

The README said the offline subset was the tests in tests/unit, but
`pytest -m unit` also runs tests/github_issues/unit, tests/test_cache_dir.py
and tests/test_environment/test_assertions*.py. A contributor believing the
directory decides would leave a new offline test elsewhere unmarked, and CI
would never run it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The lint job was added on @v7 while unit-tests, website-tests and
dashboard.yaml all use @v4, so one workflow tracked two major versions.
Moving every job to v7 is a separate change, best made across both
workflows at once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gaurav gaurav changed the title Make babel_validation a top-level import, replace black with ruff, and add offline tests for the caches and sheet parsing Make babel_validation a top-level import, switch to ruff, and keep NameRes /lookup and /bulk-lookup results in separate caches Nov 11, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants