Add station search to enhydris_api_client (fixes DEV-129)

CHANGELOG.rst

@@ -5,6 +5,7 @@ Changelog
 DEV
 ===
 
+* enhydris_api_client.list_stations() now accepts a query string.
 * Added textbisect module.
 * Added type hints.
 

docs/enhydris_api_client.rst

@@ -37,7 +37,7 @@ Reference
       it in subsequent requests. The method will be removed in future
       versions.
 
-   .. method:: list_stations(self)
+   .. method:: list_stations(self, query_string=None)
                get_station(self, id)
                post_station(self, data)
                put_station(self, station_id, data)
@@ -51,7 +51,8 @@ Reference
       :meth:`~EnhydrisApiClient.post_station` returns the created
       station's id. :meth:`~EnhydrisApiClient.list_stations` returns a
       generator object that in each iteration provides a dictionary with
-      the station's data.
+      the station's data; if *query_string* is specified then only stations
+      that match are returned.
 
    .. method:: list_timeseries_groups(self, station_id)
                get_timeseries_group(self, station_id, timeseries_group_id)

src/enhydris_api_client/__init__.py

@@ -4,7 +4,7 @@
 from copy import copy
 from io import StringIO
 from typing import Any, Dict, Generator, Iterable, Optional, cast
-from urllib.parse import urljoin
+from urllib.parse import quote_plus, urljoin
 from zoneinfo import ZoneInfo
 
 import iso8601
@@ -92,8 +92,12 @@ def get_token(self, username: str, password: str) -> Optional[str]:
         self.session.headers.update({"Authorization": f"token {key}"})
         return key
 
-    def list_stations(self) -> Generator[JSONDict, None, None]:
+    def list_stations(
+        self, query_string: Optional[str] = None
+    ) -> Generator[JSONDict, None, None]:
         url = urljoin(self.base_url, "api/stations/")
+        if query_string:
+            url += f"?q={quote_plus(query_string)}"
         while url:
             try:
                 self.response = self.session.get(url)

tests/enhydris_api_client/test_station.py

@@ -41,6 +41,26 @@ def test_result(self) -> None:
         )
 
 
+@mock_session(
+    **{
+        "get.return_value.json.return_value": {
+            "count": 2,
+            "next": None,
+            "previous": None,
+            "results": [{"name": "Hobbiton"}, {"name": "Rivendell"}],
+        }
+    }
+)
+class ListStationsWithQueryTestCase(TestCase):
+    def test_makes_request_with_query(self, m: MagicMock) -> None:
+        client = EnhydrisApiClient("https://mydomain.com")
+        result = client.list_stations(query_string="hello world")
+        next(result)  # Ensure the request is actually made
+        m.return_value.get.assert_called_once_with(
+            "https://mydomain.com/api/stations/?q=hello+world"
+        )
+
+
 class ListStationsMultiPageTestCase(TestCase):
     def setUp(self) -> None:  # type: ignore[misc]
         self.session_patcher = mock_session(