From 7eae4405c7f81e9996bc3781af5b6f3f204ea870 Mon Sep 17 00:00:00 2001 From: Devan Agrawal Date: Tue, 10 Sep 2024 13:30:37 -0700 Subject: [PATCH] DOC: update search method docstrings --- superscore/backends/core.py | 13 ++++++++++++- superscore/backends/filestore.py | 17 +++++++++-------- superscore/client.py | 7 ++++++- 3 files changed, 27 insertions(+), 10 deletions(-) diff --git a/superscore/backends/core.py b/superscore/backends/core.py index 70ba437..19d29a7 100644 --- a/superscore/backends/core.py +++ b/superscore/backends/core.py @@ -45,7 +45,18 @@ def update_entry(self, entry: Entry) -> None: raise NotImplementedError def search(self, *search_terms) -> Generator[Entry, None, None]: - """Yield Entry objects matching all ``search_terms``""" + """ + Yield Entry objects matching all ``search_terms``. Each SearchTerm has the format + (, , ). Some operators take tuples as values. + + The supported operators are: + - eq (equals) + - lt (less than or equal to) + - gt (greater than or equal to) + - in + - in_range (takes (, ) as value) + - like (fuzzy match, depends on type of value) + """ raise NotImplementedError @property diff --git a/superscore/backends/filestore.py b/superscore/backends/filestore.py index d2d2965..ab0d3c8 100644 --- a/superscore/backends/filestore.py +++ b/superscore/backends/filestore.py @@ -287,10 +287,9 @@ def delete_entry(self, entry: Entry) -> None: def search(self, *search_terms) -> Generator[Entry, None, None]: """ - Search for an entry that matches ``search_kwargs``. - Keys are attributes on `Entry` subclasses - Values can be either a single value to match or a tuple of valid values - Currently does not support partial matches. + Return entries that match all ``search_terms``. + Keys are attributes on `Entry` subclasses, or special keywords. + Values can be a single value or a tuple of values depending on operator. """ with self._load_and_store_context() as db: for entry in db.values(): @@ -312,18 +311,20 @@ def search(self, *search_terms) -> Generator[Entry, None, None]: @staticmethod def getComparator(op: str, typ: type) -> Callable[[Any, Any], bool]: """ + Return a function that applies the comparator ``op`` to two args. The function + may depend on the type of the args ``typ`` + Parameters ---------- op: str - one of the comparators that all backends must support, consisting of - 'eq', 'lt', 'gt', 'like', and 'in' + one of the comparators that all backends must support, detailed in _Backend.search typ: type - the type that the comparator must operate on + the type that the comparator will operate on Returns ------- Callable - a function that compares two values with type typ according to op + a function that compares two values according to ``op`` """ if op == "eq": return typ.__eq__ diff --git a/superscore/client.py b/superscore/client.py index b004c3c..5a44b86 100644 --- a/superscore/client.py +++ b/superscore/client.py @@ -148,7 +148,12 @@ def find_config() -> Path: raise OSError("No superscore configuration file found. Check SUPERSCORE_CFG.") def search(self, *post) -> Generator[Entry, None, None]: - """Search by SearchTerm. Can search by any field, plus special flags""" + """ + Search backend for entries matching all SearchTerms in ``post``. Can search by any + field, plus some special keywords. Backends support operators listed in _Backend.search. + Some operators are supported in the UI / client and must be converted before being + passed to the backend. + """ new_search_terms = [] for search_term in post: if search_term.operator == 'like_with_tols':