add/update docstrings

Author: fnmeyer

sysrsync/command_maker.py

@@ -17,6 +17,34 @@ def get_rsync_command(source: str,
                       private_key: Optional[str] = None,
                       rsh_port: Optional[int] = None,
                       strict_host_key_checking: Optional[bool] = None) -> List[str]:
+    """
+    Generates the rsync command with the specified options for synchronizing files and
+        directories.
+
+    Args:
+        source (str): The source directory or file path.
+        destination (str): The destination directory or file path.
+        source_ssh (Optional[str], optional): The SSH prefix for the source. Defaults
+            to None.
+        destination_ssh (Optional[str], optional): The SSH prefix for the destination.
+            Defaults to None.
+        exclusions (Optional[Iterable[str]], optional): The exclusions to be applied
+            during synchronization. Defaults to None.
+        sync_source_contents (bool, optional): Whether to sync the contents of the
+            source directory. Defaults to True.
+        options (Optional[Iterable[str]], optional): Additional rsync options. Defaults
+            to None.
+        private_key (Optional[str], optional): The path to the private key file for SSH
+            authentication. Defaults to None.
+        rsh_port (Optional[int], optional): The port number to use for the SSH
+            connection. Defaults to None.
+        strict_host_key_checking (Optional[bool], optional): Whether to perform strict
+            host key checking. Defaults to None.
+
+    Returns:
+        List[str]: A list containing the rsync command and its options for
+            synchronizing files and directories.
+    """
     if source_ssh is not None and destination_ssh is not None:
         raise RemotesError()
 

sysrsync/exceptions.py

@@ -1,14 +1,35 @@
 class RemotesError(Exception):
+    """
+    Exception raised when both the source and destination are remote.
+
+    Attributes:
+        message: The error message indicating that the source and destination cannot
+            both be remote.
+    """
+
     def __init__(self):
         message = 'source and destination cannot both be remote'
         super().__init__(message)
 
 
 class RsyncError(Exception):
+    """
+    Exception raised for errors related to rsync operations.
+    """
     pass
 
 
 class PrivateKeyError(Exception):
+    """
+    Exception raised when a private key file does not exist.
+
+    Args:
+        key_file: The path to the non-existent private key file.
+
+    Attributes:
+        message: The error message indicating that the private key file does not exist.
+    """
+
     def __init__(self, key_file):
         message = f'Private Key File "{key_file}" does not exist'
         super().__init__(message)

sysrsync/helpers/directories.py

@@ -2,6 +2,17 @@
 
 
 def get_directory_with_ssh(directory: str, ssh: Optional[str]) -> str:
+    """
+    Returns the directory path with SSH prefix if SSH is provided.
+
+    Args:
+        directory (str): The directory path.
+        ssh (Optional[str]): The SSH prefix. Defaults to None.
+
+    Returns:
+        str: The directory path with SSH prefix if SSH is provided, otherwise the
+            directory path itself.
+    """
     if ssh is None:
         return directory
 
@@ -10,6 +21,19 @@ def get_directory_with_ssh(directory: str, ssh: Optional[str]) -> str:
 
 def sanitize_trailing_slash(source_dir, target_dir, sync_sourcedir_contents=True):
     # type: (str, str, bool) -> Tuple[str, str]
+    """
+    Sanitizes the trailing slashes in the source and target directories.
+
+    Args:
+        source_dir (str): The source directory path.
+        target_dir (str): The target directory path.
+        sync_sourcedir_contents (bool, optional): Whether to sync the contents of the
+            source directory. Defaults to True.
+
+    Returns:
+        Tuple[str, str]: A tuple containing the sanitized source directory path and the
+            sanitized target directory path.
+    """
     target_dir = strip_trailing_slash(target_dir)
 
     if sync_sourcedir_contents is True:
@@ -24,9 +48,29 @@ def strip_trailing_slash(directory: str) -> str:
     return (directory[:-1]
             if directory.endswith('/')
             else directory)
+    """
+    Strips the trailing slash from the directory path if it exists.
+
+    Args:
+        directory (str): The directory path.
+
+    Returns:
+        str: The directory path without the trailing slash, if present. Otherwise,
+            returns the directory path as is.
+    """
 
 
 def add_trailing_slash(directory: str) -> str:
     return (directory
             if directory.endswith('/')
             else f'{directory}/')
+    """
+    Adds a trailing slash to the directory path if it doesn't already have one.
+
+    Args:
+        directory (str): The directory path.
+
+    Returns:
+        str: The directory path with a trailing slash, if it doesn't already have one.
+            Otherwise, returns the directory path as is.
+    """

sysrsync/helpers/iterators.py

@@ -14,5 +14,15 @@ def flatten(input_iter: Iterable[Any]) -> List[Any]:
     list_of_lists = (element if isinstance(element, Iterable)
                      else [element]
                      for element in input_iter)
+    """
+    Flattens an iterable by converting nested iterables into a single flat list.
+
+    Args:
+        input_iter (Iterable[Any]): The input iterable.
+
+    Returns:
+        List[Any]: A list containing all the elements from the input iterable, with
+            nested iterables flattened.
+    """
 
     return reduce(iconcat, list_of_lists, [])

sysrsync/helpers/rsync.py

@@ -7,13 +7,38 @@
 
 
 def get_exclusions(exclusions: Iterable[str]) -> Iterable[str]:
+    """
+    Generates a list of rsync exclusion arguments based on the provided exclusions.
+
+    Args:
+        exclusions (Iterable[str]): The exclusions to be used for generating the rsync
+            exclusion arguments.
+
+    Returns:
+        Iterable[str]: A list of rsync exclusion arguments, where each exclusion is
+            prefixed with '--exclude'.
+    """
     return flatten((('--exclude', exclusion)
                     for exclusion in exclusions
                     if exclusion != '--exclude'))
 
 
 def get_rsh_command(private_key: Optional[str] = None, port: Optional[int] = None, strict_host_key_checking: Optional[bool] = None):
 
+    """
+    Generates the rsync remote shell (rsh) command with the specified options.
+
+    Args:
+        private_key (Optional[str], optional): The path to the private key file.
+            Defaults to None.
+        port (Optional[int], optional): The port number to use for the SSH connection.
+            Defaults to None.
+        strict_host_key_checking (Optional[bool], optional): Whether to perform strict
+            host key checking. Defaults to None.
+
+    Returns:
+        List[str]: A list containing the rsync rsh command and its options.
+    """
     args: List[str] = []
 
     if private_key is not None:

sysrsync/runner.py

@@ -6,6 +6,22 @@
 
 
 def run(cwd=os.getcwd(), strict=True, verbose=False, **kwargs):
+    """
+    Runs the rsync command with the specified options.
+
+    Args:
+        cwd (str, optional): The current working directory. Defaults to the current
+            directory.
+        strict (bool, optional): Whether to raise an exception if the rsync command
+            returns a non-zero exit code. Defaults to True.
+        verbose (bool, optional): Whether to print the rsync command before executing
+            it. Defaults to False.
+        **kwargs: Additional options to be passed to the `get_rsync_command` function.
+
+    Returns:
+        subprocess.CompletedProcess: The completed process object representing the
+            execution of the rsync command.
+    """
     rsync_command = get_rsync_command(**kwargs)
 
     rsync_string = ' '.join(rsync_command)
@@ -23,5 +39,16 @@ def run(cwd=os.getcwd(), strict=True, verbose=False, **kwargs):
 
 
 def _check_return_code(return_code: int, action: str):
+    """
+    Checks the return code of an action and raises an exception if it is non-zero.
+
+    Args:
+        return_code (int): The return code of the action.
+        action (str): The description of the action.
+
+    Raises:
+        RsyncError: If the return code is non-zero, an exception is raised with an
+            error message indicating the action and the return code.
+    """
     if return_code != 0:
         raise RsyncError(f"[sysrsync runner] {action} exited with code {return_code}")

test/test_directories_helper.py

@@ -4,38 +4,41 @@
 
 
 class TestDirectoriesHelper(unittest.TestCase):
+    """
+    Unit tests for the directories helper module.
+    """
     def test_strip_trailing_slash(self):
-        """test strip trailing slash"""
+        """Test the strip_trailing_slash function."""
         test_dir = '/a/'
         expect = '/a'
         result = directories.strip_trailing_slash(test_dir)
 
         self.assertEqual(expect, result)
 
     def test_skip_strip_trailing_slash(self):
-        """test skip strip trailing slash when not necessary"""
+        """Test skipping strip_trailing_slash when not necessary."""
         test_dir = '/a'
         result = directories.strip_trailing_slash(test_dir)
 
         self.assertEqual(result, test_dir)
 
     def test_add_trailing_slash(self):
-        """test add trailing slash"""
+        """Test the add_trailing_slash function."""
         test_dir = '/a'
         expect = '/a/'
         result = directories.add_trailing_slash(test_dir)
 
         self.assertEqual(expect, result)
 
     def test_skip_add_trailing_slash(self):
-        """test skip add trailing slash when not necessary"""
+        """Test skipping add_trailing_slash when not necessary."""
         test_dir = '/a/'
         result = directories.add_trailing_slash(test_dir)
 
         self.assertEqual(result, test_dir)
 
     def test_sanitize_trailing_slash(self):
-        """test sanitize trailing slash when syncing source contents"""
+        """Test sanitizing trailing slash when syncing source contents."""
         source, target = '/a', '/b/'
         expect_source, expect_target = '/a/', '/b'
         result_source, result_target = directories.sanitize_trailing_slash(
@@ -45,7 +48,7 @@ def test_sanitize_trailing_slash(self):
         self.assertEqual(expect_target, result_target)
 
     def test_sanitize_trailing_slash_no_action_needed(self):
-        """test sanitize trailing slash when syncing source contents when already sanitized"""
+        """Test sanitizing trailing slash when syncing source contents when already sanitized."""
         source, target = '/a/', '/b'
         expect_source, expect_target = '/a/', '/b'
         result_source, result_target = directories.sanitize_trailing_slash(
@@ -55,7 +58,7 @@ def test_sanitize_trailing_slash_no_action_needed(self):
         self.assertEqual(expect_target, result_target)
 
     def test_sanitize_trailing_slash_whole_source(self):
-        """test sanitize trailing slash when syncing whole source"""
+        """Test sanitizing trailing slash when syncing whole source."""
         source, target = '/a/', '/b/'
         expect_source, expect_target = '/a', '/b'
         result_source, result_target = directories.sanitize_trailing_slash(
@@ -65,7 +68,7 @@ def test_sanitize_trailing_slash_whole_source(self):
         self.assertEqual(expect_target, result_target)
 
     def test_sanitize_trailing_slash_whole_source_no_action_needed(self):
-        """test sanitize trailing slash when syncing whole source when already sanitized"""
+        """Test sanitizing trailing slash when syncing whole source when already sanitized."""
         source, target = '/a', '/b/'
         expect_source, expect_target = '/a', '/b'
         result_source, result_target = directories.sanitize_trailing_slash(
@@ -75,7 +78,7 @@ def test_sanitize_trailing_slash_whole_source_no_action_needed(self):
         self.assertEqual(expect_target, result_target)
 
     def test_dir_with_ssh(self):
-        """should compose string with ssh for rsync connection"""
+        """Test composing string with ssh for rsync connection."""
         directory = '/a'
         ssh = 'host'
         expect = 'host:/a'
@@ -84,7 +87,7 @@ def test_dir_with_ssh(self):
         self.assertEqual(result, expect)
 
     def test_dir_without_ssh(self):
-        """should return directory when ssh is None"""
+        """Test returning directory when ssh is None."""
         directory = '/a'
         ssh = None
         result = directories.get_directory_with_ssh(directory, ssh)

test/test_iterators_helper.py

@@ -4,21 +4,27 @@
 
 
 class TestIteratorsHelper(unittest.TestCase):
+    """
+    Unit tests for the iterators helper module.
+    """
     def test_list_flatten(self):
+        """Test the flatten function with a list input."""
         list_input = [1, [2, 3], [4]]
         expect = [1, 2, 3, 4]
         result = iterators.flatten(list_input)
 
         self.assertEqual(expect, result)
 
     def test_tuple_flatten(self):
+        """Test the flatten function with a tuple input."""
         tuple_input = (1, [2, 3], [4])
         expect = [1, 2, 3, 4]
         result = iterators.flatten(tuple_input)
 
         self.assertEqual(expect, result)
 
     def test_tuples_and_lists_list_flatten(self):
+        """Test the flatten function with a tuple input containing tuples and lists."""
         tuple_input = (1, (2, 3), [4])
         expect = [1, 2, 3, 4]
         result = iterators.flatten(tuple_input)