Allow API keys to be provided without modifying API_USGS_PAT

[davetapley]

The Water Data API client reads the API key exclusively from the API_USGS_PAT environment variable:

token = os.getenv("API_USGS_PAT")
if token:
    headers["X-Api-Key"] = token

Applications that obtain credentials from configuration files, secret stores, or dependency injection must therefore modify os.environ at runtime. Because environment variables are process‑global, this can cause problems for concurrent applications, tests, and programs that need different credentials.

Proposed API

Could the public waterdata functions accept a configured requests.Session?

with requests.Session() as session:
    session.headers["X-Api-Key"] = api_key

    data, metadata = waterdata.get_continuous(
        monitoring_location_id="USGS-...",
        session=session,
    )

An explicit convenience parameter would also be useful:

data, metadata = waterdata.get_continuous(
    monitoring_location_id="USGS-...",
    api_key=api_key,
)

The environment variable could remain as a backward‑compatible fallback.

The package’s internal _walk_pages function already accepts a requests.Session, but this capability is not exposed through get_ogc_data or the other public endpoint functions. When supporting sessions, requests may need to be prepared with session.prepare_request(request) so that session‑level headers apply to both the initial request and subsequent paginated requests.

A session‑based API would additionally enable:

• connection pooling
• custom retries
• proxies
• certificates
• test adapters

Would this approach fit the library’s intended API?

[ldecicco-USGS]

I would be against the idea of adding an explicit api_key parameter for fears that folks will see it and start writing and sharing scripts exposing their keys.

Concurrent jobs that need different credentials can modify the key like this:

import os
os.environ["API_USGS_PAT"] = "my_key"

This will not change the key in another session.

I'll leave the more general question of exposing the session to each waterdata function up to the Python crew.

[thodson-usgs]

Right, I agree we could consider other approaches. I'd need to review how other packages handle this, but I think configuration files are prefered. Then we define the fallback precedence: python variables > configs files > environment variables...or something. Will give it more thought, but not today. Thankjs @davetapley