Add label search

Add search_labels methods (sync + async) using the new /labels/search endpoint.

Author: goncalossilva

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Support for searching projects
 - Support for searching sections
+- Support for searching labels
 
 ## [3.1.0] - 2025-05-07
 

tests/test_api_labels.py

@@ -88,6 +88,49 @@ async def test_get_labels(
         count += 1
 
 
+@pytest.mark.asyncio
+async def test_search_labels(
+    todoist_api: TodoistAPI,
+    todoist_api_async: TodoistAPIAsync,
+    requests_mock: responses.RequestsMock,
+    default_labels_response: list[PaginatedResults],
+    default_labels_list: list[list[Label]],
+) -> None:
+    endpoint = f"{DEFAULT_API_URL}/labels/search"
+    query = "A label"
+
+    cursor: str | None = None
+    for page in default_labels_response:
+        requests_mock.add(
+            method=responses.GET,
+            url=endpoint,
+            json=page,
+            status=200,
+            match=[
+                auth_matcher(),
+                request_id_matcher(),
+                param_matcher({"query": query}, cursor),
+            ],
+        )
+        cursor = page["next_cursor"]
+
+    count = 0
+
+    labels_iter = todoist_api.search_labels(query)
+
+    for i, labels in enumerate(labels_iter):
+        assert len(requests_mock.calls) == count + 1
+        assert labels == default_labels_list[i]
+        count += 1
+
+    labels_async_iter = await todoist_api_async.search_labels(query)
+
+    async for i, labels in enumerate_async(labels_async_iter):
+        assert len(requests_mock.calls) == count + 1
+        assert labels == default_labels_list[i]
+        count += 1
+
+
 @pytest.mark.asyncio
 async def test_add_label_minimal(
     todoist_api: TodoistAPI,

todoist_api_python/_core/endpoints.py

@@ -26,6 +26,7 @@
 SECTIONS_SEARCH_PATH_SUFFIX = "search"
 COMMENTS_PATH = "comments"
 LABELS_PATH = "labels"
+LABELS_SEARCH_PATH_SUFFIX = "search"
 SHARED_LABELS_PATH = "labels/shared"
 SHARED_LABELS_RENAME_PATH = f"{SHARED_LABELS_PATH}/rename"
 SHARED_LABELS_REMOVE_PATH = f"{SHARED_LABELS_PATH}/remove"

todoist_api_python/api.py

@@ -12,6 +12,7 @@
     COLLABORATORS_PATH,
     COMMENTS_PATH,
     LABELS_PATH,
+    LABELS_SEARCH_PATH_SUFFIX,
     PROJECT_ARCHIVE_PATH_SUFFIX,
     PROJECT_UNARCHIVE_PATH_SUFFIX,
     PROJECTS_PATH,
@@ -1330,7 +1331,7 @@ def get_labels(
         Be aware that each iteration fires off a network request to the Todoist API,
         and may result in rate limiting or other API restrictions.
 
-        :param limit: ` number of labels per page.
+        :param limit: Maximum number of labels per page.
         :return: An iterable of lists of personal labels.
         :raises requests.exceptions.HTTPError: If the API request fails.
         :raises TypeError: If the API response structure is unexpected.
@@ -1351,6 +1352,41 @@ def get_labels(
             params,
         )
 
+    def search_labels(
+        self,
+        query: Annotated[str, MinLen(1), MaxLen(1024)],
+        *,
+        limit: Annotated[int, Ge(1), Le(200)] | None = None,
+    ) -> Iterator[list[Label]]:
+        """
+        Search personal labels by name.
+
+        The response is an iterable of lists of labels matching the query.
+        Be aware that each iteration fires off a network request to the Todoist API,
+        and may result in rate limiting or other API restrictions.
+
+        :param query: Query string for label names.
+        :param limit: Maximum number of labels per page.
+        :return: An iterable of lists of labels.
+        :raises requests.exceptions.HTTPError: If the API request fails.
+        :raises TypeError: If the API response structure is unexpected.
+        """
+        endpoint = get_api_url(f"{LABELS_PATH}/{LABELS_SEARCH_PATH_SUFFIX}")
+
+        params: dict[str, Any] = {"query": query}
+        if limit is not None:
+            params["limit"] = limit
+
+        return ResultsPaginator(
+            self._session,
+            endpoint,
+            "results",
+            Label.from_dict,
+            self._token,
+            self._request_id_fn,
+            params,
+        )
+
     def add_label(
         self,
         name: Annotated[str, MinLen(1), MaxLen(60)],

todoist_api_python/api_async.py

@@ -894,6 +894,28 @@ async def get_labels(
         paginator = self._api.get_labels(limit=limit)
         return generate_async(paginator)
 
+    async def search_labels(
+        self,
+        query: Annotated[str, MinLen(1), MaxLen(1024)],
+        *,
+        limit: Annotated[int, Ge(1), Le(200)] | None = None,
+    ) -> AsyncGenerator[list[Label]]:
+        """
+        Search personal labels by name.
+
+        The response is an iterable of lists of labels matching the query.
+        Be aware that each iteration fires off a network request to the Todoist API,
+        and may result in rate limiting or other API restrictions.
+
+        :param query: Query string for label names.
+        :param limit: Maximum number of labels per page.
+        :return: An iterable of lists of labels.
+        :raises requests.exceptions.HTTPError: If the API request fails.
+        :raises TypeError: If the API response structure is unexpected.
+        """
+        paginator = self._api.search_labels(query, limit=limit)
+        return generate_async(paginator)
+
     async def add_label(
         self,
         name: Annotated[str, MinLen(1), MaxLen(60)],