Merge pull request #2 from fnmeyer/docstrings

Docstrings

Author: fnmeyer

end-to-end-tests/tests.py

@@ -1,3 +1,4 @@
+"""Test end-to-end functionality for sysrsync."""
 import inspect
 import os
 import sys
@@ -11,7 +12,10 @@
 
 
 class TestE2E(unittest.TestCase):
+    """Test end-to-end functionality."""
+
     def test_send_file(self):
+        """Test sending a file from local to remote."""
         sysrsync.run(source="end-to-end-tests/test-cases/test_file",
                      destination="/tmp/target_test_file",
                      destination_ssh="test@openssh-server",
@@ -20,6 +24,7 @@ def test_send_file(self):
                      strict_host_key_checking=False)
 
     def test_send_file_with_spaces(self):
+        """Test sending a file with spaces from local to remote."""
         sysrsync.run(source="end-to-end-tests/test-cases/file with spaces",
                      destination="/tmp/target_test_file",
                      destination_ssh="test@openssh-server",

setup.py

@@ -1,3 +1,4 @@
+"""Setup script for sysrsync."""
 import setuptools
 import toml
 

sysrsync/__init__.py

@@ -1,2 +1,3 @@
+"""sysrsync: A Python wrapper for rsync."""
 from .command_maker import *
 from .runner import run

sysrsync/command_maker.py

@@ -1,3 +1,4 @@
+"""Generates the rsync command."""
 import os
 import os.path
 from typing import Iterable, List, Optional
@@ -17,6 +18,32 @@ 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]:
+    """Generate 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,37 @@
+"""Exceptions for sysrsync."""
 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):
+        """Initialize the RemotesError exception."""
         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):
+        """Initialize the PrivateKeyError exception."""
         message = f'Private Key File "{key_file}" does not exist'
         super().__init__(message)

sysrsync/helpers/__init__.py

@@ -0,0 +1 @@
+"""Helpers for sysrsync."""

sysrsync/helpers/directories.py

@@ -1,7 +1,19 @@
+"""Directory helper functions for sysrsync."""
 from typing import Tuple, Optional
 
 
 def get_directory_with_ssh(directory: str, ssh: Optional[str]) -> str:
+    """
+    Return 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 +22,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:
@@ -21,12 +46,30 @@ def sanitize_trailing_slash(source_dir, target_dir, sync_sourcedir_contents=True
 
 
 def strip_trailing_slash(directory: str) -> str:
+    """
+    Strip 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.
+    """
     return (directory[:-1]
             if directory.endswith('/')
             else directory)
 
-
 def add_trailing_slash(directory: str) -> str:
+    """Add 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.
+    """
     return (directory
             if directory.endswith('/')
             else f'{directory}/')

sysrsync/helpers/iterators.py

@@ -1,3 +1,4 @@
+"""Iterator helper functions for sysrsync."""
 import collections
 
 if 'Iterable' in dir(collections):
@@ -11,6 +12,16 @@
 
 
 def flatten(input_iter: Iterable[Any]) -> List[Any]:
+    """
+    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.
+    """
     list_of_lists = (element if isinstance(element, Iterable)
                      else [element]
                      for element in input_iter)

sysrsync/helpers/rsync.py

@@ -1,3 +1,4 @@
+"""Generates rsync arguments based on the provided options for sysrsync."""
 import os
 from pathlib import Path
 from typing import Iterable, List, Optional
@@ -7,13 +8,35 @@
 
 
 def get_exclusions(exclusions: Iterable[str]) -> Iterable[str]:
+    """Generate 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):
-
+    """Generate 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

@@ -1,3 +1,4 @@
+"""Runs the rsync command with the specified options."""
 import os
 import subprocess
 
@@ -6,6 +7,21 @@
 
 
 def run(cwd=os.getcwd(), strict=True, verbose=False, **kwargs):
+    """Run 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,15 @@ def run(cwd=os.getcwd(), strict=True, verbose=False, **kwargs):
 
 
 def _check_return_code(return_code: int, action: str):
+    """Check 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}")