Repository navigation
Check Water Data docstrings against the service's queryables (#379) - #453
Open
acalebratliff wants to merge 25 commits into
Open
acalebratliff wants to merge 25 commits into
acalebratliff wants to merge 25 commits into
Conversation
…that reports drift
…_nearest_continuous
… disappeared queryable
…s description is empty
…text, without Markdown or RST markup The service writes its descriptions in Markdown and the docstrings are reStructuredText. One normalizer now reduces both to plain text before the containment check: literals, emphasis and roles keep their contents, a link becomes its text and its URL (the URL once when they are the same), and bullets become plain lines. The snapshot keeps the service's raw text, so a markup change still shows as drift.
…ervice's words Each queryable argument of get_daily, get_continuous, get_latest_daily and get_latest_continuous now carries the service's description, written in reStructuredText. Package notes that the service text lacks (the two-value date list, exact qualifier matching, statistic 00011 for continuous data, the method category codes) follow it.
…ervice's words get_channel, get_field_measurements and get_peaks now carry the service's description for each queryable argument. get_peaks' shared water_year, year, month and day entry becomes one entry each, since the service describes them separately.
…ice's words get_monitoring_locations, get_time_series_metadata and get_field_measurements_metadata now carry the service's description for each queryable argument. The longer hand-written explanations of hydrologic unit codes and aquifer types stay after it; get_field_measurements_metadata's shared begin, end and last_modified entry becomes one entry each.
…eter arguments in the service's words
… service's words Each queryable argument now carries the service's description, including the location-catalog arguments the docstring previously left to get_monitoring_locations. With every getter swept, the docstring check passes, so its expected-failure marker is removed and it blocks a merge.
… a role's ~ CONTRIBUTING now states the rule in two sentences and leaves the list of markup rules to the test module. The normalizer drops the leading ~ of a role such as :mod:`~a.b`, and the test module uses American spelling (normalize, emphasized, color) like the rest of the codebase.
…wording get_monitoring_locations' aquifer_type_code note now keeps only what the service text lacks: the artesian name, the well-level fact and the link. get_combined_metadata's intro no longer points to get_monitoring_locations, since every argument is described below. get_channel's channel_flow keeps its "flow in the channel" wording.
Collaborator
|
@acalebratliff, sorry for the slow response. The PR is more-or-less acceptable, what's given me pause is that we alter several of the API docstrings where |
Author
|
Thanks. I see it: the sweep replaced your rewrites with the service's words, including places where dataretrieval behaves differently (the two-value lists, the date grammar, the deprecated arguments). I can change the check so a getter can mark an argument as altered, with a reason; those keep your text, must still name the queryable, and show up in the drift report, so the gate stays for everything else. If that shape works for you I'll make it on this PR and restore your wording where it was lost; if you'd rather think first, I'll wait. |
This branch has not been deployed
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
2 participants
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.
Closes #379.
The committed queryables snapshot now holds each queryable's type, title and description. An offline test checks that every typed argument of every Water Data getter contains the service's description, after both texts are reduced to plain text (Markdown on the service side, RST on ours; a link becomes its text plus URL, once when equal). The snapshot keeps the raw text, so a wording change at the service still shows as drift.
python -m tests.waterdata_queryables_testrefreshes the snapshot and reports what appeared, disappeared or changed;--checkonly reports. The weekly advisory workflow compares the snapshot with the live service and writes the result to the run summary.The docstring edits are in their own commits, one per module, after the check. 168 descriptions across 12 getters now carry the service's words; hand-written notes stay as their own paragraph.
Two things to look at:
get_combined_metadatadocumented a few location arguments and pointed toget_monitoring_locations. The check needs every typed argument, so it now lists all of them. If you would rather keep the cross-reference, that getter can be exempted; say the word.end"; "In some case," (district_code); "or traps the water" (contributing_drainage_area); "does not necessarily indicate anything about the measurement has changed" (last_modified); "meaining" (approval_status); a stray "[" in county_name; "A list of codes is available at" repeated from the code fields in vertical_datum_name, horizontal_positional_accuracy, horizontal_position_method_name, original_horizontal_datum_name and site_type; and begin/end on combined-metadata and field-measurements-metadata refer to begin_utc/end_utc, which those collections do not have. They could be reported to the service team.Gates: ruff, mypy, pytest (coverage 99.08 %), xenon, complexipy, lint-imports; a Sphinx build of the reference page shows no new warnings.
Written with AI tools, reviewed and tested by me.