Skip to content

v1.4.0

Latest
Latest

Choose a tag to compare

View all tags
@ehinman ehinman released this 02 Oct 19:39
· 11 commits to main since this release
v1.4.0
d633fb7
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

v1.4.0 keeps the package current with the USGS Water Data APIs and corrects several places where the data you received was not faithful to the data the services sent.

The Water Data getters now request v1 of the Water Data APIs. If you need time before moving, WaterdataConfiguration(api_version="v0") pins the previous version, which stays online until June 2027.

Five fixes restore values the package was changing or dropping without telling you:

  • Code and identifier columns keep their leading zeros in every delimited response, so parameter code 00060 stays 00060.
  • Numeric columns are always float64. They used to switch to int64 whenever a response happened to hold only whole numbers, so the same column changed type between calls.
  • A value that cannot be parsed still becomes NaN or NaT, but now also warns, naming the column and how many values were affected. A parse failure is no longer indistinguishable from missing data.
  • Historical peaks whose dates are only partly known are kept rather than discarded.
  • The qualifier filter is sent as the JSON array the service expects. It previously returned HTTP 400 for every value.

Error messages also come from one place now. dataretrieval._validation holds the wording for each check that recurs across services, so a rejected call names the parameter you passed and the action that fixes it. In the same vein, get_nearest_continuous refuses missing or unusable targets and window values before sending anything, instead of building a filter the service cannot answer.

Smaller additions: the state filter accepts the five US territories, waterdata.get_cql takes a max_rows cap, and waterdata.get_continuous documents method_category, a column USGS added in September 2026.

What may change for you

These corrections change column types and error classes, so a few calls behave differently:

  • Code columns now hold strings, including USGSpcode, huc_cd, state_cd, and the HUC and FIPS fields. Comparing one against a number matches nothing instead of raising, so compare against the padded string (== "00060") or convert with .astype(int).
  • Peaks queries return more rows, and datetime may be NaT. Filter on peak_dt if you select on dates.
  • The deprecated nwis query entry points raise ValueError rather than TypeError for a missing major filter, an incomplete bounding box, or an unknown service. The text of the shared rejection messages has also changed.
  • waterdata.get_time_series_metadata() no longer returns begin_utc, end_utc, state_name, or hydrologic_unit_code. Passing any of them warns and sends the call to v0. Use begin, end, and get_combined_metadata() instead.

Behavior changes

  • Request v1 of the Water Data APIs, pinnable through api_version; get_time_series_metadata drops the v0-only fields and get_field_measurements returns time as a date by @thodson-usgs in #422
  • Keep numeric columns float64 across calls, and warn, naming the column and count, when a value cannot be parsed by @thodson-usgs in #429
  • Keep leading zeros in every code column, not only Samples; these columns now hold strings by @thodson-usgs in #420
  • Keep censored peaks instead of dropping or dating them; peaks queries return more rows, datetime may be NaT, and peak_dt is retained by @thodson-usgs in #395
  • Centralize argument checks on one vocabulary; the deprecated nwis query entry points now raise ValueError rather than TypeError, and shared rejection text changes by @thodson-usgs in #387
  • Reject missing and unusable get_nearest_continuous inputs before any request, rather than sending nan bounds or inverting the window by @qorud02 in #431

New features

  • WaterdataConfiguration(api_version=...) to pin the Water Data API version while moving from v0 to v1 by @thodson-usgs in #422
  • Document method_category on waterdata.get_continuous, the RLMS method category code USGS added in September 2026 by @thodson-usgs in #423
  • Accept the five US territories in the state filter across waterdata, ngwmn, and nwdc; add waterdata.get_cql(..., max_rows=N) by @thodson-usgs in #387

Bug fixes

  • Send the qualifier filter as a JSON array, so it stops returning HTTP 400 for every value by @thodson-usgs in #427
  • Name the Virgin Islands as the services do, so state="VI" returns rows instead of none by @thodson-usgs in #432
  • Handle an empty peaks response instead of raising KeyError('peak_dt') by @arpitjain099 in #344
  • Preserve Samples CSV identifiers through shared parsing by @tevinch in #419
  • Preserve the get_nearest_continuous result shape across a resume by @thodson-usgs in #384
  • Fix WQX3 array parameter serialization and iterable WQP filters by @thodson-usgs in #390
  • Fix iterable filters for combined metadata by @thodson-usgs in #393
  • Write ratings as UTF-8 off the event loop, so a non-UTF-8 locale no longer silently drops a rating and a multi-location pull no longer stalls by @thodson-usgs in #398

Deprecations and removals

  • Remove dataretrieval.ogc.retry and deprecate dataretrieval.ogc.interruptions; import exceptions from dataretrieval or dataretrieval.interruptions by @thodson-usgs in #391
  • Deprecate begin_utc, end_utc, state, state_name, and hydrologic_unit_code on get_time_series_metadata, removable on or after 2027-06-01 by @thodson-usgs in #422

Internals, docs, and CI

  • Refactor functions to cyclomatic complexity 10 or below and ratchet the complexipy gate by @thodson-usgs in #385
  • Simplify the WQP module so the get_* and what_* getters share internal functions by @ehinman in #394
  • Select the ruff checks no other gate covers, and pin the linter by @thodson-usgs in #398
  • Check documented properties columns against each collection's /schema in the live run by @thodson-usgs in #424
  • Use one word per concept in the configuration chain by @thodson-usgs in #400
  • Separate the terms we own from the terms the services own, and use the glossary's terms for collections and locations by @thodson-usgs in #405, #402
  • Record each explanation once, in the venue that owns it, with copy edits across the ADRs, guides, glossary, docstrings, comments, and tests by @thodson-usgs in #396, #417, #418
  • Catch doubled words in pre-commit by @thodson-usgs in #404
  • Add the Water Data for the Nation survey link to NEWS by @ehinman in #401

New contributors

Full changelog: v1.3.0...v1.4.0

Release notes drafted using Claude Opus 5

Contributors

arpitjain099, thodson-usgs, and 3 other contributors
Assets 2
Loading