Pynhd

-------------------

Breaking Changes
~~~~~~~~~~~~~~~~
- Set the minimum supported version of Python to 3.8 since many of the
dependencies such as ``xarray``, ``pandas``, ``rioxarray`` have dropped support
for Python 3.7.

Internal Changes
~~~~~~~~~~~~~~~~
- Use `micromamba <https://github.com/marketplace/actions/provision-with-micromamba>`__
for running tests
and use `nox <https://github.com/marketplace/actions/setup-nox>`__
for linting in CI.

-------------------

New Features
~~~~~~~~~~~~
- Add support for all the GeoConnex web service endpoints. There are two
ways to use it. For a single query, you can use the ``geoconnex`` function and
for multiple queries, it's more efficient to use the ``GeoConnex`` class.
- Add support for passing any of the supported NLDI feature sources to
the ``get_basins`` method of the ``NLDI`` class. The default is ``nwissite``
to retain backward compatibility.

Bug Fixes
~~~~~~~~~
- Set the type of "ReachCode" column to ``str`` instead of ``int`` in ``pygeoapi``
and ``nhdplus_vaa`` functions.

-------------------

New Features
~~~~~~~~~~~~
- Add two new functions called ``flowline_resample`` and ``network_resample`` for
resampling a flowline or network of flowlines based on a given spacing. This is
useful for smoothing jagged flowlines similar to those in the NHDPlus database.
- Add support for the new NLDI endpoint called "hydrolocation". The ``NLDI`` class
now has two methods for getting features by coordinates: ``feature_byloc``
and ``comid_byloc``. The ``feature_byloc`` method returns the flowline that is
associated with the closest NHDPlus feature to the given coordinates. The
``comid_byloc`` method returns a point on the closest downstream flowline to
the given coordinates.
- Add a new function called ``pygeoapi`` for calling the API in batch mode.
This function accepts the input coordinates as a ``geopandas.GeoDataFrame``.
It is more performant than calling its counteract ``PyGeoAPI`` multiple times.
It's recommended to switch to using this new batch function instead of the
``PyGeoAPI`` class. Users just need to prepare an input data frame that has
all the required service parameters as columns.
- Add a new step to ``prepare_nhdplus`` to convert ``MultiLineString`` to ``LineString``.
- Add support for the ``simplified`` flag of NLDI's ``get_basins`` function.
The default value is ``True`` to retain the old behavior.

Breaking Changes
~~~~~~~~~~~~~~~~
- Remove caching-related arguments from all functions since now they
can be set globally via three environmental variables:

* ``HYRIVER_CACHE_NAME``: Path to the caching SQLite database.
* ``HYRIVER_CACHE_EXPIRE``: Expiration time for cached requests in seconds.
* ``HYRIVER_CACHE_DISABLE``: Disable reading/writing from/to the cache file.

You can do this like so:

.. code-block:: python

import os

os.environ["HYRIVER_CACHE_NAME"] = "path/to/file.sqlite"
os.environ["HYRIVER_CACHE_EXPIRE"] = "3600"
os.environ["HYRIVER_CACHE_DISABLE"] = "true"

-------------------

New Features
~~~~~~~~~~~~
- Add a new class called ``NHD`` for accessing the latest National Hydrography Dataset.
More info regarding this data can be found
`here <https://hydro.nationalmap.gov/arcgis/rest/services/nhd/MapServer>`__.
- Add two new functions for getting cross-sections along a single flowline via
``flowline_xsection`` or throughout a network of flowlines via ``network_xsection``.
You can specify spacing and width parameters to control their location. For more
information and examples please consult the documentation.
- Add a new property to ``AGRBase`` called ``service_info`` to include some useful info
about the service including ``feature_types`` which can be handy for converting
numeric values of types to their string equivalent.

Internal Changes
~~~~~~~~~~~~~~~~
- Use the new PyGeoAPI API.
- Refactor ``prepare_nhdplus`` for improving the performance and robustness of determining
``tocomid`` within a network of NHD flowlines.
- Add empty geometries that ``NLDI.getbasins`` returns to the list of ``not found`` IDs.
This is because the NLDI service does not include non-network flowlines and instead returns
an empty geometry for these flowlines. (:issue_nhd:`48`)

-------------------

Internal Changes
~~~~~~~~~~~~~~~~
- Use the three new ``ar.retrieve_*`` functions instead of the old ``ar.retrieve``
function to improve type hinting and to make the API more consistent.
- Revert to the original PyGeoAPI base URL.

-------------------

Breaking Changes
~~~~~~~~~~~~~~~~
- Rewrite ``ScienceBase`` to make it applicable for working with other ScienceBase
items. A new function has been added for staging the Additional NHDPlus attributes items
called ``stage_nhdplus_attrs``.
- Refactor ``AGRBase`` to remove unnecessary functions and make them more general.
- Update ``PyGeoAPI`` class to conform to the new ``pygeoapi`` API. This web service
is undergoing some changes at the time of this release and the API is not stable,
might not work as expected. As soon as the web service is stable, a new version
will be released.

New Features
~~~~~~~~~~~~
- In ``WaterData.byid`` show a warning if there are any missing feature IDs that are
requested but are not available in the dataset.
- For all ``by*`` methods of ``WaterData`` throw a ``ZeroMatched`` exception if no
features are found.
- Add ``expire_after`` and ``disable_caching`` arguments to all functions that use
``async_retriever``. Set the default request caching expiration time to never expire.
You can use ``disable_caching`` if you don't want to use the cached responses. Please
refer to documentation of the functions for more details.

Internal Changes
~~~~~~~~~~~~~~~~
- Refactor ``prepare_nhdplus`` to reduce code complexity by grouping all the
NHDPlus tools as a private class.
- Modify ``AGRBase`` to reflect the latest API changes in ``pygeoogc.ArcGISRESTfull``
class.
- Refactor ``prepare_nhdplus`` by creating a private class that includes all the previously
used private functions. This will make the code more readable and easier to maintain.
- Add all the missing types so ``mypy --strict`` passes.