docs: use the glossary's terms for collections and locations - #402
Merged
Conversation
This was referenced Sep 1, 2026
thodson-usgs
force-pushed
the
chore/glossary-terms
branch
2 times, most recently
from
September 1, 2026 21:32
2a6b32d to
a6b8e99
Compare
Prose in the non-deprecated modules now says *collection* where it meant one of a service's named sets of records, and *monitoring location* where it meant a place measurements are recorded. The parameters are untouched -- `site_type=`, `site_type_code=` and `sites_df` are the services' own vocabulary and stay as they are. Legacy NWIS is deliberately excluded. Its `service=` parameter names a collection, but it is frozen public surface on a module being retired, and its docstrings keep that word rather than describing a parameter in a term the module itself never uses. `CONTEXT.md` records the carve-out. NEWS entries are left alone for the same reason: both of the ones this touched are about deprecated NWIS, and shipped release notes are a historical record rather than prose to bring into line. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JAEQqs7XzQHGQQi2KakuXD
thodson-usgs
force-pushed
the
chore/glossary-terms
branch
from
September 2, 2026 01:16
a6b8e99 to
edcc533
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
A glossary pass over the package, scoped to the modules that are not
deprecated. Prose says collection where it meant one of a service's named
sets of records, and monitoring location where it meant a place measurements
are recorded.
Parameters are untouched throughout.
site_type=,site_type_code=and thesites_dfexample variable are the services' own vocabulary and stay as theyare — that is the anti-corruption boundary working, not drift.
What changed
waterdata/—measurements,metadata,ratings,samples,time_series: docstring prose and example comments.ogc/planning.py— shared OGC machinery serves both Water Data and NGWMN, sonothing in it is about one service's spelling.
wqp.py—_query_wqp's docstring and the moduletodo. WQP's profiles(
Result,Station,Activity) are collections; the reference toservices_wqx3now notes that the name itself is legacy.CONTEXT.md— one Known legacy names bullet, below.Legacy NWIS is deliberately excluded
service=on the NWIS getters does name a collection. It is also frozen publicsurface on a module being retired, so the parameter keeps its name and its
docstrings keep the same word — describing a parameter in a term the module
itself never uses helps nobody, and the module is not where new vocabulary
should be landing. The
CONTEXT.mdbullet records that scope.NEWS.mdis left alone for the same reason. The two entries this originallytouched are both about deprecated NWIS, and shipped release notes are a
historical record rather than prose to bring into line.
Prose only
No executable code changed, verified by comparing the AST of every touched
module against
upstream/mainwith docstrings stripped:1139 tests pass,
ruff format --checkclean.Deferred, with a home
wqp.services_wqx3/wqp.services_legacyhold collection names and arepublic. Tracked in Glossary violations across the package: full inventory for planning #406 §3 — it needs an ADR 0012 deprecation cycle, not a
prose PR.
censored→ partly dated wording innwis.py, its tests, and the08/27 NEWS entry. A genuine terminology problem (in water data a censored
value is one outside a detection limit — a meaning this package ships in
wqp.what_detection_limits), but it is confined to deprecated NWIS and itsrelease notes, so it is out of scope here. Worth its own small PR if wanted.
UserWarningraised in the first draft of this PR is fixed infix(nwis): name the peak date format instead of making pandas guess #403.
Relationship to the other open PRs
Based directly on
main. Touches no file #396 or #400 touches exceptCONTEXT.md.#405 overlaps here. It restructures Known legacy names and, under ADR
0013, moves domain terms at an adapter's surface out of that section and into
the term's own entry — where NWIS's
service=is already named. Whichevermerges second should fold this bullet into the Collection entry rather than
keep both.
🤖 Generated with Claude Code
https://claude.ai/code/session_01JAEQqs7XzQHGQQi2KakuXD