From 3ec05c68e54df0caf219e55da463deb8671ddcbb Mon Sep 17 00:00:00 2001 From: Laouen Fernet Date: Tue, 28 Apr 2020 21:47:39 +0200 Subject: [PATCH] Add some docstrings in search/ --- search/engine.py | 80 ++++++++++++++++++++++++++++++++++++------------ search/forms.py | 4 +-- search/views.py | 4 +-- 3 files changed, 65 insertions(+), 23 deletions(-) diff --git a/search/engine.py b/search/engine.py index e0ed1018..c1adc501 100644 --- a/search/engine.py +++ b/search/engine.py @@ -45,21 +45,43 @@ from re2o.base import SortTable, re2o_paginator class Query: """Class representing a query. It can contain the user-entered text, the operator for the query, - and a list of subqueries""" + and a list of subqueries. + + Attributes: + text: the string written by the user in a query. + operator: character used to link subqueries, e.g. "+". + subqueries: list of Query objects when the current query is split in + several parts. + """ def __init__(self, text="", case_sensitive=False): - self.text = text # Content of the query - self.operator = None # Whether a special char (ex "+") was used - self.subqueries = None # When splitting the query in subparts + """Initialise an instance of Query. + + Args: + text: the content of the query (default: ""). + case_sensitive: bool, True if the query is case sensitive and + False if not (default: False). + """ + self.text = text + self.operator = None + self.subqueries = None self.case_sensitive = case_sensitive def add_char(self, char): - """Add the given char to the query's text""" + """Add the given character to the query's text. + + Args: + char: the character to be added. + """ self.text += char def add_operator(self, operator): """Consider a new operator was entered, and that it must be processed. The query's current text is moved to self.subqueries in the form - of a plain Query object""" + of a plain Query object. + + Args: + operator: the operator to be added. + """ self.operator = operator if self.subqueries is None: @@ -71,7 +93,7 @@ class Query: @property def plaintext(self): - """Returns a textual representation of the query's content""" + """Return the textual representation of the query's content.""" if self.operator is not None: return self.operator.join([q.plaintext for q in self.subqueries]) @@ -82,7 +104,7 @@ class Query: def filter_fields(): - """Return the list of fields the search applies to""" + """Return the list of fields the search applies to.""" return ["users", "clubs", "machines", @@ -95,12 +117,12 @@ def filter_fields(): def empty_filters(): - """Build empty filters used by Django""" + """Build empty filters used by Django.""" return {f: Q() for f in filter_fields()} def is_int(variable): - """ Check if the variable can be casted to an integer """ + """Check if the variable can be cast to an integer.""" try: int(variable) except ValueError: @@ -111,8 +133,18 @@ def is_int(variable): def finish_results(request, results, col, order): """Sort the results by applying filters and then limit them to the - number of max results. Finally add the info of the nmax number of results - to the dict""" + number of max results. Finally add the info of the maximum number of + results to the dictionary. + + Args: + request: django request, corresponding to the search. + results: dict, the results of the search. + col: the column used to sort the results. + order: the order used to sort the results. + + Returns: + The dictionary of results sorted and paginated. + """ results["users"] = SortTable.sort( results["users"], col, order, SortTable.USERS_INDEX ) @@ -156,7 +188,16 @@ def finish_results(request, results, col, order): def contains_filter(attribute, word, case_sensitive=False): """Create a django model filtering whether the given attribute - contains the specified value.""" + contains the specified value. + + Args: + attribute: the attribute used to check if it contains the given word or + not. + word: the word used to check if it is contained in the attribute or + not. + case_sensitive: bool, True if the check is case sensitive and + False if not (default: False). + """ if case_sensitive: attr = "{}__{}".format(attribute, "contains") else: @@ -168,12 +209,13 @@ def contains_filter(attribute, word, case_sensitive=False): def search_single_word(word, filters, user, start, end, user_state, email_state, aff, case_sensitive=False): - """ Construct the correct filters to match differents fields of some models + """Construct the correct filters to match differents fields of some models with the given query according to the given filters. - The match field are either CharField or IntegerField that will be displayed + The match fields are either CharField or IntegerField that will be displayed on the results page (else, one might not see why a result has matched the query). IntegerField are matched against the query only if it can be casted - to an int.""" + to an int. + """ # Users if "0" in aff: @@ -333,7 +375,7 @@ def search_single_word(word, filters, user, start, end, def apply_filters(filters, user, aff): - """ Apply the filters constructed by search_single_query. + """Apply the filters constructed by search_single_query. It also takes into account the visual filters defined during the search query. """ @@ -406,8 +448,8 @@ def apply_filters(filters, user, aff): def search_single_query(query, filters, user, start, end, user_state, email_state, aff): - """ Handle different queries an construct the correct filters using - search_single_word""" + """Handle different queries an construct the correct filters using + search_single_word.""" if query.operator == "+": # Special queries with "+" operators should use & rather than | newfilters = empty_filters() diff --git a/search/forms.py b/search/forms.py index 2c495b5a..ef049ffc 100644 --- a/search/forms.py +++ b/search/forms.py @@ -62,7 +62,7 @@ def initial_choices(choice_set): class SearchForm(Form): - """The form for a simple search""" + """Form used to do a simple search.""" q = forms.CharField( label=_("Search"), @@ -78,7 +78,7 @@ class SearchForm(Form): class SearchFormPlus(Form): - """The form for an advanced search (with filters)""" + """Form used to do an advanced search (with filters).""" q = forms.CharField( label=_("Search"), diff --git a/search/views.py b/search/views.py index 00141ed1..6f71000c 100644 --- a/search/views.py +++ b/search/views.py @@ -83,7 +83,7 @@ def get_results(query, request, params): @login_required @can_view_all(User, Machine, Cotisation) def search(request): - """ La page de recherche standard """ + """View used to display the simple search page.""" search_form = SearchForm(request.GET or None) if search_form.is_valid(): return render( @@ -101,7 +101,7 @@ def search(request): @login_required @can_view_all(User, Machine, Cotisation) def searchp(request): - """ La page de recherche avancée """ + """View used to display the advanced search page.""" search_form = SearchFormPlus(request.GET or None) if search_form.is_valid(): return render(