@@ -90,6 +90,18 @@ def tasks(uuid=None, include_items=False, **kwargs): # noqa: C901
90
90
If the argument is `True`, only include tasks _with_ a due date.
91
91
If the argument is `None` (default), then include all tasks.
92
92
93
+ search_query : str, bool, or None, optional
94
+ The string value is passed to the SQL LIKE operator. It can thus
95
+ include placeholders such as '%' and '_'.
96
+
97
+ Currently titles and notes of to-dos, projects, headings, and areas
98
+ are taken into account.
99
+
100
+ If the query is `False`, then return items where titles or notes
101
+ are empty.
102
+
103
+ If the query `None`, then return all items.
104
+
93
105
index : {'index', 'todayIndex'}, default 'index'
94
106
Database field to order result by.
95
107
@@ -315,26 +327,34 @@ def tags(title=None, include_items=False, **kwargs):
315
327
# Utility API functions derived from above
316
328
# --------------------------------------------------
317
329
330
+
318
331
def search (query : str , ** kwargs ) -> List [Dict ]:
319
332
"""
320
- Search the database. This takes mainly notes and titles into account .
333
+ Search tasks in the database .
321
334
322
- Parameters
323
- ----------
324
- query : str
325
- The string with optional placeholders (%) to search for.
335
+ Currently titles and notes of to-dos, projects, headings, and areas
336
+ are taken into account.
326
337
327
- Returns
328
- -------
329
- list of dict
330
- Representing Things items.
338
+ See the `search_query` parameter of `api.tasks` for details.
331
339
332
340
Examples
333
341
--------
334
- >>> things.search('substring % within notes and titles')
335
- ...
342
+ >>> things.search('book')
343
+ [{'uuid': 'YrOmUnEXASmpq8ch6RsyPt',
344
+ 'type': 'to-do',
345
+ 'title': 'Book a hotel room',
346
+ ...},
347
+ {'uuid': 'KVHAxIIJ52a0h1RCbmg5D6',
348
+ 'type': 'to-do',
349
+ 'title': 'Book flights',
350
+ ...}]
351
+ >>> things.search('book%room')
352
+ [{'uuid': 'YrOmUnEXASmpq8ch6RsyPt',
353
+ 'type': 'to-do',
354
+ 'title': 'Book a hotel room',
355
+ ...}]
336
356
"""
337
- return tasks (querystr = query , ** kwargs )
357
+ return tasks (search_query = query , ** kwargs )
338
358
339
359
340
360
def get (uuid , default = None , ** kwargs ):
0 commit comments