From 664e5e95ab396bc40db99a63f33633eaa43ad7ae Mon Sep 17 00:00:00 2001 From: Haresh Kainth Date: Mon, 25 Nov 2024 22:54:27 +0000 Subject: [PATCH] chore:add detailed docstrings to utility functions Enhanced the docstrings for the `clear_all_documents`, `insert_or_update_document`, and `calculate_score` functions. These docstrings now include comprehensive explanations of parameters, behavior, logging, and exceptions. --- orp/orp_search/utils/documents.py | 45 +++++++++++++++++++++++++++---- 1 file changed, 40 insertions(+), 5 deletions(-) diff --git a/orp/orp_search/utils/documents.py b/orp/orp_search/utils/documents.py index c76eb8d..ce5ea27 100644 --- a/orp/orp_search/utils/documents.py +++ b/orp/orp_search/utils/documents.py @@ -9,6 +9,16 @@ def clear_all_documents(): + """ + Clears all documents from the 'DataResponseModel' table in the database. + + Logs the process of clearing the documents and handles any exceptions + that may occur. If an error occurs, it logs the error message and + raises an error. + + Raises: + CustomError: If there is an error while clearing the documents. + """ logger.debug("clearing all documents from table...") try: DataResponseModel.objects.all().delete() @@ -19,6 +29,28 @@ def clear_all_documents(): def insert_or_update_document(document_json): + """ + Inserts or updates a database document based on the given JSON data. + + The function first attempts to create a new document using the + provided JSON data. + + If the document already exists (detected through an exception), + it catches the error and tries to update the existing document instead. + + Args: + document_json (dict): A dictionary containing the data for the + document to be inserted or updated. + + Raises: + Exception: If an error occurs during either the insert or update + operation, the error is logged and re-raised. + + Logs: + Logs detailed debug messages for each step, including the document + being inserted, any errors encountered, and the outcome of the update + operation. + """ try: logger.debug("creating document...") logger.debug(f"document: {document_json}") @@ -45,12 +77,15 @@ def insert_or_update_document(document_json): def calculate_score(config, queryset: QuerySet): """ - Calculate the score of a search result based on the number of - search terms found in the title and description. + Calculate the search relevance score for each document in the queryset. + + Args: + config: Configuration object containing the search query settings. + queryset: QuerySet of documents to be scored. - :param search_terms: A list of search terms to look for in the - search result. - :return: The score based on the number of search terms found. + The function tokenizes the search query, filters out "AND" and "OR", + and computes the score for each document based on the frequency of + search terms in the document's title and description. """ def _extract_terms(search_query):