Merge pull request #55 from neuroinformatics-unit/add_pydocstyle_linting

Add docstring linting and update docstrings.

Author: JoeZiminski

fancylog/fancylog.py

@@ -1,9 +1,4 @@
-"""fancylog
-===============
-
-Wrapper around the standard logging module, with additional information.
-
-"""
+"""Wrapper around the standard logging module, with additional information."""
 
 import contextlib
 import logging
@@ -39,32 +34,51 @@ def start_logging(
     timestamp=True,
     logger_name=None,
 ):
-    """Prepares the log file, and then begins logging.
-
-    :param output_dir: Directory to save the log file
-    :param package: What python package are we logging?
-    :param variables: List of objects whose attributes we want to log at the
-    beginning of the log file
-    :param verbose: If true, all info (i.e. 'DEBUG') is printed to
-    console. Else, only 'INFO' and above. Default: True
-    :param file_log_level: What level of logging to print to file.
-    Default: 'DEBUG'
-    :param filename: Filename for log file. Default: 'package.__name__'
-    :param log_header: Header for the log file, if the args are written'
-    :param multiprocessing_aware: Log from multiple processes. Default: True
-    :param write_header: Write a header for the log file. Default: True
-    :param write_git: Write information about the git repository.
-    Default: True
-    :param write_cli_args: Log the command-line arguments. Default: True
-    :param write_variables: Write the attributes of selected objects.
-    Default: True
-    :param log_to_file: If True, write a log file, otherwise just print to
-    terminal.
-    :param log_to_console: Print logs to the console or not: Default: True
-    :param timestamp: If True, add a timestamp to the filename
-    :param logger_name: If None, logger uses default logger. Otherwise,
-        logger name is set to `logger_name`.
-    :return: Path to the logging file#
+    """Prepare the log file, and then begin logging.
+
+    Parameters
+    ----------
+    output_dir
+        Directory to save the log file.
+    package
+        What Python package are we logging?
+    variables
+        List of objects whose attributes we want to log at the
+        beginning of the log file.
+    verbose
+        If True, all info (i.e. 'DEBUG') is printed to console;
+        else only 'INFO' and above. Default: True
+    file_log_level
+        What level of logging to print to file. Default: 'DEBUG'
+    filename
+        Filename for log file. Default: 'package.__name__'
+    log_header
+        Header for the log file, if the args are written.
+    multiprocessing_aware
+        Log from multiple processes. Default: True
+    write_header
+        Write a header for the log file. Default: True
+    write_git
+        Write information about the git repository. Default: True
+    write_cli_args
+        Log the command-line arguments. Default: True
+    write_variables
+        Write the attributes of selected objects. Default: True
+    log_to_file
+        If True, write a log file; otherwise just print to terminal.
+    log_to_console
+        Print logs to the console or not. Default: True
+    timestamp
+        If True, add a timestamp to the filename.
+    logger_name
+        If None, logger uses default logger; otherwise, logger
+        name is set to `logger_name`.
+
+    Returns
+    -------
+    path
+        Path to the logging file.
+
     """
     output_dir = str(output_dir)
     print_log_level = "DEBUG" if verbose else "INFO"
@@ -107,6 +121,8 @@ def start_logging(
 
 
 class LoggingHeader:
+    """Manage and write the log header."""
+
     def __init__(
         self,
         file,
@@ -119,6 +135,10 @@ def __init__(
         write_variables=True,
         log_header=None,
     ):
+        """Initialize LoggingHeader and write header to the log file.
+
+        See start_logging() for parameters.
+        """
         self.program = program
 
         with open(file, "w", encoding="utf-8") as self.file:
@@ -132,6 +152,17 @@ def __init__(
                 self.write_variables(variable_objects)
 
     def write_git_info(self, program_name, header="GIT INFO"):
+        """Write information about the git repository state.
+
+        Parameters
+        ----------
+        program_name
+            The name of the installed package, to
+            locate and inspect its Git repository.
+        header
+            The section header to use. Default is "GIT INFO".
+
+        """
         self.write_separated_section_header(header)
         try:
             program_path = find_spec(program_name).submodule_search_locations[
@@ -163,11 +194,27 @@ def write_git_info(self, program_name, header="GIT INFO"):
             )
 
     def write_command_line_arguments(self, header="COMMAND LINE ARGUMENTS"):
+        """Write the command-line arguments used to run the script.
+
+        Parameters
+        ----------
+        header
+            Title of the section that will be written to the log file.
+
+        """
         self.write_separated_section_header(header)
         self.file.write(f"Command: {sys.argv[0]} \n")
         self.file.write(f"Input arguments: {sys.argv[1:]}")
 
     def write_variables(self, variable_objects):
+        """Write a section for variables with their values.
+
+        Parameters
+        ----------
+        variable_objects
+            A list of python objects, the attributes of which will be written.
+
+        """
         self.write_separated_section_header("VARIABLES", bottom_separator="\n")
         if hasattr(variable_objects[0], "__dict__"):
             self.write_variables_from_object_list(variable_objects)
@@ -176,10 +223,27 @@ def write_variables(self, variable_objects):
         self.write_separated_section_header("LOGGING")
 
     def write_variables_from_slot_type_list(self, variable_objects):
+        """Write variables and their values from a namedtuple-like object.
+
+        Parameters
+        ----------
+        variable_objects
+            An object with a `_asdict()` method (e.g., a namedtuple)
+            containing variables to write.
+
+        """
         for attr, value in variable_objects._asdict().items():
             self.file.write(f"{attr}: {value}\n")
 
     def write_variables_from_object_list(self, variable_objects):
+        """Write attributes of each object in a list.
+
+        Parameters
+        ----------
+        variable_objects
+            A list of objects whose attributes will be written to the file.
+
+        """
         for variable_object in variable_objects:
             self.file.write(f"\n{variable_object.__class__.__name__}:\n")
             for attr, value in variable_object.__dict__.items():
@@ -188,6 +252,19 @@ def write_variables_from_object_list(self, variable_objects):
                     self.file.write(f"{attr}: {value}\n")
 
     def write_log_header(self, output_dir, log_header):
+        """Write the log header.
+
+         The header includes time, output directory,
+         and current directory.
+
+        Parameters
+        ----------
+        output_dir
+            The path to the output directory to include in the log.
+        log_header
+            Optional custom header text. If None, defaults to "LOG".
+
+        """
         if log_header is None:
             log_header = "LOG"
         self.write_separated_section_header(log_header, top_sep=False)
@@ -207,18 +284,53 @@ def write_separated_section_header(
         top_separator="\n\n",
         bottom_separator="\n\n",
     ):
+        r"""Write a section header with optional top and bottom separators.
+
+        Parameters
+        ----------
+        section_header
+            The section header text to write.
+        top_sep
+            Whether to write the top separator before the section header.
+        bottom_sep
+            Whether to write the bottom separator after the section header.
+        top_separator
+            The string to use as the top separator. Default: "\\n\\n"
+        bottom_separator
+            The string to use as the bottom separator. Default: "\\n\\n"
+
+        """
         if top_sep:
             self.write_separator(separator=top_separator)
         self.write_section_header(section_header)
         if bottom_sep:
             self.write_separator(separator=bottom_separator)
 
     def write_separator(self, separator="\n\n\n"):
+        r"""Write a separator string to the file.
+
+        Parameters
+        ----------
+        separator
+            The separator string to write. Default: "\\n\\n\\n"
+
+        """
         self.file.write(separator)
 
     def write_section_header(
         self, section_header, lateral_separator="**************"
     ):
+        """Write a section header framed by a lateral separator.
+
+        Parameters
+        ----------
+        section_header
+            The section header text to write.
+        lateral_separator
+            The string used to frame the section header.
+            Default: "**************"
+
+        """
         self.file.write(
             f"{lateral_separator}  {section_header}  {lateral_separator}"
         )
@@ -231,15 +343,22 @@ def initialise_logger(
     log_to_console=True,
     logger_name=None,
 ):
-    """Sets up (possibly multiprocessing aware) logging.
-    :param filename: Where to save the logs to
-    :param print_level: What level of logging to print to console.
-    Default: 'INFO'
-    :param file_level: What level of logging to print to file.
-    Default: 'DEBUG'
-    :param log_to_console: Print logs to the console or not
-    :param logger_name: If None, logger uses default logger. Otherwise,
-    logger name is set to `logger_name`.
+    """Set up (possibly multiprocessing aware) logging.
+
+    Parameters
+    ----------
+    filename
+        Where to save the logs to.
+    print_level
+        What level of logging to print to console. Default: 'INFO'
+    file_level
+        What level of logging to print to file. Default: 'DEBUG'
+    log_to_console
+        Print logs to the console or not.
+    logger_name
+        If None, logger uses default logger. Otherwise, logger name
+        is set to `logger_name`.
+
     """
     if logger_name:
         logger = logging.getLogger(logger_name)
@@ -280,17 +399,23 @@ def setup_logging(
     log_to_console=True,
     logger_name=None,
 ):
-    """Sets up (possibly multiprocessing aware) logging.
-    :param filename: Where to save the logs to
-    :param print_level: What level of logging to print to console.
-    Default: 'INFO'
-    :param file_level: What level of logging to print to file.
-    Default: 'DEBUG'
-    :param multiprocessing_aware: Default: True
-    :param log_to_console: Print logs to the console or no.
-    Default: True
-    :param logger_name: If None, logger uses default logger. Otherwise,
-        logger name is set to `logger_name`.
+    """Set up (possibly multiprocessing-aware) logging.
+
+    Parameters
+    ----------
+    filename
+        Path to the file where logs will be saved.
+    print_level
+        Logging level for console output. Default is 'INFO'.
+    file_level
+        Logging level for file output. Default is 'DEBUG'.
+    multiprocessing_aware
+        If True, enables multiprocessing-safe logging. Default is True.
+    log_to_console
+        If True, logs will also be printed to the console. Default is True.
+    logger_name
+        Name of the logger to use. If None, the default logger is used.
+
     """
     logger = initialise_logger(
         filename,
@@ -328,8 +453,9 @@ def setup_logging(
 
 
 def disable_logging():
-    """Prevents any more logging. Saves remembering that logging.disable() with
+    """Prevent any more logging.
+
+    Saves remembering that logging.disable() with
     no argument doesn't work.
-    :return:
     """
     logging.disable(2**63 - 1)