Skip to content

Commit cd99d6d

Browse files
committed
refactoring; improve documentation; more consistent and precise names
1 parent c2cab71 commit cd99d6d

File tree

2 files changed

+187
-118
lines changed

2 files changed

+187
-118
lines changed

things/api.py

Lines changed: 32 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,18 @@ def tasks(uuid=None, include_items=False, **kwargs): # noqa: C901
9090
If the argument is `True`, only include tasks _with_ a due date.
9191
If the argument is `None` (default), then include all tasks.
9292
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+
93105
index : {'index', 'todayIndex'}, default 'index'
94106
Database field to order result by.
95107
@@ -315,26 +327,34 @@ def tags(title=None, include_items=False, **kwargs):
315327
# Utility API functions derived from above
316328
# --------------------------------------------------
317329

330+
318331
def search(query: str, **kwargs) -> List[Dict]:
319332
"""
320-
Search the database. This takes mainly notes and titles into account.
333+
Search tasks in the database.
321334
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.
326337
327-
Returns
328-
-------
329-
list of dict
330-
Representing Things items.
338+
See the `search_query` parameter of `api.tasks` for details.
331339
332340
Examples
333341
--------
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+
...}]
336356
"""
337-
return tasks(querystr=query, **kwargs)
357+
return tasks(search_query=query, **kwargs)
338358

339359

340360
def get(uuid, default=None, **kwargs):

0 commit comments

Comments
 (0)