Edits to checkquery docstrings to standardize them

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