ADR 0005: Quarantine and retire legacy NWIS

Status

Accepted. Carried out: dataretrieval.nwis has been removed.

Amended after acceptance under ADR 0000: Record each explanation once, in the place that owns it; the Notes section records every clause added or corrected.

Context

The legacy dataretrieval.nwis facade overlaps modern Water Data APIs and contains functions backed by retired services. Existing users still require a migration window, while new code should not acquire dependencies on behavior scheduled for removal.

Decision

Keep dataretrieval.nwis importable during its published deprecation window and remove it on or after 2027-05-06 through the project’s compatibility and release process.

Add no new NWIS capabilities. Permit compatibility, security, and correctness fixes only. Every active deprecated function should warn once per user call and name a supported replacement where one exists. Modern modules must never import NWIS.

Do not treat WQP’s legacy result profiles as part of NWIS retirement; they have separate upstream constraints and migration behavior.

Consequences

  • Existing users have a predictable migration period.

  • Maintainers avoid investing in a second implementation of modern retrieval behavior.

  • Legacy integration tests may require special handling as upstream endpoints are retired.

  • Removal still requires release notes, replacement checks, and an intentional compatibility boundary.

Compliance

dataretrieval/nwis.py is a stub: importing it raises ImportError naming the Water Data replacements and the last release that includes the module (1.4.0). Attribute access after import dataretrieval, which never loads the stub, raises AttributeError with the same message from the package __getattr__. tests/contracts/removed_modules_test.py covers both.

Notes

The module was removed before the 2027-05-06 horizon, because USGS is decommissioning the waterservices endpoints it called. The Compliance section was rewritten at removal: it described the deprecation tests that verified one warning per public call and named Water Data replacements, and the nwis-quarantine contract in .importlinter. Both were removed with the module.

The Compliance sentence on attribute access was added after removal: import dataretrieval followed by dataretrieval.nwis raised a bare AttributeError that named no replacement.