mirror of
https://gitlab2.federez.net/re2o/re2o
synced 2024-11-21 19:03:11 +00:00
Add some docstrings in search/
This commit is contained in:
parent
7a126c51a1
commit
25e4d52615
3 changed files with 65 additions and 23 deletions
|
@ -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()
|
||||
|
|
|
@ -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"),
|
||||
|
|
|
@ -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(
|
||||
|
|
Loading…
Reference in a new issue