From 4f9834b0e8e49705503615a85b738953a7cc6c27 Mon Sep 17 00:00:00 2001 From: Jk40git <125589910+Jk40git@users.noreply.github.com> Date: Mon, 12 Feb 2024 13:57:49 +0000 Subject: [PATCH 1/4] Update checkquery.py Changes made on the docstrings --- src/scribe_data/checkquery.py | 253 ++++++++++++++++++++++++---------- 1 file changed, 184 insertions(+), 69 deletions(-) diff --git a/src/scribe_data/checkquery.py b/src/scribe_data/checkquery.py index b2cf4960..1e529f6b 100755 --- a/src/scribe_data/checkquery.py +++ b/src/scribe_data/checkquery.py @@ -40,11 +40,19 @@ class QueryFile: def load(self, limit: int) -> str: """Load the SPARQL query from 'path' into a string. - Args: - limit (int): the maximum number of results a query should return. + Parameters + ----------- + source_value : str + The source value to find equivalents for (e.g. 'english'). + source_key : str + The source key to reference (e.g. 'language'). + target_key : str + The key to target (e.g. 'iso'). + error_msg : str + The message displayed when a value cannot be found. Returns: - str: the SPARQL query. + The 'target' value given the passed arguments. """ with open(self.path, encoding="utf-8") as in_stream: return f"{in_stream.read()}\nLIMIT {limit}\n" @@ -60,9 +68,16 @@ class QueryExecutionException(Exception): def __init__(self, message: str, query: QueryFile) -> None: """ - Args: - message (str): why the query failed. - query (QueryFile): the query that failed. + Parameters + ----------- + source_value : str + The source value to find equivalents for (e.g. 'english'). + source_key : str + The source key to reference (e.g. 'language'). + target_key : str + The key to target (e.g. 'iso'). + error_msg : str + The message displayed when a value cannot be found. """ self.message = message self.query = query @@ -75,13 +90,21 @@ def __str__(self) -> str: def ping(url: str, timeout: int) -> bool: """ Test if a URL is reachable. - - Args: - url (str): the URL to test. - timeout (int): the maximum number of seconds to wait for a reply. - - Returns: - bool: True if connectivity established. False otherwise. + Parameters + ----------- + source_value : str + The source value to find equivalents for (e.g. 'english'). + source_key : str + The source key to reference (e.g. 'language'). + target_key : str + The key to target (e.g. 'iso'). + error_msg : str + The message displayed when a value cannot be found. + + + Returns + -------- + The 'target' value given the passed arguments. """ try: with urllib.request.urlopen(url, timeout=timeout) as response: @@ -159,12 +182,22 @@ def sparql_context(url: str) -> SPARQL.SPARQLWrapper: Configure a SPARQL context. A context allows the execution of SPARQL queries. - - Args: - url (str): a valid URL of a SPARQL endpoint. - - Returns: - SPARQLWrapper: the context. + Parameters + ----------- + source_value : str + The source value to find equivalents for (e.g. 'english'). + source_key : str + The source key to reference (e.g. 'language'). + target_key : str + The key to target (e.g. 'iso'). + error_msg : str + The message displayed when a value cannot be found. + + Returns + -------- + The 'target' value given the passed arguments. + """ + """ context = SPARQL.SPARQLWrapper(url) context.setReturnFormat(SPARQL.JSON) @@ -179,15 +212,20 @@ def execute( """ Execute a SPARQL query in a given context. - Args: - query (QueryFile): the SPARQL query to run. - limit (int): the maximum number of results a query should return. - context (SPARQLWrapper): the SPARQL context. - tries (int): the maximum number of times the query should be executed - after failure. - - Returns: - dict: results of the query. + Parameters + ----------- + source_value : str + The source value to find equivalents for (e.g. 'english'). + source_key : str + The source key to reference (e.g. 'language'). + target_key : str + The key to target (e.g. 'iso'). + error_msg : str + The message displayed when a value cannot be found. + + Returns + -------- + The 'target' value given the passed arguments. """ def delay_in_seconds() -> int: @@ -218,11 +256,20 @@ def check_sparql_file(fpath: str) -> Path: """ Check meta information of SPARQL query file. - Args: - fpath (str): the file to validate. - - Returns: - Path: the validated file. + Parameters + ----------- + source_value : str + The source value to find equivalents for (e.g. 'english'). + source_key : str + The source key to reference (e.g. 'language'). + target_key : str + The key to target (e.g. 'iso'). + error_msg : str + The message displayed when a value cannot be found. + + Returns + -------- + The 'target' value given the passed arguments. """ path = Path(fpath) @@ -239,15 +286,24 @@ def check_positive_int(value: str, err_msg: str) -> int: """ Ensure 'value' is a positive number. - Args: - value (str): the value to be validated. - err_msg (str): used when value fails validation. - - Raises: - argparse.ArgumentTypeError - - Returns: - int: the validated number. + Parameters + ----------- + source_value : str + The source value to find equivalents for (e.g. 'english'). + source_key : str + The source key to reference (e.g. 'language'). + target_key : str + The key to target (e.g. 'iso'). + error_msg : str + The message displayed when a value cannot be found. + + Raises + ------- + ValueError : when a source_value is not supported. + + Returns + -------- + The 'target' value given the passed arguments. """ try: number = int(value) @@ -263,14 +319,24 @@ def check_limit(limit: str) -> int: """ Validate the 'limit' argument. - Args: - limit (str): the LIMIT to be validated. - - Raises: - argparse.ArgumentTypeError - - Returns: - int: the validated LIMIT + Parameters + ----------- + source_value : str + The source value to find equivalents for (e.g. 'english'). + source_key : str + The source key to reference (e.g. 'language'). + target_key : str + The key to target (e.g. 'iso'). + error_msg : str + The message displayed when a value cannot be found. + + Raises + ------- + ValueError : when a source_value is not supported. + + Returns + -------- + The 'target' value given the passed arguments. """ return check_positive_int(limit, "LIMIT must be an integer of value 1 or greater.") @@ -279,14 +345,24 @@ def check_timeout(timeout: str) -> int: """ Validate the 'timeout' argument. - Args: - timeout (str): the timeout to be validated. - - Raises: - argparse.ArgumentTypeError - - Returns: - int: the validated timeout. + Parameters + ----------- + source_value : str + The source value to find equivalents for (e.g. 'english'). + source_key : str + The source key to reference (e.g. 'language'). + target_key : str + The key to target (e.g. 'iso'). + error_msg : str + The message displayed when a value cannot be found. + + Raises + ------- + ValueError : when a source_value is not supported. + + Returns + -------- + The 'target' value given the passed arguments. """ return check_positive_int( timeout, "timeout must be an integer of value 1 or greater." @@ -296,12 +372,20 @@ def check_timeout(timeout: str) -> int: def main(argv=None) -> int: """ The main function. - - Args: - argv : If set to None then argparse will use sys.argv as the arguments. - - Returns: - int: the exit status - 0: success, any other value - failure. + Parameters + ----------- + source_value : str + The source value to find equivalents for (e.g. 'english'). + source_key : str + The source key to reference (e.g. 'language'). + target_key : str + The key to target (e.g. 'iso'). + error_msg : str + The message displayed when a value cannot be found. + + Returns + -------- + The 'target' value given the passed arguments. """ cli = argparse.ArgumentParser( description=f"run SPARQL queries from the '{PROJECT_ROOT}' project", @@ -424,8 +508,24 @@ def error_report(failures: list[QueryExecutionException]) -> None: """ Report failed queries. - Args: - failures (list[QueryExecutionException]): failed queries. + Parameters + ----------- + source_value : str + The source value to find equivalents for (e.g. 'english'). + source_key : str + The source key to reference (e.g. 'language'). + target_key : str + The key to target (e.g. 'iso'). + error_msg : str + The message displayed when a value cannot be found. + + Raises + ------- + ValueError : when a source_value is not supported. + + Returns + -------- + The 'target' value given the passed arguments. """ if not failures: return @@ -440,9 +540,24 @@ def success_report(successes: list[tuple[QueryFile, dict]], display: bool) -> No """ Report successful queries. - Args: - successes (list[tuple[QueryFile, dict]]): successful queries. - display (bool): should there be output? + Parameters + ----------- + source_value : str + The source value to find equivalents for (e.g. 'english'). + source_key : str + The source key to reference (e.g. 'language'). + target_key : str + The key to target (e.g. 'iso'). + error_msg : str + The message displayed when a value cannot be found. + + Raises + ------- + ValueError : when a source_value is not supported. + + Returns + -------- + The 'target' value given the passed arguments. """ if not (display and successes): return From 2abbcca62f4e8d45a4a11d1c42a0cbfcbb84eaf1 Mon Sep 17 00:00:00 2001 From: Jk40git <125589910+Jk40git@users.noreply.github.com> Date: Mon, 12 Feb 2024 16:13:52 +0000 Subject: [PATCH 2/4] Update checkquery.py --- src/scribe_data/checkquery.py | 261 +++++++++++----------------------- 1 file changed, 86 insertions(+), 175 deletions(-) diff --git a/src/scribe_data/checkquery.py b/src/scribe_data/checkquery.py index 1e529f6b..481e51a7 100755 --- a/src/scribe_data/checkquery.py +++ b/src/scribe_data/checkquery.py @@ -40,19 +40,13 @@ class QueryFile: def load(self, limit: int) -> str: """Load the SPARQL query from 'path' into a string. - Parameters - ----------- - source_value : str - The source value to find equivalents for (e.g. 'english'). - source_key : str - The source key to reference (e.g. 'language'). - target_key : str - The key to target (e.g. 'iso'). - error_msg : str - The message displayed when a value cannot be found. + Args: + ------ + limit (int): the maximum number of results a query should return. Returns: - The 'target' value given the passed arguments. + -------- + str: the SPARQL query. """ with open(self.path, encoding="utf-8") as in_stream: return f"{in_stream.read()}\nLIMIT {limit}\n" @@ -68,16 +62,10 @@ class QueryExecutionException(Exception): def __init__(self, message: str, query: QueryFile) -> None: """ - Parameters - ----------- - source_value : str - The source value to find equivalents for (e.g. 'english'). - source_key : str - The source key to reference (e.g. 'language'). - target_key : str - The key to target (e.g. 'iso'). - error_msg : str - The message displayed when a value cannot be found. + Args: + ------ + message (str): why the query failed. + query (QueryFile): the query that failed. """ self.message = message self.query = query @@ -90,21 +78,15 @@ def __str__(self) -> str: def ping(url: str, timeout: int) -> bool: """ Test if a URL is reachable. - Parameters - ----------- - source_value : str - The source value to find equivalents for (e.g. 'english'). - source_key : str - The source key to reference (e.g. 'language'). - target_key : str - The key to target (e.g. 'iso'). - error_msg : str - The message displayed when a value cannot be found. - - - Returns - -------- - The 'target' value given the passed arguments. + + Args: + ------ + url (str): the URL to test. + timeout (int): the maximum number of seconds to wait for a reply. + + Returns: + ------- + bool: True if connectivity established. False otherwise. """ try: with urllib.request.urlopen(url, timeout=timeout) as response: @@ -120,6 +102,7 @@ def all_queries() -> list[QueryFile]: All the SPARQL queries in, and below, 'Scribe-Data/'. Returns: + ------- list[QueryFile]: the SPARQL query files. """ parts = Path(__file__).resolve().parts @@ -144,6 +127,7 @@ def changed_queries() -> Optional[list[QueryFile]]: Includes new queries. Returns: + ------- Optional[list[QueryFile]]: list of changed/new SPARQL queries or None if error. """ @@ -182,22 +166,14 @@ def sparql_context(url: str) -> SPARQL.SPARQLWrapper: Configure a SPARQL context. A context allows the execution of SPARQL queries. - Parameters - ----------- - source_value : str - The source value to find equivalents for (e.g. 'english'). - source_key : str - The source key to reference (e.g. 'language'). - target_key : str - The key to target (e.g. 'iso'). - error_msg : str - The message displayed when a value cannot be found. - - Returns - -------- - The 'target' value given the passed arguments. - """ - + + Args: + ------ + url (str): a valid URL of a SPARQL endpoint. + + Returns: + ------- + SPARQLWrapper: the context. """ context = SPARQL.SPARQLWrapper(url) context.setReturnFormat(SPARQL.JSON) @@ -212,20 +188,17 @@ def execute( """ Execute a SPARQL query in a given context. - Parameters - ----------- - source_value : str - The source value to find equivalents for (e.g. 'english'). - source_key : str - The source key to reference (e.g. 'language'). - target_key : str - The key to target (e.g. 'iso'). - error_msg : str - The message displayed when a value cannot be found. - - Returns + Args: + -------- + query (QueryFile): the SPARQL query to run. + limit (int): the maximum number of results a query should return. + context (SPARQLWrapper): the SPARQL context. + tries (int): the maximum number of times the query should be executed + after failure. + + Returns: -------- - The 'target' value given the passed arguments. + dict: results of the query. """ def delay_in_seconds() -> int: @@ -256,20 +229,13 @@ def check_sparql_file(fpath: str) -> Path: """ Check meta information of SPARQL query file. - Parameters - ----------- - source_value : str - The source value to find equivalents for (e.g. 'english'). - source_key : str - The source key to reference (e.g. 'language'). - target_key : str - The key to target (e.g. 'iso'). - error_msg : str - The message displayed when a value cannot be found. - - Returns - -------- - The 'target' value given the passed arguments. + Args: + ------ + fpath (str): the file to validate. + + Returns: + ------- + Path: the validated file. """ path = Path(fpath) @@ -286,24 +252,18 @@ def check_positive_int(value: str, err_msg: str) -> int: """ Ensure 'value' is a positive number. - Parameters - ----------- - source_value : str - The source value to find equivalents for (e.g. 'english'). - source_key : str - The source key to reference (e.g. 'language'). - target_key : str - The key to target (e.g. 'iso'). - error_msg : str - The message displayed when a value cannot be found. - - Raises + Args: ------- - ValueError : when a source_value is not supported. + value (str): the value to be validated. + err_msg (str): used when value fails validation. - Returns + Raises: + ------- + argparse.ArgumentTypeError + + Returns: -------- - The 'target' value given the passed arguments. + int: the validated number. """ try: number = int(value) @@ -319,24 +279,17 @@ def check_limit(limit: str) -> int: """ Validate the 'limit' argument. - Parameters - ----------- - source_value : str - The source value to find equivalents for (e.g. 'english'). - source_key : str - The source key to reference (e.g. 'language'). - target_key : str - The key to target (e.g. 'iso'). - error_msg : str - The message displayed when a value cannot be found. - - Raises + Args: + ------ + limit (str): the LIMIT to be validated. + + Raises: ------- - ValueError : when a source_value is not supported. + argparse.ArgumentTypeError - Returns - -------- - The 'target' value given the passed arguments. + Returns: + ------- + int: the validated LIMIT """ return check_positive_int(limit, "LIMIT must be an integer of value 1 or greater.") @@ -345,24 +298,17 @@ def check_timeout(timeout: str) -> int: """ Validate the 'timeout' argument. - Parameters - ----------- - source_value : str - The source value to find equivalents for (e.g. 'english'). - source_key : str - The source key to reference (e.g. 'language'). - target_key : str - The key to target (e.g. 'iso'). - error_msg : str - The message displayed when a value cannot be found. - - Raises + Args: + ------ + timeout (str): the timeout to be validated. + + Raises: ------- - ValueError : when a source_value is not supported. + argparse.ArgumentTypeError - Returns + Returns: -------- - The 'target' value given the passed arguments. + int: the validated timeout. """ return check_positive_int( timeout, "timeout must be an integer of value 1 or greater." @@ -372,20 +318,14 @@ def check_timeout(timeout: str) -> int: def main(argv=None) -> int: """ The main function. - Parameters - ----------- - source_value : str - The source value to find equivalents for (e.g. 'english'). - source_key : str - The source key to reference (e.g. 'language'). - target_key : str - The key to target (e.g. 'iso'). - error_msg : str - The message displayed when a value cannot be found. - - Returns - -------- - The 'target' value given the passed arguments. + + Args: + ------ + argv : If set to None then argparse will use sys.argv as the arguments. + + Returns: + ------- + int: the exit status - 0: success, any other value - failure. """ cli = argparse.ArgumentParser( description=f"run SPARQL queries from the '{PROJECT_ROOT}' project", @@ -508,24 +448,9 @@ def error_report(failures: list[QueryExecutionException]) -> None: """ Report failed queries. - Parameters - ----------- - source_value : str - The source value to find equivalents for (e.g. 'english'). - source_key : str - The source key to reference (e.g. 'language'). - target_key : str - The key to target (e.g. 'iso'). - error_msg : str - The message displayed when a value cannot be found. - - Raises - ------- - ValueError : when a source_value is not supported. - - Returns - -------- - The 'target' value given the passed arguments. + Args: + ------ + failures (list[QueryExecutionException]): failed queries. """ if not failures: return @@ -540,24 +465,10 @@ def success_report(successes: list[tuple[QueryFile, dict]], display: bool) -> No """ Report successful queries. - Parameters - ----------- - source_value : str - The source value to find equivalents for (e.g. 'english'). - source_key : str - The source key to reference (e.g. 'language'). - target_key : str - The key to target (e.g. 'iso'). - error_msg : str - The message displayed when a value cannot be found. - - Raises - ------- - ValueError : when a source_value is not supported. - - Returns - -------- - The 'target' value given the passed arguments. + Args: + ------ + successes (list[tuple[QueryFile, dict]]): successful queries. + display (bool): should there be output? """ if not (display and successes): return From 1d0f47c56d0bb4a537ebcfe7c2520d8d58122d01 Mon Sep 17 00:00:00 2001 From: Jk40git <125589910+Jk40git@users.noreply.github.com> Date: Mon, 12 Feb 2024 17:21:27 +0000 Subject: [PATCH 3/4] Update checkquery.py Changes made in the docstrings --- src/scribe_data/checkquery.py | 82 +++++++++++++++++------------------ 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/src/scribe_data/checkquery.py b/src/scribe_data/checkquery.py index 481e51a7..833ec160 100755 --- a/src/scribe_data/checkquery.py +++ b/src/scribe_data/checkquery.py @@ -40,11 +40,11 @@ class QueryFile: def load(self, limit: int) -> str: """Load the SPARQL query from 'path' into a string. - Args: + Parameters ------ limit (int): the maximum number of results a query should return. - Returns: + Returns -------- str: the SPARQL query. """ @@ -62,8 +62,8 @@ class QueryExecutionException(Exception): def __init__(self, message: str, query: QueryFile) -> None: """ - Args: - ------ + Parameters + ---------- message (str): why the query failed. query (QueryFile): the query that failed. """ @@ -79,12 +79,12 @@ def ping(url: str, timeout: int) -> bool: """ Test if a URL is reachable. - Args: - ------ + Parameters + --------- url (str): the URL to test. timeout (int): the maximum number of seconds to wait for a reply. - Returns: + Returns ------- bool: True if connectivity established. False otherwise. """ @@ -167,12 +167,12 @@ def sparql_context(url: str) -> SPARQL.SPARQLWrapper: A context allows the execution of SPARQL queries. - Args: - ------ + Parameters + --------- url (str): a valid URL of a SPARQL endpoint. - Returns: - ------- + Returns + -------- SPARQLWrapper: the context. """ context = SPARQL.SPARQLWrapper(url) @@ -188,15 +188,15 @@ def execute( """ Execute a SPARQL query in a given context. - Args: - -------- + Parameters + --------- query (QueryFile): the SPARQL query to run. limit (int): the maximum number of results a query should return. context (SPARQLWrapper): the SPARQL context. tries (int): the maximum number of times the query should be executed after failure. - Returns: + Returns -------- dict: results of the query. """ @@ -229,12 +229,12 @@ def check_sparql_file(fpath: str) -> Path: """ Check meta information of SPARQL query file. - Args: + Parameters ------ fpath (str): the file to validate. - Returns: - ------- + Returns + -------- Path: the validated file. """ path = Path(fpath) @@ -252,16 +252,16 @@ def check_positive_int(value: str, err_msg: str) -> int: """ Ensure 'value' is a positive number. - Args: - ------- + Parameters + ---------- value (str): the value to be validated. err_msg (str): used when value fails validation. - Raises: + Raises ------- argparse.ArgumentTypeError - Returns: + Returns -------- int: the validated number. """ @@ -279,16 +279,16 @@ def check_limit(limit: str) -> int: """ Validate the 'limit' argument. - Args: - ------ + Parameters + --------- limit (str): the LIMIT to be validated. - Raises: - ------- + Raises + -------- argparse.ArgumentTypeError - Returns: - ------- + Returns + -------- int: the validated LIMIT """ return check_positive_int(limit, "LIMIT must be an integer of value 1 or greater.") @@ -298,16 +298,16 @@ def check_timeout(timeout: str) -> int: """ Validate the 'timeout' argument. - Args: - ------ + Parameters + ---------- timeout (str): the timeout to be validated. - Raises: - ------- + Raises + -------- argparse.ArgumentTypeError - Returns: - -------- + Returns + --------- int: the validated timeout. """ return check_positive_int( @@ -319,12 +319,12 @@ def main(argv=None) -> int: """ The main function. - Args: - ------ + Parameters + ---------- argv : If set to None then argparse will use sys.argv as the arguments. - Returns: - ------- + Returns + -------- int: the exit status - 0: success, any other value - failure. """ cli = argparse.ArgumentParser( @@ -448,8 +448,8 @@ def error_report(failures: list[QueryExecutionException]) -> None: """ Report failed queries. - Args: - ------ + Parameters + ---------- failures (list[QueryExecutionException]): failed queries. """ if not failures: @@ -465,8 +465,8 @@ def success_report(successes: list[tuple[QueryFile, dict]], display: bool) -> No """ Report successful queries. - Args: - ------ + Parameters + ---------- successes (list[tuple[QueryFile, dict]]): successful queries. display (bool): should there be output? """ From aeb426c20db0306d4614909223ccb714c7d260b6 Mon Sep 17 00:00:00 2001 From: Andrew Tavis McAllister Date: Thu, 22 Feb 2024 02:15:44 +0100 Subject: [PATCH 4/4] Edits to checkquery docstrings to standardize them --- src/scribe_data/checkquery.py | 146 ++++++++++++++++++++++------------ 1 file changed, 96 insertions(+), 50 deletions(-) diff --git a/src/scribe_data/checkquery.py b/src/scribe_data/checkquery.py index 833ec160..7a470738 100755 --- a/src/scribe_data/checkquery.py +++ b/src/scribe_data/checkquery.py @@ -2,6 +2,25 @@ """ Command line tool for testing SPARQl queries against an endpoint. + +Contents: + QueryFile Class: + load, + __repr__, + QueryExecutionException: + __init__, + __str__, + ping, + all_queries, + changed_queries, + sparql_context, + execute, + check_sparql_file, + check_limit, + check_timeout, + main, + error_report, + success_report, """ import argparse @@ -38,15 +57,17 @@ class QueryFile: path: Path def load(self, limit: int) -> str: - """Load the SPARQL query from 'path' into a string. + """ + Load the SPARQL query from 'path' into a string. Parameters - ------ - limit (int): the maximum number of results a query should return. + ---------- + limit : int + The maximum number of results a query should return. Returns - -------- - str: the SPARQL query. + ------- + str : the SPARQL query. """ with open(self.path, encoding="utf-8") as in_stream: return f"{in_stream.read()}\nLIMIT {limit}\n" @@ -64,8 +85,11 @@ def __init__(self, message: str, query: QueryFile) -> None: """ Parameters ---------- - message (str): why the query failed. - query (QueryFile): the query that failed. + message : str + Why the query failed. + + query : QueryFile + The query that failed. """ self.message = message self.query = query @@ -81,12 +105,15 @@ def ping(url: str, timeout: int) -> bool: Parameters --------- - url (str): the URL to test. - timeout (int): the maximum number of seconds to wait for a reply. + url : str + The URL to test. + + timeout : int + The maximum number of seconds to wait for a reply. Returns ------- - bool: True if connectivity established. False otherwise. + bool : True if connectivity is established or False otherwise. """ try: with urllib.request.urlopen(url, timeout=timeout) as response: @@ -101,9 +128,9 @@ def all_queries() -> list[QueryFile]: """ All the SPARQL queries in, and below, 'Scribe-Data/'. - Returns: + Returns ------- - list[QueryFile]: the SPARQL query files. + list[QueryFile] : the SPARQL query files. """ parts = Path(__file__).resolve().parts prj_root_idx = parts.index(PROJECT_ROOT) @@ -126,9 +153,9 @@ def changed_queries() -> Optional[list[QueryFile]]: Includes new queries. - Returns: + Returns ------- - Optional[list[QueryFile]]: list of changed/new SPARQL queries or None if error. + Optional[list[QueryFile]] : list of changed/new SPARQL queries or None if there's an error. """ result = subprocess.run( @@ -168,12 +195,13 @@ def sparql_context(url: str) -> SPARQL.SPARQLWrapper: A context allows the execution of SPARQL queries. Parameters - --------- - url (str): a valid URL of a SPARQL endpoint. + ---------- + url : str + A valid URL of a SPARQL endpoint. Returns - -------- - SPARQLWrapper: the context. + ------- + SPARQLWrapper : the context. """ context = SPARQL.SPARQLWrapper(url) context.setReturnFormat(SPARQL.JSON) @@ -189,20 +217,28 @@ def execute( Execute a SPARQL query in a given context. Parameters - --------- - query (QueryFile): the SPARQL query to run. - limit (int): the maximum number of results a query should return. - context (SPARQLWrapper): the SPARQL context. - tries (int): the maximum number of times the query should be executed - after failure. + ---------- + query : QueryFile + The SPARQL query to run. + + limit : int + The maximum number of results a query should return. + + context : SPARQLWrapper + The SPARQL context. + + tries : int + The maximum number of times the query should be executed after failure. Returns - -------- - dict: results of the query. + ------- + dict : the results of the query. """ def delay_in_seconds() -> int: - """How long to wait, in seconds, between executing repeat queries.""" + """ + How long to wait, in seconds, between executing repeat queries. + """ return int(math.ceil(10.0 / math.sqrt(tries))) if tries <= 0: @@ -230,12 +266,13 @@ def check_sparql_file(fpath: str) -> Path: Check meta information of SPARQL query file. Parameters - ------ - fpath (str): the file to validate. + ---------- + fpath : str + The file to validate. Returns - -------- - Path: the validated file. + ------- + Path : the validated file. """ path = Path(fpath) @@ -254,16 +291,19 @@ def check_positive_int(value: str, err_msg: str) -> int: Parameters ---------- - value (str): the value to be validated. - err_msg (str): used when value fails validation. + value : str + The value to be validated. + + err_msg : str + Used when value fails validation. Raises - ------- + ------ argparse.ArgumentTypeError Returns - -------- - int: the validated number. + ------- + int : the validated number. """ try: number = int(value) @@ -280,16 +320,17 @@ def check_limit(limit: str) -> int: Validate the 'limit' argument. Parameters - --------- - limit (str): the LIMIT to be validated. + ---------- + limit : str + The LIMIT to be validated. Raises - -------- + ------ argparse.ArgumentTypeError Returns - -------- - int: the validated LIMIT + ------- + int : the validated LIMIT. """ return check_positive_int(limit, "LIMIT must be an integer of value 1 or greater.") @@ -300,15 +341,16 @@ def check_timeout(timeout: str) -> int: Parameters ---------- - timeout (str): the timeout to be validated. + timeout : str + The timeout to be validated. Raises - -------- + ------ argparse.ArgumentTypeError Returns - --------- - int: the validated timeout. + ------- + int : the validated timeout. """ return check_positive_int( timeout, "timeout must be an integer of value 1 or greater." @@ -321,11 +363,12 @@ def main(argv=None) -> int: Parameters ---------- - argv : If set to None then argparse will use sys.argv as the arguments. + argv (default=None) + If set to None then argparse will use sys.argv as the arguments. Returns -------- - int: the exit status - 0: success, any other value - failure. + int : the exit status - 0 - success; any other value - failure. """ cli = argparse.ArgumentParser( description=f"run SPARQL queries from the '{PROJECT_ROOT}' project", @@ -450,7 +493,7 @@ def error_report(failures: list[QueryExecutionException]) -> None: Parameters ---------- - failures (list[QueryExecutionException]): failed queries. + failures (list[QueryExecutionException]) : failed queries. """ if not failures: return @@ -467,8 +510,11 @@ def success_report(successes: list[tuple[QueryFile, dict]], display: bool) -> No Parameters ---------- - successes (list[tuple[QueryFile, dict]]): successful queries. - display (bool): should there be output? + successes : list[tuple[QueryFile, dict]] + Successful queries. + + display : bool + Whether there should be an output or not. """ if not (display and successes): return